Vinculación de Clientes

Descripción General

Esta guía te ayuda a conectar la Plataforma con el perfil en el Banco Sponsor y a vincular Cuentas financieras usando la plataforma Passport PaaS. Este proceso simple y eficaz permite que tu entidad cree rápidamente su Customer, vincule Cuenta(s) y quede lista para pagos fáciles y seguros. Al completar estos pasos, estarás listo para Pagos y creación de Llaves a través de la infraestructura nacional Bre-B.

Si gestionas pagos bajo tu empresa (especialmente si cuentas con Licencia de Pagos), asegúrate de que los datos del cliente ingresados aquí coincidan con la información legal registrada manualmente. Piensa en este paso como el registro digital de tu negocio, que te prepara para administrar tus cuentas en el Banco Sponsor.

Valor para tu Negocio

Acelera el registro de clientes, habilitando un acceso más rápido a servicios financieros.
Reduce papeleo y errores manuales, mejorando la eficiencia operativa.
Crea una experiencia fluida al incorporar usuarios de forma digital y ágil.

Vincula tu Perfil

Durante el proceso de onboarding, el Comercio habrá sido creado manualmente en el Banco Sponsor. Este proceso de debida diligencia reforzada asegura que el modelo de negocio y los flujos de dinero sean adecuados para aceptar pagos a través de la entidad financiera licenciada.

Es un paso necesario para prepararte a ofrecer productos financieros mediante el modelo del Banco Sponsor, ya que el procesamiento de pagos se considera una actividad de alto riesgo para los equipos de cumplimiento. En la plataforma Passport, el perfil se guarda como un Customer, vinculado al perfil del Customer en el Banco Sponsor.

Detalles de la Solicitud (Vincular un Comercio)

Vincular un Comercio: Ejemplo de Solicitud

Para más información sobre el Endpoint, revisa el documento: Vincular Merchant.

Parámetro	Descripción
business_name	Nombre legal registrado de tu empresa o la de tu cliente.
mobile_phone_number	Número de celular en formato de Colombia (incluyendo código de país +57).
identification_type	Tipo de documento (NIT).
identification_number	Número NIT oficial del negocio.
address	Objeto con la dirección registrada del negocio.
merchant_category_code	Identificador de cuatro dígitos que define el giro del negocio; asignado por el organismo licenciante.

Vincular un Comercio: Cuerpo de la Solicitud

JSON
    
xxxxxxxxxx
 
curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.comv/v1/customers/business/link' \--header 'Content-Type: application/json' \--header 'Authorization: YOUR_ACCESS_TOKEN' \--data-raw '{    "business_name": "Test Merchant E0C0M",    "email": "Woym8v4H@example.com",    "mobile_phone_number": "+573331115443",    "identification_type": "NIT",    "identification_number": "253499214",    "address": {        "line_1": "Carrera 123",        "line_2": "# 345",        "city": "Bogota",        "state": "Bogota DC",        "country": "CO",        "zip_code": "93111",    "merchant_category_code": "0412"}'
Copy

Vincular un Comercio: Ejemplo de Respuesta

Parámetro	Descripción
id	Identificador único asignado a este cliente BUSINESS. Lo usarás para vincular una cuenta en el siguiente paso.
business_name	Nombre legal registrado del negocio.
email	Correo del negocio utilizado para validación y contacto.
mobile_phone_number	Número de contacto almacenado.
identification_type	Tipo de documento (`NIT`).
identification_number	Número del NIT del negocio.
address	Contiene los datos dirección correspondiente a la dirección registrada de la empresa.
created_at	Marca de tiempo cuando el objeto de cliente fue creado (vinculado) en la plataforma.
updated_at	Marca de tiempo de la actualización del objeto de cliente en la plataforma.

Vincular un Comercio: Cuerpo de la Respuesta

JSON
    
xxxxxxxxxx
 
{    "type": "BUSINESS",    "id": "5ae28bc6-49e1-4710-a2d9-7b2f0f488ecb",    "email": "Woym8v4H@example.com",    "business_name": "Test Business E0C0M",    "mobile_phone_number": "573331115443",    "identification_type": "NIT",    "identification_number": "253499214",    "address": {        "line_1": "Carrera 123",        "line_2": "# 345",        "city": "Bogota",        "state": "Bogota DC",        "country": "CO",        "zip_code": "93111",    "merchant_category_code": "0412"    "created_at": "2025-09-26T23:12:43.784Z",    "updated_at": "2025-09-26T23:12:43.784Z"}
Copy

Ahora que el perfil se ha vinculado correctamente al cliente en el Banco Sponsor, estás listo para vincular la Cuenta bancaria (o Cuentas) que se abrió durante el proceso manual de onboarding. El identificador del cliente id devuelto en el paso anterior es esencial y se usará como customer_id en solicitudes futuras.

Los clientes no pueden transar hasta que tengan una Cuenta. Es esencial para acceder a los servicios financieros de la plataforma, como pagos en tiempo real.

Vincular una Cuenta Bancaria

Con el customer_id generado y completado el proceso de vincular un comercio, ahora puede realizarse el vínculo entre objetos. Los clientes de tipo Business solo pueden tener cuentas del tipo:

ORDINARY: Recomendado para Comercios, sin límites predefinidos de transacciones ni restricciones. Estas cuentas se configuran manualmente para estar exentas de impuestos locales a transacciones.

Un Comercio puede tener múltiples Cuentas bancarias (relación 1:M). No hay límite en el número de Cuentas que pueden abrirse, pero cada apertura requiere un proceso manual similar a la aprobación original (aunque acelerado).

Valor para tu Negocio

Cuenta bancaria programable para facilitar diversas transacciones.
Habilita el uso inmediato de servicios financieros mediante Cuentas disponibles al instante.

Ejemplo de Solicitud

Usa el customer_id obtenido en la llamada Identificador único devuelto en la respuesta de Vincular Comercio.

Parámetro	Descripción
customer_id	ID del cliente obtenido en el paso anterior.
type	Tipo de cuenta: `ORDINARY` (depósito ordinario).
number	Número de la Cuenta proporcionado durante el onboarding manual.

Cuerpo de la Solicitud

JSON
    
 
curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/accounts' \--header 'Content-Type: application/json' \--header 'Authorization: <YOUR_ACCESS_TOKEN>' \--data '{    "customer_id": "5ae28bc6-49e1-4710-a2d9-7b2f0f488ecb",    "type": "ORDINARY",    "number": "1234123400"}'
Copy

Formato de la Respuesta

Parámetro	Descripción
customer_id	ID del cliente vinculado a la cuenta.
available_balance	Objeto con el monto y moneda del saldo disponible de la Cuenta.
available_balance.currency	Moneda de la cuenta (COP – peso colombiano).
available_balance.value	Valor monetario actualmente disponible en la Cuenta.
id	Identificador único de la Cuenta recién vinculada. Lo usarás para transacciones y creación de llaves.
number	Número interno asignado a la Cuenta; actúa como identificador dentro del Banco Sponsor.
type	Tipo de cuenta: `ORDINARY` (sin límites de transacción).
pending_balance	Objeto con los montos y moneda de transacciones aún no liquidadas.
pending_balance.currency	Tipo de moneda: COP - Peso Colombiano.
pending_balance.value	El monto disponible en la cuenta.
created_at	Marca de tiempo de creación de la Cuenta en la plataforma Passport.
updated_at	Marca de tiempo de la última actualización de la Cuenta en la plataforma Passport.

La notación objeto.parámetro hace referencia a la relación jerárquica dentro de una respuesta JSON. Por ejemplo, pending_balance.currency indica el parámetro currency dentro del objeto pending_balance.

Próximos Pasos

Ahora que la cuenta del cliente está creada, el siguiente paso es crear una llave Bre-B, lo que habilita el uso de pagos instantáneos y seguros a través de nuestra infraestructura.

Soporte y Recursos

Explora la Colección de Postman para ver ejemplos prácticos.
Contacta a tu representante de Passport o a soporte técnico si necesitas asistencia adicional.

Última actualización el