Skip to navigation

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:

  1. Look up the key - Validate and obtain the recipient’s details
  2. Confirm the details - Display to the user for confirmation
  3. Execute the transfer - Send the PIX

Integration Flow

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Look Up │ │ Confirm │ │ Execute │
│ Key │ ───► │ Details │ ───► │ Transfer │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
Name, Bank, User E2E generated,
Account, CPF/CNPJ Confirms Webhook sent

PIX Key Types

TypeFormatExample
CPF11 digits12345678901
CNPJ14 digits12345678000199
EMAILValid e-mailjoao@email.com
PHONE+55 + area code + number+5511999998888
EVPUUID123e4567-e89b-12d3-a456-426614174000

Before transferring, look up the key to validate the recipient and display the details for user confirmation:

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/12345678901" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

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

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-order-12345" \
-d '{
"amount": 100.00,
"keyType": "CPF",
"key": "12345678901",
"description": "Service payment",
"identifier": "order-12345"
}'

Body Parameters

The source account comes from the path ({accountId}) and the currency is always BRL — neither is sent in the body.

FieldTypeRequiredDescription
amountnumberYesAmount in BRL (e.g., 100.00)
keyTypestringYesKey type: CPF, CNPJ, EMAIL, PHONE, EVP
keystringYesRecipient’s PIX key
descriptionstringNoTransfer description (max 140 characters)
identifierstringNoIntegrator-provided identifier for tracking and reconciliation. Appears in the statement when the payment is reconciled.

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.

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"transactionId": "txn-abc123-def456",
"endToEndId": "E12345678202301011234abcdefghijkl",
"status": "COMPLETED",
"completedAt": "2026-01-28T15:00:02Z",
"identifier": "order-12345",
"workflowId": "pix-out-{accountId}-{identifier}"
}
FieldDescription
paymentIdInternal payment intent ID (tracking/reconciliation)
transactionIdTransaction ID
endToEndIdBACEN E2E ID (present once settled)
statusCOMPLETED, FAILED, TIMEOUT, PENDING, PROCESSING
errorCode / errorReasonset when FAILED

Error Response

{
"errorCode": "insufficient_funds",
"message": "Saldo insuficiente na conta do liquidante para concluir a operação."
}

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

Use POST /v1/accounts/{accountId}/pix/out/async to schedule payment and get immediate 202:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/async" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: transfer-order-async-12345" \
-d '{
"amount": 100.00,
"keyType": "CPF",
"key": "12345678901",
"description": "Service payment",
"identifier": "order-12345-async"
}'

Response:

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"workflowId": "pix-out-{accountId}-{identifier}",
"runId": "b7c1f0e2-...",
"idempotencyKey": "transfer-order-async-12345",
"identifier": "order-12345-async",
"status": "ACCEPTED"
}

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

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/transactions?endToEndId=E12345678202301011234abcdefghijkl" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

Query Parameters

ParameterTypeRequiredDescription
endToEndIdstringYes*Transaction E2E ID
identifierstringYes*Charge or reference identifier

*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: [].

{
"accountId": "{accountId}",
"source": "live",
"page": 0,
"size": 1,
"totalElements": 1,
"totalPages": 1,
"hasNext": false,
"items": [
{
"partnerId": "a697b489-681a-451c-a043-d4ae65be8c80",
"endToEndId": "E12345678202301011234abcdefghijkl",
"direction": "OUT",
"transactionType": "D",
"operation": "PIX",
"status": "COMPLETED",
"amount": -100.00,
"currency": "BRL",
"description": "PIX - MARIA DA SILVA",
"identifier": "order-12345",
"timestamp": "2026-01-28T15:00:00-03:00",
"counterParty": {
"name": "MARIA DA SILVA",
"document": "12345678900",
"bankCode": "001"
}
}
],
"fetchedAt": "2026-01-28T18:00:05Z"
}

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.

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/payments/lookup?identifier=order-12345&waitForFinalStatus=10" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"

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 200 with 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_found when the settlement bank did not find it, or the settlement bank error when that attempt failed. Right after a POST .../pix/out/async, the 404 means the settlement bank has not registered the payment yet — or that the identifier is 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

StatusDescription
COMPLETEDSettled successfully
PROCESSINGBeing processed at the partner
PENDING_APPROVALHeld inside the settlement bank (its internal authorisation queue or risk review). Read hold.owner / hold.reason — no approval is pending on your side or on ours
FAILEDFailed / rejected
REVERSEDReversed / returned
UNKNOWNPartner status outside the known mapping

State flow

Approved Rejected Insufficient balance Under analysis Approved Cancelled No confirmationwithin the window No outcomewithin ~25 min Settlement bank decideswithin 7 days Client sends PIXPOST /pix/out Risk andbalance check <code>PROCESSING</code> BACEN settlement <code>COMPLETED</code> · HTTP 200Webhook <code>pix.out.completed</code> <code>FAILED</code> · HTTP 422<code>errorCode</code> + <code>errorReason</code>Webhook <code>pix.out.failed</code> <code>PENDING_APPROVAL</code> · HTTP 202 <code>TIMEOUT</code> · HTTP 202Check GET /paymentsbefore retrying Late <code>COMPLETED</code>/<code>FAILED</code>Webhook with <code>late: true</code>
  • The outcome arrives via pix.out.completed / pix.out.failed. On TIMEOUT, the API also emits pix.out.timeout (indeterminate — check the statement; a late completed/failed may still arrive afterwards, with late: true and the same paymentId).
  • Retrying with the same Idempotency-Key returns the recorded outcome and does not run the payment again: on FAILED, the same rejection; on TIMEOUT, the indeterminate state. To try again after a FAILED, use a new Idempotency-Key and a new identifier. After a TIMEOUT, 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

#!/bin/bash
# Configuration
API_URL="https://tenant.api.corpx.com"
TOKEN="your_token_here"
TENANT_ID="tenant-suaempresa"
ACCOUNT_ID="your_account"
# Transfer details
PIX_KEY="12345678901"
PIX_KEY_TYPE="CPF"
AMOUNT=100.00
echo "=== PIX CASH OUT ==="
echo ""
echo "PIX Key: $PIX_KEY ($PIX_KEY_TYPE)"
echo "Amount: R$ $AMOUNT"
echo ""
# 1. Confirm (in production, wait for user confirmation)
read -p "Confirm transfer? (y/n): " confirm
if [ "$confirm" != "y" ]; then
echo "Transfer cancelled"
exit 0
fi
# 2. Execute transfer
echo ""
echo "Executing transfer..."
IDEMPOTENCY_KEY="cashout-$(date +%s)-$RANDOM"
transfer_response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/out" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d "{
\"amount\": $AMOUNT,
\"keyType\": \"$PIX_KEY_TYPE\",
\"key\": \"$PIX_KEY\",
\"description\": \"Transfer via script\"
}")
# Check result
STATUS=$(echo "$transfer_response" | jq -r '.status')
E2E=$(echo "$transfer_response" | jq -r '.endToEndId')
if [ "$STATUS" = "COMPLETED" ]; then
echo ""
echo "=== TRANSFER COMPLETED ==="
echo "Status: $STATUS"
echo "E2E: $E2E"
echo "$transfer_response" | jq
else
echo ""
echo "=== RESULT ==="
echo "$transfer_response" | jq
fi

Decode QR Code

Before paying, you can decode the QR Code to display beneficiary details to the user:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/decode" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-d '{
"emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
}'

Response (dynamic-immediate QR):

{
"key": "123e4567-e89b-12d3-a456-426614174000",
"amount": 150.00,
"originalAmount": 150.00,
"identifier": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
"decodeId": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
"qrCodeType": "dynamic-immediate",
"qrCodeTypeId": 1,
"allowChange": false,
"description": "Online purchase",
"payeeName": "EMPRESA EXEMPLO LTDA",
"payeeDocument": "12345678000190",
"bankIspb": "50871921",
"bankBranch": "0001",
"bankAccount": "123456-7",
"accountType": "CHECKING"
}

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

POST /v1/accounts/{accountId}/pix/out/qr-code/async — immediate 202:

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/async" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pay-qr-async-12345" \
-d '{
"emv": "00020126580014br.gov.bcb.pix...",
"amount": 150.00,
"description": "QR Code payment",
"identifier": "pay-qr-async-12345"
}'

Response:

{
"paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
"workflowId": "pix-out-{accountId}-{identifier}",
"runId": "b7c1f0e2-...",
"idempotencyKey": "pay-qr-async-12345",
"identifier": "pay-qr-async-12345",
"status": "ACCEPTED"
}

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)

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

{
"id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.out.completed",
"occurredAt": "2026-09-16T20:58:46.258668746Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-yourcompany",
"accountId": "{accountId}",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-yourcompany",
"accountId": "{accountId}",
"status": "SUCCESS",
"endToEnd": "E36741675202601281500001234567",
"transactionId": "162982-pix",
"amount": 100.00,
"currency": "BRL",
"description": "Supplier payment",
"identifier": "order-12345",
"originalTransactionId": "",
"initiatedAt": "2026-09-16T20:58:42.646763686Z",
"completedAt": "2026-09-16T20:58:46.258668746Z",
"key": {
"type": "CPF",
"key": "12345678901"
},
"payee": {
"name": "MARIA DA SILVA",
"document": "12345678901",
"bankCode": "001",
"bankIspb": "00000000",
"branch": "0001",
"accountNumber": "12345678"
}
}
}

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)

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

ErrorHTTPCauseSolution
key_not_found404PIX key does not exist in DICTCheck the key and its type
invalid_pix_key422Malformed key or mismatched key typeUse: CPF, CNPJ, EMAIL, PHONE, EVP
insufficient_funds422Insufficient balance as computed by the settlement bankCheck the account balance
limit_exceeded_daily / limit_exceeded_nightly / limit_exceeded_monthly / limit_exceeded_transaction422Account limit exceeded in the stated windowWait for the window to roll over or request an increase
partner_rejected422Refused by the settlement bank on risk/fraud groundsCheck the partner block for the stated reason
policy_denied422A tenant/account policy rule refused the transferCheck violations in the body and adjust the rule in the panel — Policies and Rules

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

  1. Always look up the key before transferring to validate the recipient
  2. Confirm with the user the details before executing
  3. Use a unique Idempotency Key per transfer — and reuse the same key when repeating the request, never a new one
  4. Save the E2E for tracking and support
  5. Configure webhooks to receive asynchronous confirmations
  6. 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