Enviar um Pix

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 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.

3. Acompanhar o status

O pagamento começa em PROCESSING e evolui para um destes estados:

• SUCCEEDED — Pix liquidado.
• FAILED — recusado pelo provider; veja lastError.
• CANCELLED — cancelado antes da liquidação.
• REFUNDED — devolvido após liquidação. Você pode consultar o estado atual via GET /v1/payouts/{id} ou registrar um webhook para pix.payout.*.