VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagar.me

Cobranças do Pagar.me

Lista cobranças, captura cartão autorizado, estorna total ou parcialmente e mostra como o valor foi dividido entre os recebedores.

Uma cobrança é o pedido de pagamento feito ao gateway para um pedido da loja. Estas rotas mostram as cobranças e permitem as três ações financeiras: capturar (efetivar um cartão que só foi autorizado), estornar (devolver o dinheiro) e ver o split (como o valor foi repartido). Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

Duas listas de pagamentos

A lista de cobranças (/charges) mostra o registro do caminho antigo de pagamento. O checkout atual grava em transações. Um pedido recente costuma aparecer em transações e não aqui. O estorno funciona para os dois; a captura e o split só para cobranças.

Listar cobranças

GET/api/v1/admin/pagarme/chargesAdmin

Lista as cobranças do Pagar.me

Parâmetros de consulta

statusstring
pendingpaidfailedcanceledrefundedchargeback
Filtra pelo status gravado na cobrança. A comparação é exata com o valor armazenado; se não voltar nada, confira como o status aparece nos registros da loja.
payment_methodstring
credit_cardboletopix
Filtra pelo método.
order_iduuid
Só as cobranças deste pedido.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso volta para 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/pagarme/charges?payment_method=pix&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobranças devolvidas
json
{
  "charges": [
    {
      "id": "6db0e009-9448-4732-863a-06ba74c9bd04",
      "order_id": "a5d86a76-7d89-4646-8edc-29447aa2ec37",
      "pagarme_id": "ch_MVDQA29sOcMGxG5g",
      "payment_method": "pix",
      "status": "failed",
      "amount": 9000,
      "pix_expiry": "2026-07-13T23:52:27Z",
      "created_at": "2026-07-13T22:52:27Z",
      "updated_at": "2026-07-13T22:52:27Z"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

chargesarray
Cobranças da página. Pode vir null quando vazio.
totalinteger
Total que casa com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página aplicado.
total_pagesinteger
Total de páginas.
iduuid
Id interno da cobrança. É o que captura e splits recebem.
order_iduuid
Pedido.
pagarme_idstring
Id da cobrança no gateway (ch_...).
payment_methodstring
credit_cardboletopix
Método.
statusstring
pendingpaidfailedcanceledrefundedchargeback
Status da cobrança.
amountinteger
Valor em centavos.
boleto_pdfstring
Endereço do boleto em PDF. Só em boleto.
boleto_barcodestring
Código de barras do boleto. Só em boleto.
boleto_linestring
Linha digitável. Só em boleto.
boleto_expirystring
Vencimento do boleto, RFC 3339. Só em boleto.
pix_qr_codestring
Código "copia e cola" do PIX. Só em PIX.
pix_qr_code_urlstring
Imagem do QR code. Só em PIX.
pix_expirystring
Expiração do PIX, RFC 3339. Só em PIX.
card_brandstring
Bandeira. Só em cartão.
card_last_digitsstring
Últimos 4 dígitos. Só em cartão.
paid_atstring
Quando foi paga, RFC 3339. Ausente enquanto não paga.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
401Sem token{"error":"missing authorization header"}
403Sem privilégio{"error":"insufficient privileges","privilege_required_any":["manage_payments","view_payments"]}
403Módulo desligado{"error":"module_disabled","module":"pagarme"}
500Falha de consulta (inclui order_id que não é UUID){"error":"failed to list charges","detail":"..."}

Capturar uma cobrança

Com cartão, o dinheiro pode ser apenas reservado (autorizado) e só sai da conta do cliente na captura. Esta rota captura uma cobrança que está autorizada, no valor total ou em parte, e marca a cobrança como paga.

POST/api/v1/admin/pagarme/charges/{id}/captureAdmin

Captura uma cobrança autorizada

Parâmetros de caminho

iduuidobrigatório
Id interno da cobrança (o id da listagem, não o ch_...).

Corpo da requisição (opcional)

amountintegerpadrão: 0
Valor a capturar, em centavos. 0 ou ausente captura o valor total.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/pagarme/charges/6db0e009-9448-4732-863a-06ba74c9bd04/capture" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 0 }'

Resposta

200Cobrança capturada
json
{
  "id": "6db0e009-9448-4732-863a-06ba74c9bd04",
  "order_id": "a5d86a76-7d89-4646-8edc-29447aa2ec37",
  "pagarme_id": "ch_MVDQA29sOcMGxG5g",
  "payment_method": "credit_card",
  "status": "paid",
  "amount": 9000,
  "card_brand": "visa",
  "card_last_digits": "4242",
  "paid_at": "2026-10-11T23:05:12Z",
  "created_at": "2026-10-11T23:04:30Z",
  "updated_at": "2026-10-11T23:05:12Z"
}

A resposta é a cobrança já atualizada, com os campos da listagem.

Erros

StatusQuandoCorpo
500Cobrança inexistente, id que não é UUID, gateway recusou ou fora do ar{"error":"failed to capture charge","detail":"pagarme: capture api returned 422: ..."}
O erro do gateway vem no detail

Quando o gateway recusa a captura (por exemplo, a cobrança já foi capturada), o detail traz o código HTTP e um trecho da resposta dele. Se a chamada ao gateway deu certo mas a atualização local falhou, a cobrança fica capturada no gateway e o erro é apenas registrado: confira o estado antes de repetir.

Estornar uma cobrança

Devolve o dinheiro ao cliente, no valor total que ainda resta estornar ou em parte. Só cobranças pagas podem ser estornadas. Um estorno parcial mantém a cobrança como paga, para que o restante possa ser estornado depois; o total estornado fica em refund_amount_cents (transações).

POST/api/v1/admin/pagarme/charges/{id}/refundAdmin

Estorna uma cobrança paga

Parâmetros de caminho

idstringobrigatório
Id interno da cobrança (UUID) ou o id do gateway (ch_...). Este último é o que o checkout atual grava, e serve para estornar uma transação pelo seu charge_id.

Corpo da requisição (opcional)

amountintegerpadrão: 0
Valor a estornar, em centavos. 0 ou ausente estorna todo o saldo ainda não estornado. Não pode passar do saldo.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/pagarme/charges/ch_Z1dxXYKcNWcnw547/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2500 }'

Resposta

200Estorno feito
json
{
  "id": "6c1b45aa-1acd-4576-95ac-1c684454bd31",
  "order_id": "6c1b45aa-1acd-4576-95ac-1c684454bd31",
  "pagarme_id": "ch_Z1dxXYKcNWcnw547",
  "payment_method": "credit_card",
  "status": "paid",
  "amount": 68040,
  "card_brand": "visa",
  "card_last_digits": "4242",
  "paid_at": "2026-07-14T06:52:31Z",
  "created_at": "2026-07-14T06:50:07Z",
  "updated_at": "2026-10-11T23:10:00Z"
}

A resposta é a cobrança relida depois do estorno. Num estorno parcial o status continua paid; no total ele passa para o estado de estornado.

Erros

StatusQuandoCorpo
500Cobrança não encontrada{"error":"failed to refund charge","detail":"pagarme: charge ch_x not found"}
500Cobrança que não está paga{"error":"failed to refund charge","detail":"pagarme: cannot refund charge with status \"pending\", must be 'paid'"}
500Valor acima do saldo{"error":"failed to refund charge","detail":"pagarme: refund amount 99999 exceeds charge amount 68040"}
500Gateway recusou ou fora do ar{"error":"failed to refund charge","detail":"pagarme: refund api returned 4xx: ..."}
Estorno não tem desfazer, e o erro pode vir depois do dinheiro sair

Se o gateway já devolveu o dinheiro e só a atualização local falhou, a plataforma registra o problema em log e ainda responde 200: o estorno foi feito. Já um 500 do gateway significa que nada foi estornado. Antes de repetir uma chamada que deu erro, consulte a transação e confira refund_amount_cents, para não estornar duas vezes.

Ver o split de uma cobrança

Mostra como o valor da cobrança foi dividido entre os recebedores (os sellers e a comissão da loja).

GET/api/v1/admin/pagarme/charges/{id}/splitsAdmin

Mostra o split de uma cobrança

Parâmetros de caminho

iduuidobrigatório
Id interno da cobrança.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/pagarme/charges/6db0e009-9448-4732-863a-06ba74c9bd04/splits" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Split devolvido
json
{
  "splits": [
    {
      "recipient_id": "re_cm0sellerexampleexample0001",
      "amount": 8100,
      "type": "flat",
      "percentage": 0,
      "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de"
    },
    {
      "recipient_id": "re_cm0exampleexampleexample0",
      "amount": 900,
      "type": "percentage",
      "percentage": 1000,
      "is_marketplace": true
    }
  ],
  "total": 2
}

Campos da resposta

splitsarray
Linhas do split, primeiro os sellers e por último a comissão da loja. É null quando a cobrança não teve split.
totalinteger
Quantidade de linhas.
recipient_idstring
Recebedor no gateway (re_...).
amountinteger
Valor da linha em centavos. Em linhas percentuais, o valor já calculado sobre o total.
typestring
flatpercentage
Valor fixo ou percentual.
percentageinteger
Percentual em pontos-base (1000 = 10%). 0 em linhas fixas.
vendor_iduuid
Seller da linha. Ausente na linha da loja.
is_marketplaceboolean
true na linha da comissão da loja.

Erros

StatusQuandoCorpo
500Falha de consulta, ou id que não é UUID{"error":"failed to get charge splits","detail":"..."}

Um UUID válido sem split devolve {"splits":null,"total":0}.

Veja também

  • Transações
  • Recebedores
  • Conciliação
Anterior
Transações do Pagar.me
Próxima
Recebedores do split
Nesta página
  • Listar cobranças
  • Exemplo de requisição
  • Resposta
  • Erros
  • Capturar uma cobrança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estornar uma cobrança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver o split de uma cobrança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também