API BaaSPix

Schedule Pix QR Code payment (async)

Schedules a PIX QR Code payment (EMV / copy-and-paste) for asynchronous processing and returns immediately with `202`. Canonical endpoint to pay a PIX QR Code (EMV / copy-and-paste). Same request body previously used by the deprecated sync `POST /v1/accounts/{accountId}/pix/out/qr-code`. Final success/failure is communicated by webhook (`pix.out.completed`, `pix.out.failed`, `pix.out.timeout`) and can be checked via payment lookup endpoints.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

X-Acting-DocumentstringOptional
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN.
X-Transaction-PinstringOptional

Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).

X-Acting-IpstringOptional

Real IP of the end user, for integrator credentials calling on their behalf. This is the IP evaluated against cashoutSourceIps — without it the check would see your server’s IP. Ignored for delegated credentials, where the connection IP is already the right one.

Request

This endpoint expects an object.
accountIdstringRequiredformat: "uuid"

Source account identifier (UUID).

emvstringRequired

PIX QR Code EMV string (“copy and paste” field). Starts with “00020126” and contains encoded recipient data.

amountdoubleOptional>=0.01

Payment amount in BRL. Max 2 decimal places (e.g., 150.75 for R$150,75).

  • Required for static QR Codes without defined value
  • Optional for dynamic QR Codes (will be validated against QR value)
descriptionstringOptional<=140 characters

Payment description (for internal use).

identifierstringOptional<=64 characters

Client-side reference for reconciliation. Echoed back on the payment, in the statement and in pix.out.* webhooks. Also the key used by the Location header of the async variant.

Response headers

LocationstringOptional
Path to look up the payment by identifier.

Response

PIX QR Code payment accepted and scheduled for asynchronous processing.
paymentIdstring
Internal payment intent identifier.
identifierstring
statusenum
workflowIdstringOptional
Durable workflow identifier.
runIdstringOptional
Workflow run identifier.
idempotencyKeystringOptional

Errors

400
Bad Request Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
500
Internal Server Error
503
Service Unavailable Error