EspañolReferencia de la APIRetirosIniciar retiro PIX

Iniciar retiro PIX

POST/v1/withdraw
Inicia un retiro PIX a una clave externa.
Precondiciones

Saldo disponible ≥ amountCents + feeCents, KYC aprobado, cuenta no bloqueada, tipo de clave PIX permitido. Las fallas síncronas no debitan saldo.

Encabezados

EncabezadoObligatorioDescripción
AuthorizationBearer <TU_API_KEY>
Content-Typeapplication/json

Cuerpo

{
  "amountCents": 5000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "description": "Pago de comisiones",
  "externalRef": "withdraw-2026-05-08-001"
}
CampoTipoObl.Descripción
amountCentsenteroValor en centavos. Mínimo: 100.
pixKeystringClave PIX del destinatario. Máx. 150 caracteres.
pixKeyTypestringcpf, cnpj, email, phone o evp (ver restricciones por modo abajo). Las variaciones de case y whitespace se normalizan — "CPF", "Cnpj", " email " son aceptados.
descriptionstringnoDescripción libre. Máx. 200 caracteres.
externalRefstringnoRecomendado. Tu clave de idempotencia (máx. 100 caracteres). Dos requests con el mismo externalRef reciben la misma transacción — protege contra duplicación en reintentos. Ver callout abajo.
recipientIdstringnoID del destinatario tercero pre-aprobado por el equipo INFI (24 caracteres hex). Sin este campo, el retiro va al titular (CPF/CNPJ registrado). Con este campo, el retiro va al tercero autorizado. Ver “Retiro a terceros” abajo.
Idempotencia vía externalRef (recomendado)

Siempre que sea posible, envía un externalRef único por retiro. Si tu llamada falla con timeout, caída de red o tu sistema cae, reenvía el request con el mismo externalRef — la respuesta devolverá la transacción original con idempotent: true, sin crear retiro duplicado.

Sin externalRef, los reintentos crean retiros separados — riesgo real de duplicación. Usa siempre algo único y estable (p.ej., ID interno de tu sistema, UUID).

Dos modos de retiro

Modo 1 — Retiro al titular (por defecto, sin recipientId)

Comportamiento por defecto. Acepta solo claves de tipo cpf o cnpj que pertenezcan al titular de la cuenta:

  • pixKeyType: "cpf" → la clave debe coincidir con el CPF del responsable registrado.
  • pixKeyType: "cnpj" → la clave debe coincidir con el CNPJ de la empresa registrada.

Otros tipos (email, phone, evp) solo se aceptan en el Modo 2 (tercero autorizado).

Modo 2 — Retiro a tercero autorizado (con recipientId)

Para retirar a un CPF/CNPJ que no es el titular (p.ej. proveedor recurrente, transferencia inter-empresas), el destinatario debe estar pre-aprobado por el equipo INFI.

Cómo solicitar aprobación: contacta a soporte INFI informando el nombre legal y CPF/CNPJ del destinatario. El equipo evalúa la operación (compliance/AML) y, si se aprueba, el recipientId (24 caracteres hexadecimales) queda disponible vía GET /v1/recipients. No hay endpoint de auto-registro — toda aprobación es manual con auditoría.

Restricciones en el Modo 2:

  • Acepta los 5 tipos de clave PIX (cpf, cnpj, email, phone, evp).
  • Para pixKeyType: "cpf" o "cnpj": la clave debe coincidir exactamente con el documento del destinatario aprobado.
  • Para email/phone/evp: INFI confía en que el destino se resuelva en el DICT del BACEN para el documento aprobado. El PSP rechaza si hay divergencia.
  • Cada retiro a tercero dispara una alerta interna en INFI (auditoría continua).
Aprobación previa obligatoria

No puedes retirar a cualquier CPF/CNPJ vía API — solo a los destinatarios que el equipo INFI aprobó previamente para tu cuenta. Cada aprobación pasa por verificación de compliance y genera audit trail.

Respuesta 201 Created

Modo automático (por defecto)

{
  "transactionId": "...",
  "status": "processing",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100
}

El saldo ya fue debitado (totalDeducted = amountCents + feeCents). Espera el webhook TRANSFER_PAID o consulta el estado.

Modo aprobación manual

{
  "transactionId": "...",
  "status": "pending_approval",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100
}

Saldo no debitado aún. Espera revisión del equipo INFI. Ver Ciclo de un retiro.

Respuesta 200 OK (reintento idempotente)

Cuando reenvías un request con un externalRef que ya existe, la respuesta tiene status 200 (en lugar de 201) e incluye idempotent: true:

{
  "transactionId": "...",
  "status": "processing",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100,
  "idempotent": true
}

El transactionId es el mismo de la primera llamada. No se crea un nuevo retiro, no se debita saldo adicional.

Respuestas de error / casos especiales

HTTPCuerpoSignificado
400"amountCents deve ser inteiro ≥ 100..."Valor inválido.
400"pixKey obrigatória."Clave faltante.
400"pixKeyType deve ser 'cpf', 'cnpj', 'email', 'phone' ou 'evp'. Recebido: '<valor>'."Tipo desconocido tras la normalización.
400"Saque para chaves email/telefone/aleatória exige destinatário autorizado."pixKeyType es email/phone/evp pero no enviaste recipientId. Usa Modo 2.
400"recipientId inválido."Formato de recipientId errado (esperado: 24 caracteres hex).
400"Tipo de chave (CPF/CNPJ) não bate com o tipo do documento do destinatário."Enviaste pixKeyType: "cpf" pero el destinatario aprobado es CNPJ (o al revés).
404"Destinatário autorizado não encontrado."recipientId no existe para esta cuenta. Verifica con soporte.
422"Destinatário desativado pelo time INFI. Saque cancelado."El destinatario fue desactivado (compliance/AML). Solicita re-aprobación.
403"Chave PIX (CPF/CNPJ) não corresponde ao documento do destinatário autorizado."Modo 2 con cpf/cnpj exige clave PIX igual al documento aprobado.
400"Saque acima do máximo..."Excede el límite por transacción.
401"API key inválida ou revogada."
403"Tipo de chave PIX 'X' não autorizado para esta conta."Restricción de la cuenta.
403"Saque com chave CNPJ só permitido para o CNPJ cadastrado..."Titularidad.
403"Saque com chave CPF só permitido para o CPF do responsável..."Titularidad.
403"IP de origem não autorizado..."Lista de IPs permitidos.
422"Saldo insuficiente para realizar o saque."Saldo + tarifa > disponible.
429"Aguarde alguns segundos antes do próximo saque."Rate limit anti-burst (1/segundo).
429"Muitos saques em curto intervalo. Aguarde alguns instantes."Rate limit anti-burst (2/minuto).
429"Limite de saques atingido."Rate limit horario (10/hora).
502"Erro ao processar saque. O valor não foi debitado."Falla del proveedor con rollback.
502"Saque iniciado mas confirmação interrompida..."Operación concluida, respuesta interrumpida. Consulta el transactionId devuelto.
202"Saque em verificação. Saldo debitado..."Estado indeterminado. No reenviar. Ver failed_unknown.

Ejemplos

curl -X POST https://api.internationalfinance.com.br/v1/withdraw \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000,
    "pixKey": "12345678901",
    "pixKeyType": "cpf",
    "description": "Pago",
    "externalRef": "withdraw-2026-05-08-001"
  }'

Ejemplo: retiro a tercero autorizado (Modo 2)

Usa el recipientId devuelto por el equipo INFI tras aprobar a tu destinatario:

curl -X POST https://api.internationalfinance.com.br/v1/withdraw \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000,
    "pixKey": "proveedor@empresa.com",
    "pixKeyType": "email",
    "recipientId": "abc123def456abc123def456",
    "description": "Pago proveedor X",
    "externalRef": "supplier-payment-2026-05-15"
  }'

La respuesta tiene el mismo formato que en los ejemplos anteriores. Puedes mezclar cpf/cnpj/email/phone/evp en pixKeyType siempre que el destinatario esté aprobado y (para cpf/cnpj) la clave coincida exactamente con el documento aprobado.