Skip to navigation

Pay

PIX, TED, boleto and internal transfers leave your account. The body is the public contract; what changes is the host and the signature.

Host: https://client.api.corpx.com. Every write carries Idempotency-Key (it enters the canonical string). Amounts in BRL, at most 2 decimal places.

Do not send X-Transaction-Pin or X-Acting-Document. The credential proves possession with the private key and IP. PIN and hour locks are on the holder’s screen — see Locks.

PIX by key

To show the name first: GET /v1/accounts/{accountId}/pix/key/{pixKey}. The transfer looks the key up in DICT either way.

The key goes in the path in DICT format and encoded as a URL path segment: CPF and CNPJ digits only, phone with +55 (%2B5511999998888), email with the @ encoded (fulano%40exemplo.com), random key as the UUID. A phone without +55 is read as a CPF. Examples and what does not work in PIX key lookups.

Sign the encoded path, exactly as it goes on the request: /v1/accounts/{accountId}/pix/key/fulano%40exemplo.com, not .../fulano@exemplo.com. See Request signing.

curl -X POST "https://client.api.corpx.com/v1/accounts/$ACCOUNT_ID/pix/out" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Idempotency-Key: $UUID" \
-H "Content-Type: application/json" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $SHA" \
-H "X-Request-Signature: $SIG" \
-d '{
"amount": 100.00,
"keyType": "CPF",
"key": "12345678901",
"description": "Order 12345",
"identifier": "order-12345"
}'
FieldRequiredNotes
amountYes≥ 0.01; 2 decimals
keyTypeYesCPF, CNPJ, EMAIL, PHONE, EVP
keyYesMatches the type
descriptionNoMax 140
identifierNoYour reconciliation; appears on the statement

The source account is {accountId} in the path. The API checks available balance before sending.

HTTPTypical statusWhat to do
200COMPLETEDDone
202TIMEOUT / PENDINGIndeterminate: check statement or webhook before resending
207partner timeoutSame: do not assume debit or credit
422FAILEDImmediate refusal (partner_rejected, insufficient_funds, pix_key_not_found)

PENDING_APPROVAL on lookups means the settlement bank held the order (anti-fraud), not that you owe an approval. TIMEOUT is not final: the API keeps polling for up to 7 days and, if it settles or refuses, you receive pix.out.completed / pix.out.failed with late: true and the same paymentId.

For volume, prefer POST .../pix/out/async (202 immediately). Sync has a per-account cap (today 100 req/min; heading toward 10).

There is also PIX by bank details (.../pix/out/bank-account and .../async) and QR payment (.../pix/out/qr-code/async — the sync route is deprecated). The legacy path POST /v1/pix-out (accountId in the body) was removed and returns 410 gone: always use POST /v1/accounts/{accountId}/pix/out.

Look up an outbound PIX

  • GET /v1/accounts/{accountId}/pix/transactions?endToEndId= (or identifier)
  • GET /v1/accounts/{accountId}/pix/payments and .../pix/payments/lookup

To wait for the outcome without polling, call the lookup with waitForFinalStatus (seconds, at most 10). The response comes when the PIX reaches COMPLETED, FAILED or REVERSED, or when the wait expires, with the last status read. If the PIX never appeared at the settlement bank, it returns 404. Only the lookup accepts the parameter, and the client timeout must be at least 20 s with waitForFinalStatus=10.

Webhooks: pix.out.completed, pix.out.failed, pix.out.timeout.

Refund an inbound PIX

POST /v1/accounts/{accountId}/pix/out/refund with the original E2E. Partial refunds are allowed, each with its own Idempotency-Key and identifier. BACEN window: 90 days. Without the E2E, take it from the statement, the pix.in.completed webhook or the QR lookup.

{
"originalEndToEnd": "E36741675202601281435001234567",
"amount": 150.00,
"reason": "user-requested"
}

TED

POST /v1/accounts/{accountId}/ted/out — async (202, status: PROCESSING). BACEN window: business days 06:30–17:00. Outside it, scheduled for the next business day.

{
"value": 5000.00,
"bankCode": "001",
"branch": "1234",
"account": "56789",
"accountType": "CHECKING",
"taxNumber": "12345678900",
"holderName": "JOAO DA SILVA",
"description": "Invoice 12345",
"identifier": "fornecedor-acme-2026-05"
}

bankCode is a 3-digit Compe. An 8-digit ISPB is refused (400 invalid_bank_code). The COMPE/ISPB pair for the dropdown is in the Bank catalog. Look up GET /v1/accounts/{accountId}/ted/{tedId}. Webhooks: ted.out.requested, ted.out.confirmed, ted.out.failed.

Day to day, PIX is usually the better choice (24/7, instant). TED fits when the counterparty only accepts TED or the amount is above the account’s PIX cap.

Boleto

  1. POST /v1/accounts/{accountId}/boleto/preview with the typed line.
  2. Pay the preview’s totalUpdated — not the face amount. On an overdue slip they differ; the settlement bank refuses any other value (422 boleto_amount_mismatch).
  3. POST /v1/accounts/{accountId}/boleto/pay → always 202, paymentId as bol_{uuid}.
  4. GET /v1/accounts/{accountId}/boleto/payments/{paymentId}.

Redo the preview on the payment day: interest and fines move.

Internal transfer

Between accounts at the same bank, no PIX. Instant.

DestinationPath
API accountIdPOST .../transfers/internal
Branch and accountPOST .../transfers/internal/by-bank-account
CPF/CNPJPOST .../transfers/internal/by-document

There is a name preview at GET .../transfers/internal/lookup/{document} (first name in full; other surnames become initial + ***).

Idempotency

Idempotency-Key is the identity of the HTTP attempt. Repeating the same key, path and body returns the original result — not a second debit. Changing the body with the same key is a conflict. Detail: Idempotency.

identifier in the body is your reconciliation key. They coexist.

Holder locks

If the payment returns 423 cashout_locked, 403 cashout_outside_hours or 403 cashout_source_ip_not_allowed, the holder configured a block, window or IP list in internet banking. Read what is in force in Locks. You do not change those locks through the API.