Envia Pix via chave

Cria um pagamento Pix usando chave. O response já traz o desfecho da criação em kind: submitted (aceito, status PROCESSING), rejected (recusado, valor devolvido ao saldo) ou submitted_unknown (indeterminado; a plataforma resolve sozinha). 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). Em submitted_unknown (HTTP 200, status SUBMITTED_UNKNOWN) o provedor não respondeu a tempo e o desfecho ainda é desconhecido: o valor fica reservado (debitado) e a plataforma resolve sozinha. NÃO reenvie com outra Idempotency-Key — risco de pagar duas vezes. Reenviar com a MESMA Idempotency-Key devolve esta mesma resposta (Idempotency-Replay: true). Acompanhe via GET /v1/payouts/:id até o status virar SUCCEEDED ou FAILED, ou aguarde pix.payout.succeeded / pix.payout.failed. Em rejected (HTTP 422) o valor já voltou ao saldo; leia reason. Trate o desfecho pelo campo kind/status do corpo, não pelo código HTTP.

Headers

AuthorizationObrigatório
string
Bearer SUA_API_KEY
Idempotency-KeyObrigatório
string
UUID para retry seguro — obrigatório.
Content-TypeObrigatório
string
application/json

Body

pixKeyObrigatório
string
Chave Pix do destinatário.
pixKeyTypeObrigatório
"EMAIL" | "PHONE" | "CPF" | "CNPJ" | "EVP"
Tipo da chave.
amountCentsObrigatório
string
Valor a transferir em centavos.
dictLookupId
string
ID retornado por POST /v1/dict/lookup. Recomendado para auditoria do destinatário.
description
string
Descrição livre exibida no extrato e no metadata do movimento.
externalRef
string (≤ 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" | "rejected" | "submitted_unknown"
Desfecho da criação. submitted → HTTP 200 (aceito pelo provedor, status PROCESSING); rejected → HTTP 422 (recusado pelo provedor; o valor já voltou ao saldo); submitted_unknown → HTTP 200 (indeterminado: o provedor não respondeu a tempo; o valor fica reservado e a plataforma resolve sozinha).
payoutId
string
Identificador interno do pagamento (cuid).
status
"PROCESSING" | "SUBMITTED_UNKNOWN" | "FAILED"
Estado correspondente ao kind: PROCESSING em submitted, SUBMITTED_UNKNOWN em submitted_unknown, FAILED em rejected.
endToEndId
string | null
Sempre null na criação; preenchido após liquidação. Presente quando submitted.
providerTransactionId
string
ID da transação no provider Pix subjacente. Presente quando submitted.
reason
string
Motivo da recusa ou da indeterminação. Presente quando rejected ou submitted_unknown.
providerStatusCode
number
Status HTTP retornado pelo provedor. Presente quando rejected.

json

{  "kind": "submitted",  "payoutId": "cmoxample0001qkxyzpayout",  "status": "PROCESSING",  "endToEndId": null,  "providerTransactionId": "00000000"}

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

Enviar Pix via chave

Envia Pix via chave

Headers

Body

Exemplo de requisição

Resposta

On this page