Cash Out Guide (PIX Out)
This guide explains step by step how to make PIX transfers (cash out) with prior key lookup. Paying someone else’s boleto is Boleto Pay. To pay dozens or thousands of PIX from a file, with a review and acknowledgement before any debit, see Batch PIX.
Overview
Cash Out allows you to send money via PIX to any key registered in the Brazilian PIX system. The recommended flow is:
- Look up the key - Validate and obtain the recipient’s details
- Confirm the details - Display to the user for confirmation
- Execute the transfer - Send the PIX
Integration Flow
PIX Key Types
Step 1: Look Up the PIX Key (Optional but Recommended)
Before transferring, look up the key to validate the recipient and display the details for user confirmation:
The API automatically performs the key lookup during the transfer — the prior lookup is optional, but improves UX. The result is cached for 24 h (use ?noCache=true to force a fresh DICT lookup) and consumes lookup quota according to the tenant policies. DICT consumption is measured in real time and watched by CorpX: before integrating, read PIX key lookups.
What the Transfer Returns
The transfer response does not echo the recipient’s details: it carries the outcome of the operation (status, paymentId, endToEndId). The payee’s name and document appear in the statement and in the payment lookup.
Step 2: Execute the Transfer
Execute the PIX transfer via key:
Request
Body Parameters
The source account comes from the path ({accountId}) and the currency is always BRL — neither is sent in the body.
Success Response
The HTTP status reflects the outcome: 200 (COMPLETED), 422
(FAILED), 202 (TIMEOUT/PENDING — indeterminate; check the statement
before retrying).
Immediate rejections by the settlement bank (anti-fraud or insufficient
settlement funds) return 422 FAILED right away, with errorCode
(partner_rejected / insufficient_funds) and errorReason filled in.
Transfers held at the settlement bank show as PENDING_APPROVAL on lookups
and wait for the outcome for up to ~25 minutes before marking TIMEOUT; the
result arrives via the pix.out.completed / pix.out.failed /
pix.out.timeout webhooks.
In that state, the lookup and the pix.out.timeout webhook carry hold
(owner: "partner" + reason) and the raw state in
partnerStatus/partnerStatusId. PENDING_APPROVAL never means an
approval is pending on your side or on ours: the decision belongs to the
settlement bank. And TIMEOUT is not the end — we keep polling for up to
7 days and, if it settles or rejects, you receive pix.out.completed /
pix.out.failed with late: true and the same paymentId.
Error Response
(The API returns messages in Portuguese; the example above means “insufficient balance at the settlement bank to complete the operation”.)
Timeout on the sync flow
If the settlement bank does not confirm within the window, the API responds
202 with status: "TIMEOUT" and a warning field — there is no 207.
The PIX may already have been sent: check the statement or the payment lookup
before retrying. The late outcome arrives via webhook
(pix.out.completed / pix.out.failed).
Async flow (recommended for high volume)
Use POST /v1/accounts/{accountId}/pix/out/async to schedule payment and get immediate 202:
Response:
The 202 response includes a Location header pointing to
/v1/accounts/{accountId}/payments/{identifier} — an alias kept for
compatibility that responds with Deprecation headers. The canonical lookup
route is GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=.
The final result (success/failure) is delivered by webhook and can also be
checked by identifier/paymentId. To avoid polling that route yourself,
pass waitForFinalStatus — the call holds the connection until the
outcome. See Wait for the outcome instead of polling.
Step 3: Check Transfer Status
After executing a transfer, you can check its status using the E2E ID:
Request
Query Parameters
*At least one of the two (endToEndId or identifier) is required. The accountId goes in the path, not in the query.
Success Response (200 OK)
This route responds with the same envelope as the statement (items[]),
with 0 or 1 item. Timestamps (timestamp) are in São Paulo time (-03:00).
A transaction that does not exist is not a 404: the response is 200 with
items: [].
To get a single object (instead of the items[] envelope), use
GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=... (or
?endToEnd=...).
Wait for the outcome instead of polling
The waitForFinalStatus parameter replaces the polling loop you would
otherwise run against the payment lookup
(GET /v1/accounts/{accountId}/pix/payments/lookup). Only that route
accepts it; the /pix/transactions route in the example above ignores it.
Instead of calling the lookup every few seconds, call it once with
waitForFinalStatus (seconds, at most 10). The API holds the connection and
queries the settlement bank until the payment reaches COMPLETED, FAILED
or REVERSED, or until the wait expires. The first query goes out 1 s after
the call, inside the wait: right after the POST the settlement bank usually
does not have the payment yet.
The response shape does not change. A value above 10 is capped at 10, and
the X-Wait-Seconds header returns the wait that was applied (not how long
the call took). Without the parameter, or with 0, the route answers
immediately, as before.
When the wait expires before the outcome:
- If the payment was read at least once, the response is
200with the last status (PROCESSING,PENDING_APPROVAL…). It is not an error: call again or wait for the webhook. - If the payment was never read, the response is that of the last attempt:
404 not_foundwhen the settlement bank did not find it, or the settlement bank error when that attempt failed. Right after aPOST .../pix/out/async, the404means the settlement bank has not registered the payment yet — or that theidentifieris wrong.
If the settlement bank does not find the payment but it already has a final
status at CorpX (completed, refused before reaching the settlement bank, or
returned), the response is 200 with that status, with or without
waitForFinalStatus. While the payment is in progress, 404 still means the
settlement bank has not registered it yet.
On a refusal (FAILED), the lookup carries errorCode with the same code as
the pix.out.failed webhook (insufficient_funds,
limit_exceeded_transaction, limit_exceeded_daily, partner_rejected…) and
the reason in errorMessage. Branch on the code, not on the text: the code is
what tells a lack of balance from an exceeded limit in the message you show
your customer.
A definitive refusal from the settlement bank (4xx other than 408 and
429) comes back right away, without waiting for the deadline. Only
transient failures (5xx, 408, 429, timeout) are retried.
The response can arrive a few seconds after the wait: an attempt already in
flight when the wait expires finishes before the response (up to 5 s). Set
your HTTP client timeout to at least waitForFinalStatus + 10 s — 20 s for
waitForFinalStatus=10.
The webhook remains the authoritative path. waitForFinalStatus is for
callers that need the outcome in the same request.
Possible Statuses
State flow
- The outcome arrives via
pix.out.completed/pix.out.failed. OnTIMEOUT, the API also emitspix.out.timeout(indeterminate — check the statement; a latecompleted/failedmay still arrive afterwards, withlate: trueand the samepaymentId). - Retrying with the same
Idempotency-Keyreturns the recorded outcome and does not run the payment again: onFAILED, the same rejection; onTIMEOUT, the indeterminate state. To try again after aFAILED, use a newIdempotency-Keyand a newidentifier. After aTIMEOUT, check the statement first: with a new key you may duplicate the transfer. Details in Idempotency.
Always save the identifier of transfers and use it to check the status — it is the ID you define, stable and available from creation (the endToEndId only exists after settlement).
Full Example: Cash Out Script
Decode QR Code
Before paying, you can decode the QR Code to display beneficiary details to the user:
Response (dynamic-immediate QR):
For a charge-with-due-date QR (dynamic-due-date), the response also
includes the charge components (discount, deduction, interest,
penalty), originalAmount (face value before adjustments),
dueDate, paymentDeadline and payeeTradeName (the legal entity’s
trade name). See the matching example in the OpenAPI.
You can reuse decodeId in the body of POST /pix/out/qr-code/async
to skip a second decode at payment time.
After confirming, use the payment endpoint below to execute.
Pay QR Code (PIX Out via EMV)
If you have an EMV code (QR Code copy and paste), use the async endpoint (canonical):
Async flow (recommended)
POST /v1/accounts/{accountId}/pix/out/qr-code/async — immediate 202:
Response:
The 202 response includes a Location header pointing to the payment
lookup. The final result (success/failure/timeout) is delivered by webhook
(pix.out.completed, pix.out.failed, pix.out.timeout) and can also be
queried by identifier/paymentId.
Sync endpoint (deprecated)
POST /v1/accounts/{accountId}/pix/out/qr-code (sync) is deprecated.
It still works for compatibility and returns Deprecation, Sunset, and
Link headers (sunset planned: 2026-11-21). Migrate to
/pix/out/qr-code/async.
Transfer Webhook
After the transfer, you receive a webhook in the canonical envelope
(id, type, occurredAt, schemaVersion, data):
The failure counterpart is pix.out.failed (with error inside data) and
the indeterminate one is pix.out.timeout. The full field reference is in
Webhooks.
BigPix (deprecated)
The R$ 15,000 per-transaction limit has been removed — POST /v1/accounts/{accountId}/pix/out
now accepts any amount in a single transaction. BigPix (which split large amounts
into multiple PIX transfers) is no longer necessary and is deprecated.
The /pix/out/bigpix and /pix/out/bank-account/bigpix endpoints remain functional
for backward compatibility, but return the Deprecation: true header. Migrate to
POST /pix/out (or /pix/out/bank-account). The final removal date will be
announced in the changelog in advance.
Common Errors
The full list with messages and semantics is in Errors.
Retrying with the same Idempotency-Key on PIX out does not return 409:
the API returns the recorded result, including when that result is a
rejection (FAILED).
Best Practices
- Always look up the key before transferring to validate the recipient
- Confirm with the user the details before executing
- Use a unique Idempotency Key per transfer — and reuse the same key when repeating the request, never a new one
- Save the E2E for tracking and support
- Configure webhooks to receive asynchronous confirmations
- Implement retry with exponential backoff for temporary failures
Limits
The amount is bounded by the account ceiling. The read, the windows and
the increase request are in the limits guide.
GET .../pix/limits is deprecated.
Next Steps
- Refund Guide - Reverse received transfers
- Webhooks - Configure notifications
- Errors - Full list of error codes