API Reference
Enviar Pix via chave
POST /v1/payouts — cria pagamento Pix usando chave.
Envia Pix via chave
Cria um pagamento Pix usando chave. A criação retorna imediatamente com status PROCESSING — o endToEndId definitivo só é emitido após a confirmação do provider e chega via webhook pix.payout.succeeded.
POST/v1/payouts
Para monitorar o pagamento até a liquidação, registre um webhook em pix.payout.succeeded / pix.payout.failed / pix.payout.cancelled / pix.payout.refunded. Como alternativa, faça polling em GET /v1/payouts/:id (mas webhooks são preferíveis).
Headers
- AuthorizationObrigatóriostringBearer SUA_API_KEY
- Idempotency-KeyObrigatóriostringUUID para retry seguro — obrigatório.
- Content-TypeObrigatóriostringapplication/json
Body
- pixKeyObrigatóriostringChave Pix do destinatário.
- pixKeyTypeObrigatório"EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP"Tipo da chave.
- amountCentsObrigatóriostringValor a transferir em centavos.
- dictLookupIdstringID retornado por POST /v1/dict/lookup. Recomendado para auditoria do destinatário.
- descriptionstringDescrição livre exibida no extrato e no metadata do movimento.
- externalRefstring (≤ 64)Referência externa do seu sistema (ex.: ID do pedido, do lote, da fatura). Até 64 caracteres. Permite consultar o payout e seu movimento depois via GET /v1/payouts/external-ref/:reference (e /movement).
Exemplo de requisição
bash
curl -X POST https://api.staterpay.io/v1/payouts \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Idempotency-Key: 438e4e8d-3f81-4579-a2e4-3f55b5993413" \ -H "Content-Type: application/json" \ -d '{ "pixKey": "fulano@example.com", "pixKeyType": "EMAIL", "amountCents": "1500", "dictLookupId": "cmoxample0001qkxyzdictentry", "description": "Pagamento pedido #123", "externalRef": "pedido-2026-0001" }'Resposta
- kind"submitted"Marca a criação como submetida ao provider.
- payoutIdstringIdentificador interno do pagamento (cuid).
- status"PROCESSING" | "SUCCEEDED" | "FAILED" | "CANCELLED" | "REFUNDED"Estado inicial sempre PROCESSING.
- endToEndIdstring | nullSempre null na criação; preenchido após liquidação.
- providerTransactionIdstringID da transação no provider Pix subjacente.
json
{ "kind": "submitted", "payoutId": "cmoxample0001qkxyzpayout", "status": "PROCESSING", "endToEndId": null, "providerTransactionId": "00000000"}URL base:
https://api.staterpay.io