Cobranças

Criar cobrança Pix

POST/v1/chargescharges:write

Envie sempre o cabeçalho Idempotency-Key. Se a conexão cair, repita a chamada com a mesma chave: você recebe o mesmo recurso, nunca um segundo. Como repetir com segurança

Ciclo de vida

CREATINGPENDINGQR pronto
PENDINGPAIDcharge.paid
PENDINGEXPIRED · CANCELED · FAILEDvence em expires_at
PAIDREVERSEDMED

Cabeçalhos

Authorizationstringobrigatório

Bearer seguido da sua chave: gw_test_ em teste, gw_live_ em produção.

Idempotency-Keystring · 8–128obrigatório

Identificador único da tentativa, entre 8 e 128 caracteres ASCII visíveis.

Corpo da requisição

external_idstring · 1–128obrigatório

amount_centsinteger · mín. 1obrigatório

Valor inteiro positivo em centavos.

exemplo 4990 = R$ 49,90

payerobjectobrigatório

2 campos

namestring · 2–120obrigatório

documentstring · 11 dígitosobrigatório

CPF válido, somente dígitos.

descriptionstring · 1–255obrigatório

expires_in_secondsinteger · 300–604800opcionalNOVO

Por quanto tempo o QR aceita pagamento. Padrão 1800 (30 minutos). O vencimento efetivo volta em expires_at.

metadataobject · até 20 chavesopcionalNOVO

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

product_iduuidopcionalNOVO

Produto do catálogo vendido. amount_cents precisa ser o preço atual dele; senão a resposta é 422 product_unavailable.

Resposta 201

Cobrança criada. Normalmente o objeto completo; em falha de leitura imediata, o formato reduzido.

iduuid

external_idstring

method

PIX ou CARD (checkout no cartão).

PIXCARD

statusstring

CREATINGPENDINGPAIDFAILEDCANCELEDEXPIREDUNDER_REVIEWREVERSED

amount_centsinteger

Valor inteiro em centavos.

exemplo 4990 = R$ 49,90

fee_centsinteger

Valor inteiro em centavos.

exemplo 149 = R$ 1,49

net_amount_centsinteger

Valor inteiro em centavos.

exemplo 4841 = R$ 48,41

pixPixArtifact | null

3 campos

copy_pastestring

qr_code_urlurl | null

qr_code_base64string | null

cardobject | nullNOVO

Só em cobranças CARD. O link do checkout aparece enquanto a cobrança está PENDING. O valor pago fica a liberar até a liberação da venda no cartão.

2 campos

checkout_urlurl | null

checkout_expires_atdatetime | null

expires_atdatetime | null

paid_atdatetime | null

created_atdatetime

updated_atdatetime

settlementobject

3 campos

modestring | null

D0D1

sourcestring | null

GLOBALMERCHANTLEGACY

withdrawable_atdatetime | null

descriptionstring | nullNOVO

metadataobject · até 20 chavesNOVO

Pares chave-valor seus, até 20 chaves e 2 KB. Gravados uma vez na criação e devolvidos em toda consulta e webhook. Não guarde dados pessoais aqui.

product_iduuid | nullNOVO

Produto do catálogo que esta cobrança vendeu, quando criada a partir de um.

payerobject | nullNOVO

Quem você informou que pagaria, com o documento mascarado.

2 campos

namestring | null

document_maskedstring | null

Ex.: ***.456.789-**

paid_byobject | nullNOVO

Quem pagou, segundo o banco. Pode ser diferente de payer. null até o pagamento.

3 campos

namestring | null

document_maskedstring | null

Ex.: ***.456.789-**

bankstring | null

end_to_end_idstring | nullNOVO

ID fim a fim do Pix no Banco Central. null até o pagamento.

reversed_atdatetime | nullNOVO

Códigos de resposta

HTTP	Quando acontece
201	Cobrança criada. Normalmente o objeto completo; em falha de leitura imediata, o formato reduzido.
200	Cobrança existente recuperada sem artefato Pix disponível
202	Resultado da criação incerto; conciliação automática ou revisão manual
400	Requisição ou cursor inválido
401	Chave ausente, inválida ou sem o escopo exigido
403	Criação de cobrança desabilitada pela política efetiva de verificação da conta ou por um bloqueio operacional explícito. O campo error é merchant_not_operational.
409	Conflito de identificador externo, idempotência ou operação em andamento
422	Regra financeira impediu a operação
429	Limite de requisições ou limite operacional da conta excedido. Para error operation_limit_exceeded, reasons identifica os limites efetivos atingidos; Retry-After só é garantido para rate_limit_exceeded.
503	Serviço temporariamente indisponível

Cada código de erro está explicado em Erros.

Requisição

curl -X POST "https://api.mainumpay.com/v1/charges" \
  -H "Authorization: Bearer $MAINUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "external_id": "pedido-48213",
  "amount_cents": 4990,
  "description": "Plano Pro mensal",
  "payer": {
    "name": "Ana Souza",
    "document": "52998224725"
  },
  "expires_in_seconds": 1800,
  "metadata": {
    "pedido": "48213",
    "canal": "loja"
  }
}'

Resposta

{
  "id": "0192a7c4-5b1e-7d3a-9f10-6c2e8b4d1a77",
  "external_id": "pedido-48213",
  "method": "PIX",
  "status": "PENDING",
  "amount_cents": 4990,
  "fee_cents": 149,
  "net_amount_cents": 4841,
  "description": "Plano Pro mensal",
  "metadata": {
    "pedido": "48213",
    "canal": "loja"
  },
  "payer": {
    "name": "Ana Souza",
    "document_masked": "***.982.247-**"
  },
  "paid_by": null,
  "end_to_end_id": null,
  "expires_at": "2026-09-24T15:02:11.000Z",
  "paid_at": null,
  "reversed_at": null,
  "created_at": "2026-09-24T14:32:11.000Z",
  "updated_at": "2026-09-24T14:32:11.000Z",
  "settlement": {
    "mode": "D0",
    "source": "MERCHANT",
    "withdrawable_at": null
  },
  "pix": {
    "copy_paste": "00020101021226870014br.gov.bcb.pix2565qr.mainumpay.com/v2/cobv/9d3e4a6f520400005303986540649.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1F3",
    "qr_code_url": null,
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"
  },
  "card": null,
  "product_id": null,
  "request_id": "req_0192a7c4-5b20-7c11-8e4f-2b9d0c6a3e58"
}

Cobrança criada. Normalmente o objeto completo; em falha de leitura imediata, o formato reduzido.