Consultar cobrança

GET/v1/charges/:id

Devolve 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 da cobrança
StatusO que significa
PENDINGAguardando o pagamento.
PROCESSINGEm 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.
PAIDPaga. A partir daqui pode ir para DISPUTED, PARTIALLY_REFUNDED ou REFUNDED.
EXPIREDO prazo acabou sem pagamento.
CANCELEDCancelada antes do pagamento.
FAILEDO pagamento falhou (provider ou banco). Gera charge.failed.
DISPUTEDEm disputa (MED): o valor contestado está retido até a decisão.
PARTIALLY_REFUNDEDParte do valor voltou ao pagador (devolução ou MED perdido).
REFUNDEDTodo o valor voltou ao pagador.
UNDERPAID · OVERPAID · LATE_PAYMENTSó 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/cancel

Só 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.

Cancelar
curl -X POST https://api.averopay.io/v1/charges/ch_7Hq2Kd8Wf91a/cancel \
  -H "Authorization: Bearer sk_test_..."
Códigos de erro
CódigoHTTPQuando acontece
CHARGE_NOT_OPEN409A cobrança não está pendente, foi paga antes do cancelamento ou está em análise. error.details.status diz qual.
PROVIDER_UNAVAILABLE503O provedor não respondeu; a cobrança segue pendente. Tente de novo.
NOT_FOUND404Não existe nesta empresa e neste ambiente.

Rotas relacionadas

Rotas da cobrança
RotaO que devolve
GET /v1/chargesListar cobranças
GET /v1/charges/:id/refundsDevoluções da cobrança
GET /v1/charges/:id/disputesDisputas (MED) da cobrança (escopo disputes)