Clientes
Las personas y empresas por las que actúas. Son el remitente de un pago cuando el país lo pide.
Un cliente se registra con tu propio identificador (external_id), así lo encuentras siempre desde tu sistema.
| Campo | Obligatorio | Qué es |
|---|---|---|
external_id | Sí | Tu id, hasta 128 caracteres. |
type | Sí | individual o business. |
country | Sí | País de residencia o constitución (ISO alfa-2). |
display_name | Sí | Nombre, hasta 200 caracteres. |
profile | Según el país | Datos de identidad (abajo). |
metadata | No | Hasta 20 claves tuyas. Nunca datos personales. |
El perfil
| Campo | Para |
|---|---|
first_name, last_name | Personas. Van juntos. |
date_of_birth | Personas, AAAA-MM-DD. |
identity_document_type, identity_document | Van juntos. Tipos: DNI, RUC, CE, PAS, PTP, PASSPORT, NATIONAL_ID, RESIDENCE_PERMIT, TAX_ID, DRIVER_LICENSE. |
identity_document_country | País que emitió el documento. |
email, phone, tax_id | Contacto e impuestos. |
registration_number | Empresas. |
address | line1, line2, city, state, postal_code, country. |
Qué pide cada país lo dice customer_fields en capabilities. Por ejemplo, un pago en soles pide que el remitente sea una persona (individual) con nombre, apellidos, fecha de nacimiento, documento y ciudad.
Completa el perfil antes de pagar
Los datos del remitente se validan cuando el pago sale al banco, no al crearlo. Un pago con un remitente incompleto se acepta y luego falla con failure_code: invalid_instruction. Valida el perfil contra customer_fields antes de pagar.
Repetir el registro
Si envías otra vez el mismo external_id con los mismos datos, recibes el cliente existente (200). Con otros datos, 409 external_id_conflict.
Estados
status | Qué significa |
|---|---|
active | Normal. |
blocked | Caibo lo detuvo: no se paga a sus beneficiarios. |
closed | Cerrado, definitivo. |
Con PATCH/v1/customers/{id} cambias metadata o lo cierras (status: closed). compliance_status (unverified, pending, verified, rejected, review) lo cambian solo las verificaciones de Caibo.
Eventos: customer.created, customer.updated, customer.status_changed. Los eventos nunca incluyen el perfil.