EnglishConceptsWithdrawal lifecycle

Withdrawal lifecycle

A withdrawal (POST /v1/withdraw) moves funds from your INFI account balance to an external PIX key.

Modes: automatic vs. manual approval

INFI can operate your account in two modes (configured by the team):

  • Automatic (default): the withdrawal is processed immediately. Balance is debited on the spot.
  • Manual approval: the withdrawal is created as pending_approval and awaits review by the INFI team. Balance is only debited after approval.

Diagram (automatic mode)

Preconditions

  • Available balance ≥ amountCents + feeCents (your account’s flat withdrawal fee).
  • Allowed key type for your account (cpf, cnpj, email, phone, evp).
  • Holder identity: a cpf key must match the responsible party’s CPF; a cnpj key must match the registered company’s CNPJ. For email, phone and evp, there is no holder-identity validation.
  • Approved KYC, account not blocked.

Pre-execution failures return a synchronous error — nothing is debited.

Edge cases

Insufficient balance

HTTP/1.1 422
{ "error": "Saldo insuficiente para realizar o saque." }

Provider communication error

HTTP/1.1 502
{ "error": "Erro ao processar saque. O valor não foi debitado." }

INFI performs a balance rollback automatically. If the inline rollback fails, an internal job reconciles within 10 minutes.

Indeterminate state

If the provider returns an ambiguous result (timeout, doubtful response), INFI:

HTTP/1.1 202
{
  "error": "Saque em verificação. Saldo debitado; status final em até 24h.",
  "transactionId": "...",
  "status": "failed_unknown"
}
Do not resend

In failed_unknown, do not duplicate the withdrawal. The PIX key may have been sent. Wait for reconciliation or query GET /v1/transactions/:id.

Interrupted confirmation

The provider confirmed but INFI could not return the response:

HTTP/1.1 502
{
  "error": "Saque iniciado mas confirmação interrompida. Consulte /v1/transactions/<id>",
  "transactionId": "..."
}

The operation was completed — only the response did not arrive. Query the returned transactionId.

Manual approval

When your account is in this mode, the response is:

HTTP/1.1 201
{
  "transactionId": "...",
  "status": "pending_approval",
  "amountCents": 5000,
  "feeCents": 0,
  "totalDeducted": 5000
}

The balance has not been debited yet. Once the INFI team approves, the status transitions to processing (balance debited) or is rejected. Track via webhook or polling.

[TO BE CONFIRMED WITH THE INFI TEAM]: the average manual approval lead time (or whether it is only for specific cases).

Charge lifecycleStatus