Stater Platform
API Reference

Consultar pagamento por referência externa

GET /v1/payouts/external-ref/:reference — consulta um payout pelo externalRef.

Consulta pagamento por externalRef

Consulta um pagamento pelo externalRef informado na criação (POST /v1/payouts ou /v1/payouts/qr-code). Útil quando você só guarda o ID do seu sistema e não o payoutId interno. Retorna a mesma estrutura de GET /v1/payouts/:id.

GET/v1/payouts/external-ref/:reference

Diferente do GET /v1/payouts/:id, este endpoint exige o header X-Pix-Account-Id obrigatoriamente (o externalRef só é único dentro de uma conta). O shape da resposta é idêntico ao do GET por id e ao do GET /v1/payouts/end-to-end-id/:endToEndId.

Path params

  • referenceObrigatório
    string (≤ 64)
    externalRef informado na criação do payout.

Headers

  • AuthorizationObrigatório
    string
    Bearer SUA_API_KEY
  • X-Pix-Account-IdObrigatório
    string
    ID da conta Pix proprietária do payout.

Exemplo de requisição

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

Resposta

  • id
    string
    Identificador interno do payout (cuid).
  • pixAccountId
    string
    Conta Pix de origem.
  • movementId
    string
    Movimento contábil associado.
  • paymentMethod
    "PIX_KEY" | "QR_CODE"
    Como o pagamento foi originado.
  • pixKey
    string | null
    Chave Pix de destino (em PIX_KEY).
  • pixKeyType
    "EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP" | null
    Tipo da chave (em PIX_KEY).
  • qrCode
    string | null
    QR Code copia-e-cola original (em QR_CODE).
  • qrCodeDecodeId
    string | null
    ID do decode prévio (em QR_CODE).
  • amountCents
    string
    Valor enviado em centavos.
  • description
    string | null
    Descrição livre informada na criação.
  • status
    "PROCESSING" | "SUCCEEDED" | "FAILED" | "CANCELLED" | "REFUNDED"
    Estado atual.
  • endToEndId
    string | null
    Identificador Pix de liquidação.
  • providerTransactionId
    string
    ID da transação no provider.
  • providerCodeTransaction
    string | null
    Código auxiliar do provider, quando aplicável.
  • refundEndToEndId
    string | null
    EndToEndId da devolução, se houve.
  • refundTransactionId
    string | null
    ID da devolução no provider.
  • refundedAmountCents
    string
    Valor devolvido (centavos). 0 quando não houve devolução.
  • submittedAt
    string (ISO-8601 UTC-3)
    Submissão ao provider.
  • paidAt
    string (ISO-8601 UTC-3) | null
    Confirmação no provider.
  • lastPolledAt
    string (ISO-8601 UTC-3) | null
    Última verificação do estado.
  • nextPollAt
    string (ISO-8601 UTC-3) | null
    Próxima verificação agendada.
  • pollAttempts
    number
    Quantas verificações já foram feitas.
  • lastError
    string | null
    Mensagem de erro do último submit, se falhou.
  • providerResponse
    object | null
    Resposta crua do provider, quando rejeitado.
  • providerStatusCode
    string | null
    Código de status do provider, quando rejeitado.
  • resolvedAt
    string (ISO-8601 UTC-3) | null
    Quando o estado final foi atingido.
  • externalRef
    string
    Referência externa (eco do path param).
  • createdAt
    string (ISO-8601 UTC-3)
    Criação do registro.
  • beneficiaryName
    string | null
    Nome do destinatário (snapshot capturado no envio).
  • beneficiaryDocument
    string | null
    CPF/CNPJ do destinatário (somente dígitos).
  • beneficiaryAccount
    string | null
    Conta do destinatário na instituição beneficiária.
  • beneficiaryBranch
    string | null
    Agência do destinatário.
  • beneficiaryInstitution
    string | null
    ISPB da instituição do destinatário (8 dígitos).
  • beneficiaryAccountType
    string | null
    Tipo de conta do destinatário, quando informado pelo provider.
  • beneficiaryPixKey
    string | null
    Chave Pix do destinatário usada no envio (em PIX_KEY).
  • beneficiaryPixKeyType
    "EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP" | null
    Tipo da chave do destinatário.
json
{  "id": "cmoxample0001qkxyzpayout",  "pixAccountId": "cmoxample0001qkxyzaccount",  "movementId": "cmoxample0001qkxyzmovement",  "paymentMethod": "PIX_KEY",  "pixKey": "fulano@example.com",  "pixKeyType": "EMAIL",  "qrCode": null,  "qrCodeDecodeId": null,  "amountCents": "1",  "description": "Transferência Pix — Fulano de Tal",  "status": "SUCCEEDED",  "endToEndId": "E37319859202605191328CGTFMTDP4RX",  "providerTransactionId": "33004715",  "providerCodeTransaction": null,  "refundEndToEndId": null,  "refundTransactionId": null,  "refundedAmountCents": "0",  "submittedAt": "2026-05-19T10:28:21.264-03:00",  "paidAt": "2026-05-19T10:28:23.253-03:00",  "lastPolledAt": null,  "nextPollAt": null,  "pollAttempts": 0,  "lastError": null,  "providerResponse": null,  "providerStatusCode": null,  "resolvedAt": "2026-05-19T10:28:23.868-03:00",  "externalRef": "pedido-2026-0001",  "createdAt": "2026-05-19T10:28:21.337-03:00",  "beneficiaryName": "Fulano de Tal",  "beneficiaryDocument": "12345678900",  "beneficiaryAccount": "49773517",  "beneficiaryBranch": "1",  "beneficiaryInstitution": "18236120",  "beneficiaryAccountType": null,  "beneficiaryPixKey": "fulano@example.com",  "beneficiaryPixKeyType": "EMAIL"}
URL base:https://api.staterpay.io

Consultar pagamento

GET /v1/payouts/:id — status, endToEndId e detalhes do erro quando aplicável.

Consultar pagamento por endToEndId

GET /v1/payouts/end-to-end-id/:endToEndId — consulta um payout pelo endToEndId Pix de liquidação.

On this page

Path paramsHeadersExemplo de requisiçãoResposta