Pagar QR Code
POST /v1/payouts/qr-code — paga um Pix a partir do copia-e-cola.
Pagar QR Code
Paga um Pix a partir do copia-e-cola. Recomendado decodificar antes via POST /v1/qr-code/decode para confirmar valor e beneficiário. Mesma semântica de liquidação que /v1/payouts (eventos pix.payout.*) e mesmos desfechos em kind: submitted, rejected ou submitted_unknown.
A resposta tem o mesmo formato do POST /v1/payouts (envio por chave). O detalhe do payout (incluindo recipientPreview) está em GET /v1/payouts/:id; para esse fluxo, paymentMethod virá QR_CODE e os campos qrCode + qrCodeDecodeId estarão preenchidos. 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óriostringBearer SUA_API_KEY
- Idempotency-KeyObrigatóriostringUUID para retry seguro.
- Content-TypeObrigatóriostringapplication/json
Body
- pixCopyAndPasteObrigatóriostringQR Code Pix (copia-e-cola) a ser pago.
- amountCentsObrigatóriostringValor a pagar em centavos. Em QR estático sem valor, este é o valor que o pagador define; em QR dinâmico, deve coincidir com o valor do QR (salvo allows_change_value).
- qrCodeDecodeIdstringID retornado em POST /v1/qr-code/decode. Recomendado para auditoria do destinatário.
- descriptionstringDescrição livre exibida no extrato.
- externalRefstring (≤ 64)Referência externa do seu sistema (ex.: ID do pedido). Até 64 caracteres. Permite consultar o payout depois via GET /v1/payouts/external-ref/:reference.
Exemplo de requisição
curl -X POST https://api.staterpay.io/v1/payouts/qr-code \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Idempotency-Key: f4455591-0c62-40f3-a71d-7bb8edb35cdc" \ -H "Content-Type: application/json" \ -d '{ "pixCopyAndPaste": "00020126580014BR.GOV.BCB.PIX0136f3e7b544-2510-4d84-a262-8bfe14eef00852040000530398654040.015802BR5921Fulano de Tal6009SAO PAULO61080540900062240520LloQbvfB1qY3yL32yojr63040F44", "amountCents": "1", "qrCodeDecodeId": "cmoxample0001qkxyzdecode" }'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).
- payoutIdstringIdentificador interno do payout.
- status"PROCESSING" | "SUBMITTED_UNKNOWN" | "FAILED"Estado correspondente ao kind: PROCESSING em submitted, SUBMITTED_UNKNOWN em submitted_unknown, FAILED em rejected.
- endToEndIdstring | nullSempre null na criação; preenchido após liquidação. Presente quando submitted.
- providerTransactionIdstringID da transação no provider Pix. Presente quando submitted.
- reasonstringMotivo da recusa ou da indeterminação. Presente quando rejected ou submitted_unknown.
- providerStatusCodenumberStatus HTTP retornado pelo provedor. Presente quando rejected.
{ "kind": "submitted", "payoutId": "cmoxample0001qkxyzpayout", "status": "PROCESSING", "endToEndId": null, "providerTransactionId": "00000000"}https://api.staterpay.io