Vincular Merchant

Visión General

Este endpoint vincula el recurso de Cliente en la plataforma PaaS al vincularlo con un Comercio (Merchant) existente que el Banco Patrocinador (Banco Sponsor) aprobó manualmente. Solo admite clientes de tipo BUSINESS (Comercio). Si la operación tiene éxito, devuelve el identificador único del cliente recién creado, sus datos de contacto, metadatos de identificación y un estado inicial ACTIVE (Activo) con marcas de tiempo. En versiones futuras, los flujos de incorporación digital reemplazarán el proceso manual de aprobación del Banco Patrocinador.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/customers/business/link
Método	POST
Encabezados	Content-Type: application/json, Authorization
Autenticación	Token de Acceso (Bearer Token)

Cuerpo de la Solicitud

Parámetro	Tipo	Restricciones	Obligatario	Descripción
type	String	ENUM: `BUSINESS`	Sí	Tipo de cliente (`BUSINESS`).
business_name	String	1 - 140	Sí	Nombre legal de la empresa.
email	String	1–35	Sí	Dirección de correo electrónico del cliente.
mobile_phone_number	String	Formato E.164, hasta 15 dígitos	Sí	Número de teléfono de contacto. Es compatible con los formatos: `340977997` `+573402977997`
identification_type	String	ENUM: `NIT`	Sí	Tipo de documento de identificación (`NIT`).
identification_number	String	9 dígitos	Sí	Número de identificación único del cliente, sin dígito verificador.
address	Objeto		Sí	Dirección registrada del merchant en Colombia.
line_1	String		Sí	Línea 1 de dirección.
line_2	String		No	Línea 2 de dirección.
line_3	String		No	Línea 3 de dirección.
city	String		Sí	Ciudad donde se encuentra el Merchant.
state	String		Sí	Departamento/estado donde se encuentra el Merchant.
post_code	String		Sí	Código postal vinculado a la dirección del Merchant.
country	String		Sí	Código de país, siempre `CO`.
merchant_category_code	String	4 dígitos	9 dígitos	MCC (código de categoría del comercio) que clasifica el giro del negocio.

Ejemplo de Solicitud

JSON
    
 
curl --location 'api.paas.sandbox.co.passportfintech.com/v1/customers/business/link' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "type": "BUSINESS",
    "business_name": "ENTITY_NAME",
    "email": "email@yourdomain.com",
    "mobile_phone_number": "MOBILE_PHONE_NUMBER",
    "identification_type": "NIT",
    "identification_number": "ENTITY_NIT_NUMBER",
    "address": {
        "line_1": "Line 1",
        "line_2": "Line 2",
        "line_3": "Line 3",
        "city": "Bogota",
        "state": "Bogota DC",
        "post_code": "14111",
        "country": "CO"
    },
    "merchant_category_code": "0412"
}'
Copy

Cuerpo de la Respuesta

Código HTTP: 200 OK
Devuelve el cliente recién creado y sus metadatos.

Ejemplo de Respuesta

JSON
    
 
{
    "id": "d868bd5f-c9b5-4f81-a180-e4033c14b93b",
    "status": "ACTIVE",
    "updated_at": "2025-10-04T00:49:58.588Z",
    "created_at": "2025-10-04T00:49:58.588Z"
    "type": "BUSINESS",
    "business_name": "Passport Software SaS",
    "mobile_phone_number": "3503501234",  
    "email": "sebastian@passportfintech.com",
    "identification_type": "NIT"
    "identification_number": "102238236",  
    "address": {
        "state": "Bogota DC",
        "line_1": "sdf",
        "line_2": "asdf",
        "city": "Bogota",
        "post_code": "49312",
        "country": "CO"
    },
    "merchant_category_code": "0412"
}
Copy

Errores Comunes y Manejo

Código HTTP	Significado	Descripción
400 Bad Request	Datos inválidos	Faltan campos requeridos o contienen valores incorrectos.
401 Unauthorized	Token inválido	El token de acceso ha expirado o es inválido.
403 Forbidden	Acceso denegado	La solicitud no está autorizada para validar la entidad.
500 Server Error	Error del servidor	Se produjo un error inesperado al procesar la validación.

Buenas Prácticas

Asegúrate de que el tipo y número de identificación coincidan con los datos proporcionados durante el registro inicial. Esto es fundamental para que el Banco Patrocinador (Sponsor Bank) pueda validar correctamente la información y evitar errores en etapas posteriores del flujo.

Última actualización el