Ciclo de um saque

Um saque (POST /v1/withdraw) move fundos do saldo da sua conta INFI para uma chave PIX externa.

Modos: automático vs aprovação manual

A INFI pode operar a sua conta em dois modos (configurado pela equipe):

Automático (default): o saque é processado imediatamente. Saldo é debitado na hora.
Aprovação manual: o saque é criado como pending_approval e aguarda revisão da equipe da INFI. Saldo só é debitado após aprovação.

Diagrama (modo automático)

Pré-condições

Saldo disponível ≥ amountCents + feeCents (a taxa fixa de saque da sua conta).
Tipo de chave permitido para sua conta (cpf, cnpj, email, phone, evp).
Titularidade: chave do tipo cpf deve ser do CPF do responsável; chave cnpj deve ser do CNPJ da empresa cadastrada. Para email, phone e evp, não há validação de titularidade.
KYC aprovado, conta não bloqueada.

Falhas pré-execução retornam erro síncrono — nada é debitado.

Casos de borda

Saldo insuficiente

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

Erro de comunicação com o provedor

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

A INFI faz rollback do saldo automaticamente. Se o rollback inline falhar, um job interno reconcilia em até 10 minutos.

Estado indeterminado

Se o provedor retorna ambíguo (timeout, resposta dúbia), a INFI:

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

Não reenvie

Em failed_unknown, não duplique o saque. A chave PIX pode ter sido enviada. Aguarde a reconciliação ou consulte GET /v1/transactions/:id.

Confirmação interrompida

Provedor confirmou, mas a INFI não conseguiu retornar a resposta:

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

A operação foi concluída — apenas a resposta não chegou. Consulte o transactionId retornado.

Aprovação manual

Quando a sua conta está nesse modo, a resposta é:

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

O saldo ainda não foi debitado. Quando a equipe da INFI aprova, o status transita para processing (saldo debitado) ou rejeita. Acompanhe via webhook ou polling.

[VERIFICAR COM EQUIPE INFI]: confirmar prazo médio de aprovação manual (ou se é apenas para casos específicos).

Ciclo de uma cobrança Status