Buscar cobrança pela referência
Retorna a cobrança da sua conta que tem o externalReference informado, para ligar o pedido à cobrança.
apiKeyAuthorizationBearer <token>Chave de API gerada no painel: Authorization: Bearer <chave>.
externalReference*stringO externalReference enviado na criação. Comparação exata, com maiúsculas e minúsculas.
length <= 255A cobrança encontrada. Quando nenhuma cobrança da conta tem essa
referência, a resposta também é 200, com corpo vazio.
application/json- response
Cobrança completa. É a resposta da criação sem tentativa (sem
paymentMethod, ou com CREDIT_CARD) e da busca pela referência.
id?stringId da cobrança (ULID, 26 caracteres).
kind?stringTipo da cobrança. SALE para cobrança avulsa.
status?ChargeStatusStatus da cobrança.
PENDING: aguardando pagamento.PARTIAL: recebeu menos que o valor e continua aberta. Só ocorre em cripto. Não é pago.PAID: paga.EXPIRED: prazo vencido sem pagamento.CANCELED: cancelada.FAILED: falhou.REFUNDED: reembolsada.RETAINED: o valor foi retido pela plataforma.
"PENDING""PARTIAL""PAID""EXPIRED""CANCELED""FAILED""REFUNDED""RETAINED"grossAmount?stringValor cobrado do pagador.
^\d{1,20}\.\d{2}$netAmount?stringValor que fica com você depois das tarifas. É a base do split.
^\d{1,20}\.\d{2}$refundedAmount?stringTotal já reembolsado.
^\d{1,20}\.\d{2}$currency?stringMoeda da cobrança.
externalReference?|O valor enviado na criação.
description?|O valor enviado na criação.
expiresAt?|Prazo para pagar.
date-timecustomerMeta?|Dados do pagador, com documento, e-mail e telefone mascarados.
passthroughFees?booleanO valor enviado na criação.
splitConfig?array<>|O split enviado na criação, ou null.
splitSettlement?|Como o valor foi dividido, em centavos. null até a cobrança ser paga.
canRefund?booleanSe a cobrança aceita reembolso agora.
canRefundPartial?booleanSe a cobrança aceita reembolso de parte do valor.
checkoutUrl?stringLink do checkout. Envie ao pagador. Vem só na resposta da criação.
uricreatedAt?stringCriação, em UTC.
date-timeupdatedAt?stringÚltima alteração, em UTC.
date-timecurl -X GET 'https://api.gates2b.com/charge?externalReference=string'{ "id": "01JC8Z3R5W7Y9A1C3E5G7J9K2M", "kind": "SALE", "status": "PAID", "grossAmount": "49.90", "netAmount": "47.35", "refundedAmount": "0.00", "currency": "BRL", "externalReference": "pedido-0001", "description": "Assinatura mensal", "expiresAt": "2026-11-30T23:59:59.000Z", "customerMeta": { "name": "Maria da Silva", "document": "123******09", "email": "cl*****@example.com", "phone": null }, "passthroughFees": false, "splitConfig": null, "splitSettlement": null, "canRefund": true, "canRefundPartial": true, "createdAt": "2026-10-22T14:00:00.000Z", "updatedAt": "2026-10-22T14:03:12.000Z"}Não encontrada é 200 com corpo vazio
Quando nenhuma cobrança da conta tem a referência, a resposta é 200 sem corpo, não 404. Verifique se o corpo
está vazio antes de ler o JSON.
Regras
- A comparação é exata:
Pedido-1não encontrapedido-1. Para busca parcial, usesearchem Listar cobranças. - A busca só olha as cobranças da conta da chave de API.
- A API não impede duas cobranças com o mesmo
externalReference. Se houver mais de uma, a resposta traz só uma, sem ordem garantida. Use uma referência única por cobrança, ou liste comsearchpara ver todas. - Para ver o pagamento confirmado (quem pagou, identificador PIX), consulte o
idretornado em Consultar cobrança.