Stater Platform
API Reference

Consultar cobrança

GET /v1/charges/:id — detalhes da cobrança incluindo dados do pagador.

Consulta cobrança por id

Retorna a cobrança completa: imagem do QR, dados do devedor (em debtor/cobv), pagador (quando paga), endToEndId, e o snapshot da resposta do provider Pix.

GET/v1/charges/:id

depositSnapshot expõe a comunicação com o provider Pix subjacente em snake_case (campos como tx_id, due_date, base_64_image_url). Use os campos top-level (camelCase) na sua integração; depositSnapshot é destinado a debugging.

Path params

  • idObrigatório
    string
    Identificador da cobrança (cuid).

Headers

  • AuthorizationObrigatório
    string
    Bearer SUA_API_KEY

Exemplo de requisição

bash
curl https://api.staterpay.io/v1/charges/cmoxample0001qkxyzcharge \  -H "Authorization: Bearer SUA_API_KEY"

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 | null
    Referência externa informada na criação (≤ 64). Permite consultar via GET /v1/charges/external-ref/:externalRef.
  • 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

Listar cobranças

GET /v1/charges com paginação por cursor.

Consulta cobrança por externalRef

GET /v1/charges/external-ref/:externalRef — mesmo shape do GET por id.

On this page

Path paramsHeadersExemplo de requisiçãoResposta