Limites de cashout

O teto de saída é por conta, por operação e por janela. Não é uma regra de política: pixOut.maxAmount não é mais avaliado. Quem estoura o teto recebe 422 limit_exceeded_transaction.

Ler o disponível

GET /v1/accounts/{accountId}/limits/available devolve PIX, TED, boleto e transferência interna, cada um com quatro janelas, usado e restante.

operation é pix_out, ted_out, boleto ou internal_out.

Sem teto efetivo a janela é fail-open: o pagamento não é barrado por limite local. A precedência do teto é a célula da própria conta, depois o padrão do tenant, depois o padrão global. source na janela diz qual dos três valeu. Um teto local de PIX não substitui o teto do liquidante.

GET /v1/accounts/{accountId}/pix/limits está deprecated. Devolve só os tetos de PIX do liquidante, sem usado, e aponta Link para /limits/available.

Pedir um aumento

POST /v1/accounts/{accountId}/limit-requests abre um pedido. Não muda o teto. A CorpX analisa e, ao aprovar, aplica o valor na hora. effectiveAt fica null enquanto não houver carência.

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 '{
    "operation": "pix_out",
    "window": "daytime",
    "requestedLimitBrl": 50000,
    "justification": "Folha de pagamento do mês.",
    "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": "Folha de pagamento do mês.",
  "identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
  "decisionMessage": null,
  "effectiveAt": null,
  "createdAt": "2026-10-02T18:00:01Z"
}

Nomes da janela

Nesta rota a janela é snake_case. No GET /limits/available o mesmo conceito é camelCase. Não misture os dois.

requestedLimitBrl tem de ser maior que o teto efetivo daquela janela. Sem teto, currentLimitBrl é 0 e qualquer valor positivo passa dessa checagem. Valor igual ou menor é 422 limit_request_not_above_current.

Idempotência

Idempotency-Key é obrigatório (até 128 caracteres) e identifier tem de ser idêntico ao header. A mesma chave devolve o pedido original com 201, mesmo que o corpo mude. Outra chave, com um pedido ainda em pending_review para a mesma operação e janela, é 409 limit_request_pending.

Quem pediu e o risco

X-Acting-Document é obrigatório: CPF (11 dígitos) ou CNPJ (14). É o documento que volta no webhook para você avisar a pessoa certa. X-Acting-Ip é o IP do operador, não o do seu servidor.

risk é opcional. action é allow, challenge ou deny; score, se vier, fica entre 0 e 1. O bloco só é armazenado e mostrado ao analista. deny não recusa o pedido.

justification é obrigatória, até 500 caracteres.

Acompanhar e cancelar

GET /v1/accounts/{accountId}/limit-requests?status= devolve { "items": [...] }. status filtra pending_review, approved, refused ou cancelled. Sem filtro, devolve todos.

GET .../limit-requests/{id} acrescenta decisionMessage, effectiveAt e events: [{ "at", "status", "message" }]. Só entram eventos públicos. A nota interna do analista não sai nesta API.

POST .../limit-requests/{id}/cancel cancela só pending_review. Qualquer outro status é 409 limit_request_closed. O cancelamento também dispara o webhook.

Status

Não existe estado “aprovado mas ainda não aplicado”.

Webhook limit_request.updated

Sai na aprovação, na recusa e no cancelamento. Não sai na abertura: o 201 já é a confirmação. Assinatura por conta recebe o evento porque accountId vai no envelope.

data: id, accountId, status, operation, window, requestedLimitBrl, approvedLimitBrl, decisionMessage, effectiveAt, actingDocument, identifier.

O exemplo completo está em Webhooks.

Erros