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 addressPHONE- 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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Client-generated idempotency token.
CPF of the human performing the operation. Required on cashout routes when the credential enforces a transaction PIN. On a company P2P profile contact, this CPF is the holder who signs; it is not taken from the body.
Transaction PIN of the operator in X-Acting-Document. Required on cashout routes when the credential enforces a PIN (428 pin_required).
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.
Optional user-agent of the end user’s browser or app, for integrator credentials calling on their behalf. Feeds risk analysis only: an invalid or oversized value is dropped and the payment still proceeds. Ignored for delegated credentials.
Optional device fingerprint or identifier from the integrator’s own system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional session id of the end user in the integrator’s system. Risk analysis only; never required and never a reason to reject the payment. Ignored for delegated credentials.
Optional latitude,longitude in decimal degrees. Out of range or malformed values are dropped. Risk analysis only. Ignored for delegated credentials.
Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).
Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.
Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.
Request
Source account identifier (UUID).
Recipient’s PIX key type:
CPF- CPF (11 digits, numbers only)CNPJ- CNPJ (14 digits, numbers only)EMAIL- Email addressPHONE- Phone with country code (+5511999999999)EVP- Random key (UUID v4)
Recipient’s PIX key value.
Format depends on the provided keyType.
Transfer amount in BRL. Max 2 decimal places (e.g., 150.75 for R$150,75).
Currency code (only BRL supported).
Transfer description (visible to recipient).
Integrator-provided identifier for tracking and reconciliation. Appears in the statement when the payment is reconciled.
Additional metadata (not sent to recipient).
Response
PIX transfer accepted/executed.
Internal payment intent identifier (tracking/reconciliation).
Canonical status:
COMPLETED- settled (HTTP 200)FAILED- rejected (HTTP 422; seeerrorCode/errorReason)TIMEOUT- indeterminate; request reached the partner (HTTP 202; check the statement before retrying)PENDING/PENDING_APPROVAL/PROCESSING- not terminal yet (HTTP 202)
Business identifier (client-provided or auto-generated UUID).
BACEN end-to-end PIX identifier (present once settled).
Error code (present when FAILED).
Error reason (present when FAILED).
Completion timestamp (UTC).
Present on indeterminate (TIMEOUT) results.