Consulta cobrança por externalRef

Consulta uma cobrança pelo externalRef informado na criação (POST /v1/charges). Útil quando você só guarda o ID do seu sistema e não o chargeId interno. Retorna a mesma estrutura de GET /v1/charges/:id.

GET/v1/charges/external-ref/:externalRef

Diferente do GET /v1/charges/:id, este endpoint exige o header X-Pix-Account-Id obrigatoriamente — externalRef só é único dentro de uma conta. Resposta tem o mesmo shape do GET por id, com externalRef sempre preenchido. depositSnapshot expõe a comunicação com o provider Pix em snake_case e é destinado a debugging.

Path params

externalRefObrigatório
string (≤ 64)
externalRef informado na criação da cobrança.

Headers

AuthorizationObrigatório
string
Bearer SUA_API_KEY
X-Pix-Account-IdObrigatório
string
ID da conta Pix proprietária da cobrança.

Exemplo de requisição

bash

curl https://api.staterpay.io/v1/charges/external-ref/fatura-2026-05-0001 \  -H "Authorization: Bearer SUA_API_KEY" \  -H "X-Pix-Account-Id: cmoxample0001qkxyzaccount"

Resposta

id
string
Identificador da cobrança.
pixAccountId
string
Conta Pix proprietária.
variant
"simple" | "debtor" | "cobv"
Variante.
status
"PENDING" | "PAID" | "EXPIRED" | "REFUNDED"
Estado atual.
amountCents
string
Valor em centavos.
txid
string
TXID Pix.
providerQrId
string
ID do QR no provider.
brCode
string
QR Code copia-e-cola (padrão BR Code).
imageBase64
string
PNG do QR em base64 cru.
imageUrl
string (URL)
URL pública da imagem PNG.
expiresAt
string (ISO-8601 UTC-3)
Quando o QR expira.
dueDate
string | null
Vencimento (cobv) — null nas demais variantes.
fineDate
string | null
Início da multa (cobv) — null nas demais.
debtorName
string | null
Nome do devedor (debtor/cobv).
debtorDocument
string | null
Documento do devedor (debtor/cobv).
debtorTypeDocument
"CPF" | "CNPJ" | null
Tipo do documento (debtor/cobv).
typeFine
"NONE" | "VALUE" | "PERCENT" | null
Tipo de multa (cobv).
fine
number | null
Valor/percentual da multa (cobv).
tag
string | null
Tag livre informada na criação.
externalRef
string
Referência externa (eco do path param).
endToEndId
string | null
EndToEndId da liquidação (preenchido após pagamento).
coreMovementId
string | null
Movimento contábil associado, quando pago.
paidAt
string (ISO-8601) | null
Quando foi paga.
payerName
string | null
Nome do pagador (após pagamento).
payerDocument
string | null
Documento mascarado do pagador.
payerInstitution
string | null
Instituição do pagador (razão social).
payerInstitutionIspb
string | null
ISPB (8 dígitos) da instituição do pagador.
refundEndToEndId
string | null
EndToEndId da devolução, se houve.
refundedAt
string (ISO-8601) | null
Quando foi devolvida.
refundedAmountCents
string
Valor devolvido (centavos). 0 quando não houve devolução.
depositSnapshot
object
Snapshot da requisição original e da resposta do provider Pix subjacente.
failureReason
string | null
Motivo de falha, quando aplicável.
createdAt
string (ISO-8601 UTC-3)
Criação.
updatedAt
string (ISO-8601 UTC-3)
Última atualização.

json

{  "id": "cmoxample0001qkxyzcharge",  "pixAccountId": "cmoxample0001qkxyzaccount",  "variant": "cobv",  "status": "PENDING",  "amountCents": "10000",  "txid": "837efc90cc554a42ab779c15f0f40092",  "providerQrId": "0000000000",  "brCode": "00020101021226920014br.gov.bcb.pix2570qrcode.staterpay.com.br/v2/qr/cob/837efc90-cc55-4a42-ab77-9c15f0f400925204000053039865802BR5921NOME EMPRESA LTDA6009SAO PAULO62070503***630459A8",  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAhIAAAISAQAAAACxRhsSAAA...",  "imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/837efc90cc554a42ab779c15f0f40092.png",  "expiresAt": "2026-05-09T21:00:00.000-03:00",  "dueDate": "2026-05-08T15:00:00.000Z",  "fineDate": "2026-05-08T15:00:00.000Z",  "debtorName": "Fulano de Tal",  "debtorDocument": "12345678900",  "debtorTypeDocument": "CPF",  "typeFine": "PERCENT",  "fine": 1,  "tag": "Mensalidade Maio/2026",  "externalRef": "fatura-2026-05-0001",  "endToEndId": null,  "coreMovementId": null,  "paidAt": null,  "payerName": null,  "payerDocument": null,  "payerInstitution": null,  "payerInstitutionIspb": null,  "refundEndToEndId": null,  "refundedAt": null,  "refundedAmountCents": "0",  "depositSnapshot": {    "request": {      "tag": "Mensalidade Maio/2026",      "variant": "cobv",      "amountCents": "10000"    },    "providerResponse": {      "fee": 0,      "tag": "Mensalidade Maio/2026",      "tax": null,      "fine": null,      "tx_id": "837efc90cc554a42ab779c15f0f40092",      "amount": 100,      "status": "NEW",      "worked": true,      "due_date": null,      "fine_date": null,      "type_fine": "NONE",      "endToEndId": "",      "qr_code_id": 0,      "debtor_name": "Fulano de Tal",      "payment_date": null,      "agency_number": "0001",      "type_document": "CPF",      "account_number": "123456",      "debtor_document": "12345678900",      "expiration_date": "2026-05-10T00:00:00.000Z",      "amount_chargeback": 0,      "base_64_image_url": "https://api.staterpay.com.br/v2/finance/image/qrcode/837efc90cc554a42ab779c15f0f40092.png",      "debtor_institution": null,      "pix_copy_and_paste": "00020101021226920014br.gov.bcb.pix2570qrcode...",      "debtor_institution_number": null    }  },  "failureReason": null,  "createdAt": "2026-05-07T18:35:37.165-03:00",  "updatedAt": "2026-05-07T18:35:37.165-03:00"}

URL base:https://api.staterpay.io

Consulta cobrança por externalRef

Consulta cobrança por externalRef

Path params

Headers

Exemplo de requisição

Resposta

On this page