API Reference
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.*).
POST/v1/payouts/qr-code
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.
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
bash
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"Marca a criação como submetida ao provider.
- payoutIdstringIdentificador interno do payout.
- 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.
json
{ "kind": "submitted", "payoutId": "cmoxample0001qkxyzpayout", "status": "PROCESSING", "endToEndId": null, "providerTransactionId": "00000000"}URL base:
https://api.staterpay.io