Vincular Cuenta

Visión General

Este endpoint permite vincular una cuenta bancaria para un cliente previamente registrado en la API de Passport. Una solicitud exitosa devuelve los detalles de la cuenta, incluyendo el número de cuenta, tipo, y saldos asociados.

Información

El proceso de apertura de cuenta con el banco sponsor actualmente es manual, y Passport lo facilita con el apoyo de nuestro equipo de Cumplimiento. Este endpoint se utiliza después de dicho proceso para vincular el objeto.

Detalles del Endpoint

Parámetro	Descripción
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/accounts/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	Requerido	Descripción
customer_id	String		Sí	Identificador único del cliente para quien se está vinculando la cuenta.
account_type	String	ENUM: `ORDINARY`	Sí	Tipo de cuenta: `ORDINARY` (ordinaria).
account_number	string	1-35	Sí	Número de cuenta asignado por el Banco Sponsor.

Ejemplo de Solicitud

curl --location 'https://api.paas.sandbox.co.passportfintech.com/v1/accounts/link' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data '{ "customer_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc", "account_type": "ORDINARY", "account_number": "88827643001" }'

Nota

Asegúrate de que el customer_id proporcionado sea válido y esté vinculado a un cliente creado previamente.

Cuerpo de la Respuesta

Código HTTP: 200 OK
Devuelve la cuenta vinculada y sus metadatos, incluidos los saldos.

Ejemplo de Respuesta

{ "pending_balance": { "value": "0", "currency": "COP" }, "customer_id": "db7e89e7-59d8-4ab1-b675-a2ae52c3339e", "account_type": "ORDINARY", "updated_at": "2025-10-09T10:40:29.966Z", "account_number": "88827643001", "created_at": "2025-10-09T10:40:29.966Z", "status": "ACTIVE", "available_balance": { "value": "0", "currency": "COP" }, "id": "6c23f053-0e1a-46b4-b902-97ba47e351bc" }

Nota

Los campos pending_balance y available_balance representan los saldos de la cuenta, en pesos colombianos (COP).
El id que se genera en la respuesta es el account_id que se encuentra en otros puntos finales.

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 vincular una cuenta.
500 Server Error	Error del servidor	Se produjo un error inesperado durante la creación de la cuenta.

Buenas Prácticas

Verifica que el entity_customer_id corresponda a un cliente registrado y activo.
Utiliza el id de la cuenta retornado para consultar detalles o iniciar transacciones futuras.

Última actualización el