Skip to main content
GET
Esta rota devolve uma cobrança (charge) pelo seu identificador, com o status atual e todos os detalhes. Ela é a fonte de verdade para decidir o que fazer com um pedido: liberar o produto, cancelar, marcar como estornado ou como em disputa. É também a única rota que mostra a divisão do valor entre as contas (splits) e as tentativas agrupadas (groupCharges).

Quando usar

Antes de chamar

  • Tenha uma chave secreta do mesmo ambiente em que a cobrança foi criada: sk_test_ para cobranças de teste e sk_ para cobranças reais (Credenciais e ambientes).
  • Tenha o id da cobrança, devolvido por POST /v1/charges e presente em todos os webhooks de cobrança (data.id).

Parâmetros de caminho

string
required
Identificador único da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.

Respostas

A resposta 200 é o objeto de cobrança. Trate a ausência de qualquer campo.
A API não usa 404 nesta rota: para um id que não existe, ela responde hoje 200 com corpo vazio. Trate corpo vazio como “cobrança não encontrada” e confira se a chave é do mesmo ambiente e da mesma conta da cobrança.
string
Identificador único da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
string
Status da cobrança: paid, pending, refused, failed, refunded, in_analysis, authentication_required, pre_chargeback ou chargeback. Ex.: paid.
boolean
true enquanto a cobrança está bloqueada por uma disputa (MED no Pix ou chargeback no cartão). O status continua paid durante o bloqueio. Use este campo para saber se a cobrança está bloqueada.
string | null
Data e hora do bloqueio, em ISO 8601. Continua preenchido depois da liberação, por isso não serve para saber se a cobrança ainda está bloqueada.
string | null
Motivo do bloqueio, em texto livre preenchido pela equipe Finvia (pode indicar MED ou chargeback). Pode vir vazio e é apagado na liberação.
boolean | null
Presente em cobranças com alerta de pré-chargeback (status pre_chargeback). true: o valor já foi estornado ao comprador como parte do tratamento do alerta. false: disputa aberta, sem estorno. null quando não há alerta.
string | null
Motivo ou referência informado no alerta de pré-chargeback. Ex.: Chargeback - NSU 123456789.
string | null
Identificador da cobrança no sistema do provedor de pagamento (PSP). Ex.: ch_123456789.
number
Valor total da cobrança, em reais. Ex.: 100.5.
string
Moeda no padrão ISO 4217. Ex.: BRL.
number
Spread (taxa) aplicado à cobrança. Ex.: 2.5.
number
Valor líquido depois do spread. Ex.: 98.
object
Cliente que pagou a cobrança.
object
Forma de pagamento usada. Em cobranças Pix, traz type pix. Em cartão (digitado, salvo ou Apple Pay):
string
Identificador da conta dona da cobrança. Ex.: 2vorkDcXyvzifL63YX09S9VqcnI.
object | null
Detalhes do pagamento. O formato muda conforme a forma de pagamento.
object[]
Divisão do valor entre as contas recebedoras. Aparece só nesta consulta (não vem na listagem nem na criação). Vem preenchida quando a cobrança teve split no POST ou quando a conta tem regra de split padrão para aquele método e moeda; nesse segundo caso, mesmo sem split na criação.
object[]
No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a cobrança principal do grupo, e as demais tentativas aparecem aqui, na consulta da principal.
object | null
Informações livres que você enviou na criação. Nesta resposta, as chaves voltam em camelCase: chaves enviadas em snake_case chegam convertidas. Veja Metadata. Ex.: {"orderId": "ORD-123"}.
string | null
Data e hora do pagamento, em ISO 8601. Ex.: 2026-10-15T14:30:00Z.
string
Data e hora da criação, em ISO 8601.
string
Data e hora da última atualização, em ISO 8601.

O que splitAmount mostra

Com base net (o padrão): Com base gross, mostra sempre percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga.
Para o desenvolvedor: na conciliação do split, confira destinyMerchantId e splitPercentage e compare splitAmount com valor líquido × percentual. Enquanto a simulação de antecipação estiver ativa, o valor mostrado é menor que esse cálculo.
Para o negócio: use o status desta consulta como regra para liberar pedidos. paid libera; pending aguarda; refused e failed encerram a tentativa; refunded cancela o pedido. Uma cobrança paid com isBlocked: true está em disputa: o valor fica no saldo bloqueado até a decisão. Em pre_chargeback, olhe chargebackAlertRefunded: true significa que o valor já foi devolvido ao comprador.

Como decidir pelo status

Exemplos por caso de uso

Ao receber charge.paid, confirme o status antes de liberar o pedido.

Erros comuns

Veja também

Listar cobranças

Várias cobranças com filtros por status, data e busca.

Estornar cobrança

Estorno total de uma cobrança paga.

Bloqueio, chargeback e MED

O que significam isBlocked e o bloqueio de saldo.

Split

Prazos e regras do repasse.