API BaaSPix

Execute Pix outbound transfer (via Pix Key)

Executes a PIX transfer directly to a PIX key. **Balance verification**: The system automatically checks if there is sufficient available balance before executing the transfer. **Supported key types**: - `CPF` - Recipient's CPF (11 digits, numbers only) - `CNPJ` - Recipient's CNPJ (14 digits, numbers only) - `EMAIL` - Recipient's email address - `PHONE` - Phone with +55 and area code (e.g., +5511999999999) - `EVP` - Random key (UUID v4) **Tip**: To pay a QR Code, use `POST /v1/accounts/{accountId}/pix/out/qr-code/async` (preferred). The synchronous `/pix/out/qr-code` endpoint is deprecated. **Tip**: To send a PIX using bank account details (ISPB, branch, account number) instead of a PIX key, use `POST /v1/accounts/{accountId}/pix/out/bank-account`. **Sync rate limit**: This endpoint applies per-account rate limiting (current default: 100 req/min, configurable by policy). In the next days, the default for synchronous requests is planned to be adjusted to `10 req/min`. When exceeded, it returns `429 rate_limit_exceeded` with the current limit and a recommendation to use async cashout. **Breaking behavior change**: Partner timeout for sync PIX OUT returns `207 Multi-Status` (previously `504`). In this scenario, always check statement/payment status before retrying. **Immediate rejections** (v2.24.0): when the settlement bank refuses the transfer right away (anti-fraud or insufficient settlement funds), the endpoint responds `422 FAILED` immediately with `errorCode` (`partner_rejected` / `insufficient_funds`) and `errorReason`. Transfers held for risk analysis show as `PENDING_APPROVAL` on payment lookups and wait up to ~25 minutes for the final outcome (delivered via `pix.out.completed` / `pix.out.failed` webhooks) before marking `TIMEOUT`. **Held by the settlement bank** (v2.64.0): while the order is held, payment lookups and the `pix.out.timeout` webhook carry `hold.owner: "partner"` plus `hold.reason`, and the raw state in `partnerStatus`/`partnerStatusId`. `PENDING_APPROVAL` never means an approval is pending on your side or on ours. `TIMEOUT` is indeterminate, not final: we keep polling the settlement bank for up to 7 days and, if it settles or rejects the order in that window, you receive `pix.out.completed` / `pix.out.failed` with `late: true` and the same `paymentId`.

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).

keyTypeenumRequired

Recipient’s PIX key type:

  • CPF - CPF (11 digits, numbers only)
  • CNPJ - CNPJ (14 digits, numbers only)
  • EMAIL - Email address
  • PHONE - Phone with country code (+5511999999999)
  • EVP - Random key (UUID v4)
keystringRequired

Recipient’s PIX key value. Format depends on the provided keyType.

amountdoubleRequired>=0.01

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

currencyenumRequiredDefaults to BRL

Currency code (only BRL supported).

descriptionstringOptional<=140 characters

Transfer description (visible to recipient).

identifierstringOptional<=50 characters

Integrator-provided identifier for tracking and reconciliation. Appears in the statement when the payment is reconciled.

metadatamap from strings to anyOptional

Additional metadata (not sent to recipient).

Response

PIX transfer 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
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error