Ciclo de un retiro

Un retiro (POST /v1/withdraw) mueve fondos desde el saldo de tu cuenta INFI hacia una clave PIX externa.

Modos: automático vs. aprobación manual

INFI puede operar tu cuenta en dos modos (configurado por el equipo):

Automático (por defecto): el retiro se procesa de inmediato. El saldo se debita en el acto.
Aprobación manual: el retiro se crea como pending_approval y espera revisión del equipo INFI. El saldo solo se debita tras la aprobación.

Diagrama (modo automático)

Precondiciones

Saldo disponible ≥ amountCents + feeCents (la tarifa fija de retiro de tu cuenta).
Tipo de clave permitido para tu cuenta (cpf, cnpj, email, phone, evp).
Titularidad: una clave cpf debe ser del CPF del responsable; una clave cnpj debe ser del CNPJ de la empresa registrada. Para email, phone y evp, no hay validación de titularidad.
KYC aprobado, cuenta no bloqueada.

Las fallas previas a la ejecución devuelven error síncrono — nada se debita.

Casos de borde

Saldo insuficiente

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

Error de comunicación con el proveedor

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

INFI hace rollback del saldo automáticamente. Si el rollback inline falla, un job interno concilia en hasta 10 minutos.

Estado indeterminado

Si el proveedor devuelve un resultado ambiguo (timeout, respuesta dudosa), INFI:

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

No reenviar

En failed_unknown, no dupliques el retiro. La clave PIX puede haberse enviado. Espera la conciliación o consulta GET /v1/transactions/:id.

Confirmación interrumpida

El proveedor confirmó pero INFI no logró devolver la respuesta:

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

La operación fue concluida — solo la respuesta no llegó. Consulta el transactionId devuelto.

Aprobación manual

Cuando tu cuenta está en ese modo, la respuesta es:

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

El saldo aún no se debitó. Cuando el equipo INFI aprueba, el estado pasa a processing (saldo debitado) o se rechaza. Sigue por webhook o polling.

[POR CONFIRMAR CON EL EQUIPO INFI]: el plazo medio de aprobación manual (o si es solo para casos específicos).

Ciclo de un cobro Estados