Stater Platform

Consultar cobrança Pix

GET /accounts/:accountId/charges/:chargeId — estado atualizado e dados do pagador após liquidação.

Consultar cobrança Pix

Retorna o estado atualizado de uma cobrança. Use pra checar se foi paga (status PAID), expirou (EXPIRED) ou estornada (REFUNDED) — inclui os dados do pagador real depois da liquidação.

GET/accounts/:accountId/charges/:chargeId

Mesmo endpoint pras 3 variantes (simple/debtor/cobv) — campos não aplicáveis vêm como null. Após status=PAID, paidAt + endToEndId + payerName/Document/Institution são preenchidos (o pagador real pode ser diferente do debtor* esperado, especialmente em simple/debtor que aceitam qualquer pagador). Após status=REFUNDED, refundEndToEndId/refundedAt/refundedAmountCents refletem o estorno. Para acompanhamento ativo prefira webhooks; polling moderado (1-5s) é aceitável enquanto status=PENDING.

Path params

  • accountIdObrigatório
    string (UUID)
    ID da conta recebedora da cobrança.
  • chargeIdObrigatório
    string (cuid)
    ID retornado em chargeId pela criação da cobrança.

Headers

  • AcceptObrigatório
    string
    application/json
  • AuthorizationObrigatório
    string
    Bearer <token> — JWT de /authenticate.
  • X-Tenant-IdObrigatório
    string (UUID)
    Identificador do tenant.

Exemplo de requisição

bash
curl -X GET https://baas.staterpay.io/accounts/00000000-0000-0000-0000-000000000010/charges/cmoxample0004qkxyzcharge \  -H "Accept: application/json" \  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>" \  -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000"

Resposta

  • id
    string (cuid)
    ID da cobrança (mesmo chargeId).
  • pixAccountId
    string (cuid)
    ID interno da conta Pix subjacente (sub-conta operacional).
  • variant
    "simple" | "debtor" | "cobv"
    Tipo da cobrança originalmente criada.
  • status
    "PENDING" | "PAID" | "EXPIRED" | "REFUNDED"
    Estado atual da cobrança.
  • txid
    string
    Identificador BCB embutido no brCode (32 hex).
  • amountCents
    string
    Valor original em centavos.
  • brCode
    string
    Payload Pix Copia e Cola.
  • imageBase64
    string
    PNG do QR Code em base64 (sem prefixo data:image).
  • imageUrl
    string
    URL pública do PNG do QR Code, hospedada pela Stater.
  • expiresAt
    string (ISO 8601)
    Quando a cobrança expira/expirou.
  • dueDate
    string (ISO 8601) | null
    Data de vencimento. Preenchido apenas em variant=cobv.
  • fineDate
    string (ISO 8601) | null
    Data de início da multa. Pode ser null mesmo em cobv (campo é opcional na criação).
  • debtorName
    string | null
    Nome do pagador esperado. null em variant=simple.
  • debtorDocument
    string | null
    CPF/CNPJ do pagador esperado. null em variant=simple.
  • debtorTypeDocument
    "CPF" | "CNPJ" | null
    Tipo do documento do pagador esperado. null em variant=simple.
  • typeFine
    "VALUE" | "PERCENT" | null
    Modo de cálculo da multa. null fora de variant=cobv ou quando sem multa.
  • fine
    number | null
    Valor/percentual da multa. null fora de variant=cobv ou quando sem multa.
  • tag
    string | null
    Identificador livre enviado na criação.
  • endToEndId
    string | null
    EndToEndId da liquidação. null enquanto status=PENDING; preenchido após PAID.
  • paidAt
    string (ISO 8601) | null
    Quando a cobrança foi paga. null enquanto status≠PAID.
  • payerName
    string | null
    Nome do pagador real que liquidou. Preenchido após PAID.
  • payerDocument
    string | null
    CPF/CNPJ do pagador real. Preenchido após PAID.
  • payerInstitution
    string | null
    Instituição financeira do pagador real. Preenchido após PAID.
  • refundEndToEndId
    string | null
    EndToEndId do estorno. Preenchido após status=REFUNDED.
  • refundedAt
    string (ISO 8601) | null
    Quando o estorno foi liquidado. Preenchido após status=REFUNDED.
  • refundedAmountCents
    string
    Valor estornado em centavos. "0" enquanto não houver estorno.
  • failureReason
    string | null
    Motivo de falha, quando aplicável.
  • createdAt
    string (ISO 8601)
    Quando a cobrança foi criada.
json
{  "id": "cmoxample0004qkxyzcharge",  "pixAccountId": "cmoxample0050qkxyzpixacct",  "variant": "cobv",  "status": "PENDING",  "txid": "00000000000000000000000000000000",  "amountCents": "1000",  "brCode": "00020101021226930014br.gov.bcb.pix2571qrcode.staterpay.com.br/v2/qr/cobv/00000000-0000-0000-0000-0000000000005204000053039865802BR5912FULANO DE TAL6009SAO PAULO61080408000062070503***6304XXXX",  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...truncado",  "imageUrl": "https://api.staterpay.com.br/v2/finance/image/qrcode/00000000000000000000000000000000.png",  "expiresAt": "2026-05-19T12:00:00.000-03:00",  "dueDate": "2026-05-18T12:00:00.000-03:00",  "fineDate": "2026-05-19T12:00:00.000-03:00",  "debtorName": "Fulano de Tal",  "debtorDocument": "12345678900",  "debtorTypeDocument": "CPF",  "typeFine": "VALUE",  "fine": 1000,  "tag": "Pedido 123",  "endToEndId": null,  "paidAt": null,  "payerName": null,  "payerDocument": null,  "payerInstitution": null,  "refundEndToEndId": null,  "refundedAt": null,  "refundedAmountCents": "0",  "failureReason": null,  "createdAt": "2026-05-14T08:04:52.901-03:00"}
URL base:https://baas.staterpay.io

Criar cobrança Pix

POST /accounts/:accountId/charges — gera QR Code Pix nas variantes simple, debtor ou cobv.

Listar cobranças Pix

GET /accounts/:accountId/charges — paginação por cursor com filtros por status e variant.

On this page

Path paramsHeadersExemplo de requisiçãoResposta