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:
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:
- Account — an own ceiling stored in the ledger.
- Tenant default — applies when the account has no cell of its own.
- Global default — the same, when the tenant has not set one either.
- Previous register (
source: legacy) — the MySQL ceilings from before the ledger, only while the operation has no own ceiling. - Operator — internet-banking credential only. The BaaS credential does
not call that route. On cashout,
min(account, operator). - 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:
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.
201:
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
There is no “approved but not yet applied” state.
Events
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.