Skip to navigation

Limits guide

The cashout ceiling is per account, per operation and per window. It is not a policy rule: pixOut.maxAmount is no longer evaluated. Exceeding the ceiling returns 422 limit_exceeded_transaction.

Limit types

Four operations: pix_out, ted_out, boleto, internal_out.

Four windows, in America/Sao_Paulo:

Window on the requestField on GET /limits/availableMeaningLedger hours
single_transfersingleTransferOne operation—
daytimedaytimeDaytime window06:00–20:00
nighttimenighttimeNighttime window20:00–06:00
monthlymonthlyCalendar month—

Do not mix the names. On the request the window is snake_case. On the read, the per-transaction window is camelCase. daytime, nighttime and monthly match.

Ceiling layers, from the most specific to the most general:

  1. Account — an own ceiling stored in the ledger.
  2. Tenant default — applies when the account has no cell of its own.
  3. Global default — the same, when the tenant has not set one either.
  4. Previous register (source: legacy) — the MySQL ceilings from before the ledger, only while the operation has no own ceiling.
  5. Operator — internet-banking credential only. The BaaS credential does not call that route. On cashout, min(account, operator).
  6. Settlement-bank PIX ceiling — independent. A local PIX ceiling does not replace it; the settlement bank still enforces its own.

How it is calculated

For each cell (operation × window) the precedence is:

account's own ceiling
│ (none)
▼
previous register for the operation, if it still has no own ceiling
│ (none, or the operation already has an own ceiling)
▼
tenant default
│ (none)
▼
global default
│ (none)
▼
fail-open: the window does not block

With no effective ceiling the window is fail-open: the payment is not blocked by a local limit. limitBrl is null. On the windows that accumulate, usedBrl and availableBrl are null too, and the screen shows the window as open.

The previous register has no monthly window and uses 07:00–22:00 / 22:00–07:00. The ledger uses 06:00–20:00 / 20:00–06:00. The first own ceiling of an operation turns the legacy view off for the whole operation. On approval of a request (and on any account-ceiling write), the other windows that still came from the previous register become own ceilings, at the same amounts. An open monthly window is not stored. From then on the hours are the ledger hours.

singleTransfer is the ceiling of each payment. It does not accumulate: the response carries limitBrl (and scope / source when the ledger has them) and omits usedBrl, availableBrl and resetsAt.

usedBrl is what already left in the window that is open. availableBrl is what still fits. A window that is not open shows the next occurrence, with used zero and no resetsAt: the period that already closed no longer counts. The month is the calendar month, not thirty rolling days. With an operator ceiling, cashout availability is the lower of the account and the operator.

Read what is available

GET /v1/accounts/{accountId}/limits/available returns the four operations, each with four windows. The ones that accumulate carry used and remaining. singleTransfer carries only the ceiling.

source on the window says where the ceiling came from: account, tenant_default, global_default or legacy. On the operation item, source: legacy means the whole operation is still on the previous register.

GET /v1/accounts/{accountId}/pix/limits is deprecated. It returns only the settlement-bank PIX ceilings, without used amounts, and points Link at /limits/available.

Ask for an increase

Through the API or the Limits page in the API backoffice. Both open the same request. A new request is created as awaiting_documents and stays out of the queue until POST .../submit. Catalog documents are optional: submit works with no file. A file that was uploaded must be antivirus-approved before submit. The status then becomes pending_review and CorpX reviews it. This does not change the ceiling. On approval, the amount is applied immediately. The approved amount may be lower than the request, never higher. effectiveAt stays null: there is no waiting period on the account ceiling.

In the backoffice, the person asking types the CPF of who is operating (11 digits, valid check digits) and confirms with TOTP. The IP sent is the panel server’s, not the browser’s. A viewer can only read. Tenant admin and tenant manager can create and cancel.

curl -X POST "https://tenant.api.corpx.com/v1/accounts/$ACCOUNT_ID/limit-requests" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21" \
-H "X-Acting-Document: 39053344705" \
-H "X-Acting-Ip: 200.10.20.30" \
-d '{
"operations": ["pix_out", "boleto", "ted_out"],
"window": "daytime",
"requestedLimitBrl": 50000,
"justification": "Monthly payroll.",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"risk": {
"provider": "castle",
"action": "allow",
"score": 0.12,
"policyName": "ib-limit-increase",
"evaluatedAt": "2026-10-02T18:00:00Z"
}
}'

201:

{
"id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
"status": "pending_review",
"operation": "pix_out",
"window": "daytime",
"currentLimitBrl": 20000,
"requestedLimitBrl": 50000,
"approvedLimitBrl": null,
"justification": "Monthly payroll.",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"decisionMessage": null,
"effectiveAt": null,
"createdAt": "2026-10-02T18:00:01Z"
}

Use operation to keep the single-operation form, or operations to open 1–4 distinct operations in one bundle. Do not send both fields. The bundle shares the window, requested amount, documents, messages and review decision. Each operation remains visible in bundle.items, with its current and approved ceilings. For single_transfer, TED is capped at R$ 14,999.99; when the account is already at that cap, TED appears in skipped with reason: ted_single_cap and the other operations continue normally.

requestedLimitBrl must be greater than the effective ceiling of that window. currentLimitBrl is that ceiling when the request was opened, including when it still comes from the previous register. It is 0 only when the window is open. An equal or lower amount is 422 limit_request_not_above_current.

On an account still on the previous register, approval stores the requested window and also the other legacy windows of the same operation, at the amounts they had. The hours become the ledger hours.

Idempotency

Idempotency-Key is required (up to 128 characters) and identifier must be identical to the header. The same key returns the original request with 201, even if the body changes, and does not open another request. Another key, while a request is still pending_review for the same operation and window, is 409 limit_request_pending.

Who asked, and risk

X-Acting-Document is required: CPF (11 digits) or CNPJ (14). It is the document that comes back on the webhook so you can notify the right person. X-Acting-Ip is the operator’s IP, not your server’s. In the API backoffice the panel fills both: the CPF the operator typed and the BFF source IP.

risk is optional. action is allow, challenge or deny; score, when present, is between 0 and 1. The block is only stored and shown to the reviewer. deny does not refuse the request.

justification is required, up to 500 characters.

Documents

GET /v1/limit-requests/document-types?holderType=PF|PJ returns the catalog (required and additional). PF is an 11-digit holder document; PJ is 14. Labels come from the API. No catalog type is mandatory: required is empty and every type is listed under additional.

Upload follows the MED evidence flow: POST .../evidence/upload-url, a direct PUT, then POST .../evidence/add. Every file is scanned. downloadUrl exists only when scanStatus is APPROVED. Limits: 5 MB per file, 30 files and 60 MB per request. Types: pdf, jpeg, png, webp.

POST .../submit moves awaiting_documents to pending_review even with no file. The catalog marks no type as required. Without submit within 7 days the request is cancelled (reason: expired).

Files are accepted only in awaiting_documents or info_requested. When the reviewer asks for more, the status becomes info_requested. Reply with files and an optional text (POST .../messages), then submit again. A file uploaded before that message does not satisfy the asked type.

Track and cancel

GET /v1/accounts/{accountId}/limit-requests?status= returns { "items": [...] }. status filters awaiting_documents, pending_review, info_requested, approved, refused or cancelled. With no filter, every status is returned.

GET .../limit-requests/{id} adds decisionMessage, effectiveAt and events: [{ "at", "status", "message" }]. Only public events are included. The reviewer’s internal note is not on this API.

POST .../limit-requests/{id}/cancel cancels awaiting_documents, pending_review or info_requested. Any other status is 409 limit_request_closed. Cancellation also sends the update webhook. Cancelling does not ask for TOTP in the backoffice.

Status

StatusMeaning
awaiting_documentsOpen, outside the queue, until submit. Expires in 7 days.
pending_reviewIn the queue. The ceiling is still the old one.
info_requestedThe reviewer asked for more. Outside the queue. Expires in 7 days.
approvedApproved and applied. approvedLimitBrl is the ceiling that took effect and may be lower than the request.
refusedRefused. The ceiling did not change. decisionMessage explains.
cancelledCancelled by the requester, or because submit did not arrive in time.

There is no “approved but not yet applied” state.

Events

EventListen for
limit_request.createdA request was opened, including by another operator in the backoffice. It is not sent again on a replay of the same Idempotency-Key.
limit_request.updatedThe request changed. reason is submitted, decided, info_requested or expired.
account.limits.updatedA ceiling actually changed (approval, staff or the account owner). It is not sent for a tenant or global default, nor when an already scheduled operator relaxation takes effect.

Approval sends limit_request.updated and account.limits.updated, with no order guaranteed between them. Deduplicate by the envelope id. When the amount matters, read GET /limits/available again.

A subscription with an empty event list receives everything. A subscription with an explicit list receives an event only if it is on the list.

The full envelope for each event is in Webhooks.

Errors

CodeHTTPWhen
missing_idempotency_key400No Idempotency-Key, or a key longer than 128 characters
invalid_identifier400identifier differs from the key
invalid_justification400Empty or longer than 500 characters
invalid_risk400action or score outside the contract
acting_document_required400No X-Acting-Document
invalid_acting_document400Document that is neither CPF nor CNPJ
limit_request_operation_unavailable422operation or window outside the table above
limit_request_not_above_current422Requested (or approved) amount does not exceed the effective ceiling
limit_request_above_requested422Approved amount above the request
limit_request_pending409An open request already exists for the same operation and window
limit_request_closed409Attachment, submit or cancel on a request that no longer accepts it
limit_request_documents_missing422submit when a type marked required has no APPROVED file. The current catalog marks none. details.missing lists the types
limit_request_info_missing422submit while info_requested without what was asked
limit_request_document_type_invalid422documentType is not in this account’s catalog
limit_request_not_found404id does not exist on this account