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.
The source account is {accountId} in the path. The API checks available
balance before sending.
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=(oridentifier)GET /v1/accounts/{accountId}/pix/paymentsand.../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.
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.
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
POST /v1/accounts/{accountId}/boleto/previewwith the typed line.- 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). POST /v1/accounts/{accountId}/boleto/pay→ always202,paymentIdasbol_{uuid}.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.
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.