Consultar cobrança
GET/v1/charges/:idDevolve a cobrança como ela está agora. Use quando precisar de certeza antes de liberar um pedido, ou para mostrar o PIX copia e cola na sua própria tela. Escopo da chave: charges em read.
O recurso charge
idtextosempreId da cobrança, ch_…objecttextosempreSempre "charge".environmenttextosempre"test" ou "live", o ambiente da chave que criou.statustextosempreSituação de agora; veja a tabela abaixo.amount · currencytextosempreValor cobrado e a moeda.fee · nettextosempreTarifa da cobrança e o líquido (amount − fee).methodslistasempreMeios aceitos, ex.: ["PIX"].externalId · description · metadata · returnUrlváriospode ser nullO que você mandou na criação; null quando não mandou.expiresAtdatasempreAté quando o pagador pode pagar.paidAtdatapode ser nullQuando o pagamento foi confirmado; null antes disso.amountReceivedtextopode ser nullO que de fato entrou; null enquanto nada entrou. No PIX, igual a amount.amountRefundedtextosempreSoma das devoluções concluídas. O valor perdido num MED não entra aqui: ele fica na disputa.paymentLinkIdtextopode ser nullO link de pagamento que gerou a cobrança (plk_…); null quando criada pela API ou pelo painel.createdAtdatasempreQuando a cobrança foi criada.checkoutUrlURLsemprePágina de pagamento para mandar ao cliente. Só na API, não vem nos webhooks.customerobjetopode ser nullO pagador como você mandou, normalizado (documento sem pontuação). Só na API.attemptobjetopode ser nullA forma de pagamento criada: id (pa_…), method e status. Enquanto está pendente, instructions traz o PIX: kind "PIX", emv (o copia e cola, que também é o conteúdo do QR code) e expiresAt. Só na API.
Os webhooks charge.* trazem o mesmo recurso em data, sem checkoutUrl, customer e attempt. Cobrança de outra empresa ou do outro ambiente responde 404 NOT_FOUND, como se não existisse.
Status
| Status | O que significa |
|---|---|
PENDING | Aguardando o pagamento. |
PROCESSING | Em análise pela plataforma: o provedor não confirmou o pagamento nem a expiração. Não muda sozinha; espere antes de cobrar o mesmo pedido de novo. |
PAID | Paga. A partir daqui pode ir para DISPUTED, PARTIALLY_REFUNDED ou REFUNDED. |
EXPIRED | O prazo acabou sem pagamento. |
CANCELED | Cancelada antes do pagamento. |
FAILED | O pagamento falhou (provider ou banco). Gera charge.failed. |
DISPUTED | Em disputa (MED): o valor contestado está retido até a decisão. |
PARTIALLY_REFUNDED | Parte do valor voltou ao pagador (devolução ou MED perdido). |
REFUNDED | Todo o valor voltou ao pagador. |
UNDERPAID · OVERPAID · LATE_PAYMENT | Só em USDT (em breve): chegou menos, mais ou depois do prazo. |
Uma cobrança EXPIRED ou CANCELED ainda vira PAID se o provedor confirmar um pagamento feito no limite: o dinheiro entrou e vale o pagamento. Nesse caso o charge.paid chega depois do charge.expired ou do charge.canceled; decida pelo status mais recente.
Cancelar uma cobrança pendente
POST/v1/charges/:id/cancelSó cobrança PENDING. Antes de fechar, a plataforma pede o cancelamento ao provedor e consulta de novo: se o pagador já tinha pago, vale o pagamento e o cancelamento é recusado. Cancelar de novo devolve a cobrança cancelada. Escopo: charges em write; não usa Idempotency-Key. Gera charge.canceled.
curl -X POST https://api.averopay.io/v1/charges/ch_7Hq2Kd8Wf91a/cancel \
-H "Authorization: Bearer sk_test_..."| Código | HTTP | Quando acontece |
|---|---|---|
CHARGE_NOT_OPEN | 409 | A cobrança não está pendente, foi paga antes do cancelamento ou está em análise. error.details.status diz qual. |
PROVIDER_UNAVAILABLE | 503 | O provedor não respondeu; a cobrança segue pendente. Tente de novo. |
NOT_FOUND | 404 | Não existe nesta empresa e neste ambiente. |
Rotas relacionadas
| Rota | O que devolve |
|---|---|
GET /v1/charges | Listar cobranças |
GET /v1/charges/:id/refunds | Devoluções da cobrança |
GET /v1/charges/:id/disputes | Disputas (MED) da cobrança (escopo disputes) |