Beneficiarios

Un Beneficiario es un destinatario guardado: una persona o una empresa que no es el comercio, con sus datos bancarios ya cargados y comprobados, lista para recibir un Envío. Se registra una vez y a partir de ahí se le puede enviar dinero tantas veces como haga falta sin volver a escribir una cuenta.

No es una comodidad opcional: es la única forma de nombrar un destino. Un Envío lleva la referencia a un Beneficiario, nunca unos datos bancarios sueltos, así que no existe el caso de enviar dinero a alguien que no esté registrado antes.

Qué lleva un Beneficiario

Los datos se dividen en dos bloques con orígenes distintos, y confundirlos es el error corriente.

El primero es quién es, y lo pide Aloha igual para todos los destinos:

El correo es obligatorio aunque el dinero no viaje por ahí: es la dirección a la que Aloha le escribe cuando un Envío a su nombre se completa, y es lo único que el Beneficiario recibe de Aloha.

El país del Beneficiario y el país de su banco son dos campos distintos a propósito, y el que manda para todo lo operativo —la ruta, el mínimo, el plazo, los campos bancarios que hay que llenar— es el del banco. Alguien que vive en un país y cobra en una cuenta de otro es un caso normal, no una excepción.

El segundo bloque es dónde cobra, y ese no lo define Aloha. Ver el apartado siguiente.

Los tipos de relación son para el comercio, no para el dinero

Al registrar un Beneficiario se elige qué es del comercio, entre cinco opciones: Proveedor, Cliente, Empleado, Servicio y Otro.

La elección no cambia nada de la operación. No mueve el costo, ni el mínimo, ni la ruta, ni el plazo. Sirve para filtrar la lista de Beneficiarios y aparece en el aviso de Envío que recibe el comercio, y eso es todo lo que hace. Es una etiqueta de organización, y conviene tratarla como tal en vez de buscarle un efecto que no tiene.

Los datos bancarios los define el destino, y se consultan

Aquí está la parte que no se puede adivinar desde fuera. Qué campos hace falta llenar para pagar en un país lo decide ese país, no Aloha, y la lista cambia de uno a otro: en unos destinos basta un número de cuenta y un banco, en otros hacen falta además un tipo de cuenta, un documento de identidad del titular o un código de sucursal.

Por eso hay una operación que responde exactamente eso: dado el destino, devuelve la lista de campos con su tipo, sus límites de longitud, los valores que acepta cuando es una lista cerrada, y cuáles solo aplican según lo que se haya elegido en otro campo. Salvo esos condicionales, todos los campos que devuelve son obligatorios. El del banco es una de esas listas cerradas: no es texto libre, es un catálogo de bancos con su código.

De ahí sale la única regla dura de esta página: el código de un banco se lee de esa operación, nunca se fija dentro de una integración. Ese catálogo es dato, no constante: Aloha lo mantiene sincronizado, lleva su propia versión y su fecha de última actualización precisamente porque cambia. Y nada garantiza que el mismo banco lleve el mismo código en dos Ambientes distintos, así que un código copiado de una prueba es un código que puede mandar el dinero a otro sitio, o no mandarlo a ninguno. Se pide el catálogo del destino, en el Ambiente donde se va a usar, y se usa lo que devuelva.

Un detalle más sobre esos destinos: no todos son países. El valor que identifica al destino suele ser un código de país, pero algunos países tienen más de uno, porque se puede pagar en ellos por más de una vía o en más de una moneda, y cada vía pide sus propios campos. Es otra razón para preguntar por el destino concreto en vez de asumir que el país basta para deducir el formulario.

Editar un Beneficiario vuelve a pasar por esa comprobación, y el bloque bancario se guarda entero: hay que reenviarlo completo, no solo el campo que cambia.

Activo, inactivo y eliminado

Un Beneficiario se registra activo y puede desactivarse y volver a activarse cuando haga falta. La diferencia importa en un solo momento, pero es el que cuenta: solo un Beneficiario activo puede recibir un Envío. Ordenarlo contra uno desactivado se rechaza con ese motivo, y no es un error de datos sino de estado, así que lo que hay que hacer es activarlo, no corregir nada.

Desactivar no borra: el Beneficiario sigue en la lista, con sus datos, y basta con volver a activarlo. Es la forma de sacar a alguien de circulación sin perder lo que costó cargarlo.

Eliminar tampoco borra del todo. El Beneficiario desaparece de la lista y ya no se le puede enviar nada, pero los Envíos que ya se le hicieron siguen mostrándolo: un Envío pasado no se queda sin destinatario porque alguien haya limpiado la lista después.

Por qué se registra antes y no durante el envío

Separar el registro del envío parece un paso de más y es justo lo contrario. Los datos bancarios de un destino se comprueban contra las reglas de ese destino en el momento de guardarlos, que es un momento tranquilo: si falta un campo o un código no existe, lo que falla es un formulario, no un pago.

Si esa comprobación ocurriera al enviar, el mismo error aparecería con el monto ya decidido, el código de confirmación en la mano y el Saldo a punto de reservarse. Y como el error sería idéntico —un dato mal cargado—, el costo de equivocarse sería mucho mayor sin que el dato fuera más correcto.

El otro efecto es de permisos. Registrar Beneficiarios y ordenar Envíos son cosas distintas y llevan Permisos distintos, así que se puede dar de alta destinatarios sin poder mover dinero, y mover dinero solo hacia destinatarios que otra persona aprobó. Registrar uno exige además tener la cuenta verificada, tanto en identidad como en la parte comercial.

En la API

Los Beneficiarios se administran desde la API del panel, bajo /api/v1/clients:

Al registrar uno se manda name, email, country_code —el país del Beneficiario—, bank_country_code —el del banco, que es el que decide la ruta— y relationship_type, que acepta provider, client, employee, service y other. A eso se le suman los campos bancarios que haya devuelto payout-rules para ese bank_country_code, que van al mismo nivel que los demás.

payout-rules toma el destino en country_code y devuelve su catálogo de campos junto con una versión y la fecha en que se actualizó por última vez. Esos dos datos son la forma de darse cuenta de que el formulario de un destino cambió sin tener que compararlo campo a campo.

La lista acepta relationship_type, country_code, status, is_active y search —que busca por nombre y por correo—, y per_page hasta cincuenta.

Esa API es la que usa el panel; no es una superficie de integración y no se documenta aquí. Se nombra para poder emparejar lo que se ve en pantalla con la operación que hay detrás. La API externa no administra Beneficiarios: cubre el cobro y termina en la Billetera.

Relacionado

• Envíos a terceros — para qué sirve un Beneficiario, y el paso extra que exige usarlo.
• Retiros — la salida que no necesita Beneficiario, porque la cuenta es del comercio.
• Ambientes y Sandbox — por qué un dato válido en un Ambiente no lo es en otro.
• Saldo y Movimientos — qué le pasa al Saldo cuando el Envío sale.
• Glosario — la definición de cada término de esta página.