API BaaSPix

[DEPRECATED] Pay a Pix QR Code (via EMV, sync)

Deprecated
**DEPRECATED**: prefer `POST /v1/accounts/{accountId}/pix/out/qr-code/async`, which returns `202` immediately and delivers the final result via webhook. This synchronous endpoint remains functional for backward compatibility and returns `Deprecation: true`, `Sunset` and `Link` headers. Planned sunset: **2026-11-21**. Pays a PIX QR Code using the EMV string (copy and paste). For static QR Codes without a predefined value, the `amount` field is required. For dynamic QR Codes with a predefined value, the `amount` field is optional (if provided, it will be validated against the QR Code value). **Balance verification**: The system automatically checks if there is sufficient available balance before executing the transfer.

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

PIX payment via QR Code accepted/executed.

paymentIdstring

Internal payment intent identifier (tracking/reconciliation).

statusenum

Canonical status:

  • COMPLETED - settled (HTTP 200)
  • FAILED - rejected (HTTP 422; see errorCode/errorReason)
  • TIMEOUT - indeterminate; request reached the partner (HTTP 202; check the statement before retrying)
  • PENDING / PENDING_APPROVAL / PROCESSING - not terminal yet (HTTP 202)
identifierstring

Business identifier (client-provided or auto-generated UUID).

transactionIdstringOptional
Transaction identifier in the system.
endToEndIdstringOptional

BACEN end-to-end PIX identifier (present once settled).

errorCodestringOptional

Error code (present when FAILED).

errorReasonstringOptional

Error reason (present when FAILED).

completedAtdatetimeOptional

Completion timestamp (UTC).

idempotencyKeystringOptional
workflowIdstringOptional
Durable workflow identifier.
warningstringOptional

Present on indeterminate (TIMEOUT) results.

Errors

400
Bad Request Error
409
Conflict Error
422
Unprocessable Entity Error
503
Service Unavailable Error
504
Gateway Timeout Error