Enviar um Pix
Fluxo completo para enviar Pix: consulta DICT + criação da transferência.
O envio de Pix tem dois passos: consultar o titular da chave (DICT) e depois criar a transferência. A consulta é opcional, mas recomendada para confirmar o destinatário antes de mover o dinheiro.
1. Consultar o titular
curl -X POST https://api.staterpay.io/v1/dict/lookup \-H "Authorization: Bearer SUA_API_KEY" \-H "Content-Type: application/json" \-d '{ "pixKey": "fulano@example.com", "pixKeyType": "EMAIL" }'A resposta inclui o nome do titular, banco e um id de auditoria:
{"id": "cmoxample0001qkxyzdictentry","key": "fulano@example.com","keyType": "EMAIL","owner": { "name": "Fulano de Tal", "document": "***456789**"},"bankName": "BANCO EXEMPLO S.A.","ispb": "12345678","branch": null,"account": null,"accountType": null,"cached": false}cached: true indica que a resposta veio de cache interno
(não acionou o DICT). document sempre vem mascarado por
regulação do BCB.
2. Criar a transferência
Use o id da consulta no campo dictLookupId.
Os campos pixKey, pixKeyType e
amountCents continuam obrigatórios.
curl -X POST https://api.staterpay.io/v1/payouts \-H "Authorization: Bearer SUA_API_KEY" \-H "Idempotency-Key: 4a51b6c2-2cd0-4d06-b5e2-2e9d4d7e5e3f" \-H "Content-Type: application/json" \-d '{ "pixKey": "fulano@example.com", "pixKeyType": "EMAIL", "amountCents": "1500", "dictLookupId": "cmoxample0001qkxyzdictentry", "description": "Pagamento pedido #123"}'{"kind": "submitted","payoutId": "cmoxample0001qkxyzpayout","status": "PROCESSING","endToEndId": null,"providerTransactionId": "00000000"}A criação retorna imediatamente com kind: "submitted",
status: "PROCESSING" e endToEndId: null. O ID
definitivo de liquidação só é emitido após a confirmação do provider —
chega via webhook pix.payout.succeeded.
O campo kind traz o desfecho da criação. Além de
submitted, existem dois outros:
rejected(HTTP 422) — o provedor recusou. O valor já voltou ao saldo; o motivo está emreason.submitted_unknown(HTTP 200) — o provedor não respondeu a tempo e o desfecho ainda é desconhecido. O valor fica reservado e a plataforma resolve sozinha.
{"kind": "submitted_unknown","payoutId": "cmoxample0001qkxyzpayout","status": "SUBMITTED_UNKNOWN","reason": "SAQ cashout-self-approve network/timeout"}Ao receber submitted_unknown, não reenvie o pagamento
com outra Idempotency-Key — o Pix pode ter saído e você
pagaria duas vezes. Guarde o payoutId e acompanhe via
GET /v1/payouts/:id até o status virar
SUCCEEDED ou FAILED, ou aguarde o webhook
pix.payout.succeeded / pix.payout.failed.
Decida pelo campo kind/status do corpo, não
pelo código HTTP.
Sempre envie Idempotency-Key ao criar pagamentos. Em caso
de timeout na sua chamada, refaça a requisição com a mesma chave para
evitar débito duplo — você recebe a resposta original, inclusive quando
ela foi submitted_unknown.
3. Acompanhar o status
O pagamento começa em PROCESSING (ou em
SUBMITTED_UNKNOWN, quando a criação foi indeterminada) e
evolui para um destes estados:
SUCCEEDED— Pix liquidado.FAILED— recusado pelo provider; vejalastError.CANCELLED— cancelado antes da liquidação.REFUNDED— devolvido após liquidação. Você pode consultar o estado atual viaGET /v1/payouts/{id}ou registrar um webhook parapix.payout.*.