[MARCA] Documentação

Cobranças

Cobranças Pix imediatas ou com vencimento (cobv), com QR Code dinâmico, Pix Copia e Cola e página de pagamento hospedada.

Criar cobrança

POST /v1/charges

Cria uma cobrança Pix junto ao banco e devolve o Pix Copia e Cola e o QR Code. O txid é gerado pela plataforma. Requer o escopo charges:write.

Cobrança com vencimento (cobv): informe due_date (e, opcionalmente, days_after_due, fine, interest, discount e rebate); o pagador passa a ser obrigatório. Vencimento em dia não útil é prorrogado para o primeiro dia útil. O valor final pago é calculado pelo banco do pagador na data do pagamento; due.amount_due_today é uma estimativa. O pagamento traz components com o detalhamento.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

CampoTipoDescrição
amount obrigatóriostring (valor)

Valor em reais, duas casas decimais, separador ponto.

expires_ininteger

Validade em segundos (de 1 minuto a 7 dias).

payerPayer
Campos de payer
CampoTipoDescrição
namestring
documentstring

CPF (11 dígitos) ou CNPJ (14 caracteres), somente dígitos/letras. Nas respostas, vem mascarado.

addressobject

Só para cobrança híbrida (boleto = true); não é devolvido nas respostas.

Campos de address
CampoTipoDescrição
street obrigatóriostring
number obrigatóriostring
complementstring
district obrigatóriostring
city obrigatóriostring
state obrigatóriostring
zip obrigatóriostring

CEP sem hífen.

descriptionstring

Texto exibido ao pagador no app do banco (solicitacaoPagador).

external_refstring

Referência do seu sistema (ex.: número do pedido). Única por unidade.

additional_infoarray de object
allow_amount_changeboolean

Permite ao pagador alterar o valor (modalidadeAlteracao = 1). Não vale com due_date.

metadataMetadata

Até 20 pares chave/valor livres do integrador (chave ≤ 40, valor ≤ 500 caracteres). Não use para dados pessoais.

return_urlstring (uri)

Endereço da sua loja para o botão "Voltar para a loja" do checkout hospedado, depois do pagamento. Em produção, só https://.

due_datestring (date)

Vencimento (horário de Brasília). Torna a cobrança com vencimento (type: due); exige payer com nome e documento e não aceita expires_in. Entre hoje e 5 anos à frente.

days_after_dueinteger

Dias corridos após o vencimento em que ainda é possível pagar (validadeAposVencimento).

fineDueFine

Multa por atraso, cobrada uma vez após o vencimento (valor fixo ou percentual do valor original).

Campos de fine
CampoTipoDescrição
type obrigatóriostring
fixedpercent
value obrigatóriostring
interestDueInterest

Juros por dia de atraso a partir do vencimento (dias corridos, ou úteis com business_days).

Campos de interest
CampoTipoDescrição
type obrigatóriostring
amount_per_daypercent_per_daypercent_per_monthpercent_per_year
business_daysboolean
value obrigatóriostring
discountDueDiscount

Desconto para pagamento até o vencimento: fixo ou percentual até 3 datas (*_until_dates, com dates) ou por dia de antecipação (*_per_day_early, com value).

Campos de discount
CampoTipoDescrição
type obrigatóriostring
fixed_until_datespercent_until_datesamount_per_day_earlypercent_per_day_early
business_daysboolean

Só para desconto por dia de antecipação.

valuestring
datesarray de object
rebateDueFine

Abatimento concedido em qualquer data (valor fixo ou percentual do valor original).

Campos de rebate
CampoTipoDescrição
type obrigatóriostring
fixedpercent
value obrigatóriostring
boletoboolean

Cobrança híbrida: registra também um boleto com o mesmo vencimento e valor — o cliente paga pelo QR/Copia e Cola ou pela linha digitável, o que for mais fácil. Exige due_date e payer.address (o banco exige o endereço no registro). Pago por um meio, o outro deixa de valer. Pagamento por boleto não pode ser devolvido por Pix.

fiscal_documentsarray de FiscalDocument

Split tributário (preparação, reforma tributária — LC 214/2025): documentos fiscais da venda. A chave é conferida (tamanho, modelo, dígito verificador e, nos modelos de 44 posições, emitente = CNPJ da unidade). Hoje só é guardada; quando o split entrar em produção (2027), segue ao banco junto com a cobrança.

Respostas

  • 201 Cobrança criada e ativa.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
  • 422 Regra de negócio violada: `idempotency-key-reused`, `refund-exceeds-available`,
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.
  • 503 O banco está temporariamente indisponível. Repita com a mesma `Idempotency-Key` após `Retry-After`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/charges" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "149.90",
  "expires_in": 3600,
  "description": "Pedido 10293 — Loja Exemplo",
  "external_ref": "pedido-10293",
  "payer": {
    "name": "Maria Souza",
    "document": "12345678909"
  },
  "metadata": {
    "canal": "site",
    "cupom": "PRIMAVERA10"
  }
}'

Identificador nos logs: api.charges.create

Listar cobranças

GET /v1/charges

Requer o escopo charges:read.

Parâmetros

NomeOndeTipoDescrição
limitconsultainteger
starting_afterconsultastringCursor — ID do último objeto da página anterior.
ending_beforeconsultastringCursor — ID do primeiro objeto da página seguinte.
created_gteconsultastring (date-time)
created_lteconsultastring (date-time)
statusconsultaChargeStatus
external_refconsultastring
txidconsultastring

Respostas

  • 200 Lista paginada de cobranças.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/charges?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.charges.list

Consultar cobrança

GET /v1/charges/{charge_id}

Retorna a cobrança com o status atualizado. Use esta consulta como confirmação antes de liberar mercadoria. Requer o escopo charges:read.

Parâmetros

NomeOndeTipoDescrição
charge_id obrigatóriocaminhostring

Respostas

  • 200 Cobrança.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/charges/ch_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.charges.retrieve

Cancelar cobrança

POST /v1/charges/{charge_id}/cancel

Cancela uma cobrança active. Um Pix pago após o cancelamento é registrado como pagamento unmatched (ver Pagamentos). Requer o escopo charges:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
charge_id obrigatóriocaminhostring

Respostas

  • 200 Cobrança cancelada.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.
  • 503 O banco está temporariamente indisponível. Repita com a mesma `Idempotency-Key` após `Retry-After`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/charges/ch_01J9Z3F0A1B2C3D4E5F6G7H8J9/cancel" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.charges.cancel