Consultar payout

Retorna o status atualizado de um pagamento enviado, independente do canal (Pix, TEF ou QR Code). Use depois de POST /pix/payment, /tef/internal-payment ou /pix/qrcode/payment pra acompanhar a liquidação — o payoutId é o mesmo valor que veio em payout.payoutId na criação.

GET/accounts/:accountId/payouts/:payoutId

Endpoint único pros 3 canais de envio — distingue pelo source (PIX_OUT, TEF_OUT, QR_CODE_OUT). Logo após /pix/payment, /tef/internal-payment ou /pix/qrcode/payment, o status volta como PROCESSING e metadata.endToEndId null. Após a liquidação no provider, status vira POSTED, metadata.endToEndId é preenchido e metadata.paymentDate aparece. Use polling moderado (1-5s) ou aguarde callbacks pra não martelar o endpoint. entries[].amount/balanceAfter vêm em centavos string (diferente do amount em reais que entra na criação).

Path params

accountIdObrigatório
string (UUID)
ID da conta que enviou o payout.
payoutIdObrigatório
string (cuid)
ID retornado em payout.payoutId pela rota que criou o pagamento.

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/payouts/cmoxample0001qkxyzpayout \  -H "Accept: application/json" \  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>" \  -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000"

Resposta

id
string (cuid)
ID do movimento gerado pelo payout — mesmo formato que aparece em /transactions.
type
"DEBIT" | "CREDIT"
Sentido do movimento na conta. Payouts enviados sempre vêm como DEBIT.
status
"PENDING" | "PROCESSING" | "POSTED" | "FAILED" | "CANCELLED" | "REFUNDED"
Estado atual do payout. POSTED indica que o débito foi confirmado na conta; o status do envio em si vive em metadata e nas reconciliações.
source
string
Origem da operação. PIX_OUT pra transferências Pix por chave, TEF_OUT pra transferências internas, QR_CODE_OUT pra pagamentos via QR Code.
description
string
Descrição humana do payout (ex.: "Transferência para NOME EMPRESA LTDA").
externalRef
string | null
Referência externa opcional do parceiro, quando enviada na criação.
feeAmount
string | null
Tarifa cobrada (em centavos, string) — null quando não há tarifa aplicada.
reversesMovementId
string | null
Se o payout estorna outro movimento, traz o id do movimento original; senão null.
createdAt
string (ISO 8601)
Quando o payout foi criado, com timezone.
entries
array
Lançamentos contábeis gerados na conta.
entries[].id
string (cuid)
ID do lançamento.
entries[].accountId
string (cuid)
ID interno da conta onde o lançamento foi feito.
entries[].amount
string
Valor do lançamento em centavos (string). Negativo em débitos.
entries[].balanceAfter
string
Saldo da conta logo após este lançamento, em centavos (string).
entries[].kind
"PRIMARY" | "FEE" | "REVERSAL"
Tipo do lançamento. PRIMARY é o valor principal; FEE separa a tarifa.
entries[].createdAt
string (ISO 8601)
Quando o lançamento foi registrado.
metadata
object
Metadados específicos do canal (Pix/TEF/QR).
metadata.date
string (ISO 8601 UTC)
Timestamp da submissão ao provider.
metadata.endToEndId
string | null
EndToEndId definitivo. Sempre null enquanto status=PROCESSING; preenchido após liquidação no provider.
metadata.paymentDate
string (ISO 8601 UTC)
Quando a liquidação confirmou no provider. Só aparece após o payout liquidar.
metadata.payer
object
Dados da conta pagadora (sua conta).
metadata.payer.branch
string
Agência do pagador.
metadata.payer.account
string
Número da conta pagadora.
metadata.beneficiary
object
Dados do destinatário resolvido no momento do envio.
metadata.beneficiary.ispb
string
ISPB do banco destinatário.
metadata.beneficiary.name
string
Nome ou razão social do destinatário.
metadata.beneficiary.branch
string
Agência do destinatário.
metadata.beneficiary.account
string
Número da conta destinatária.
metadata.beneficiary.document
string
CPF/CNPJ do destinatário.
metadata.beneficiary.accountType
string
Tipo da conta destinatária (ex.: Current Account).
metadata.beneficiary.branchDigit
string | null
Dígito da agência, se houver.
metadata.beneficiary.accountModel
string
Modelo da conta destinatária (ex.: Movement).
metadata.pixAccountId
string (cuid)
ID interno da conta Pix subjacente (sub-conta operacional). Só em payouts Pix/QR.

json

{  "id": "cmoxample0001qkxyzpayout",  "type": "DEBIT",  "status": "POSTED",  "source": "PIX_OUT",  "description": "Transferência para NOME EMPRESA LTDA",  "externalRef": null,  "feeAmount": null,  "reversesMovementId": null,  "createdAt": "2026-05-14T07:30:09.369-03:00",  "entries": [    {      "id": "cmoxample0099qkxyzentryac",      "accountId": "cmoxample0010qkxyzaccount",      "amount": "-1",      "balanceAfter": "642",      "kind": "PRIMARY",      "createdAt": "2026-05-14T07:30:09.371-03:00"    }  ],  "metadata": {    "date": "2026-05-14T10:30:09.363Z",    "payer": {      "branch": "1",      "account": "6002096"    },    "endToEndId": "E12345678202605141030HYmA4MdODiv",    "beneficiary": {      "ispb": "12345678",      "name": "NOME EMPRESA LTDA",      "branch": "0001",      "account": "598375",      "document": "12345678000190",      "accountType": "Current Account",      "branchDigit": null,      "accountModel": "Movement"    },    "pixAccountId": "cmoxample0050qkxyzpixacct",    "paymentDate": "2026-05-14 10:30:12.599199+00:00"  }}

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

Consultar payout

Consultar payout

Path params

Headers

Exemplo de requisição

Resposta

On this page