Link Account

Overview

This endpoint links an existing bank Account, manually opened and approved by the Sponsor Bank, to a Customer resource on the PaaS platform. While the account must already exist in the Sponsor Bank’s core system, this call registers a unique reference in the PaaS system to enable balance inquiries and transaction operations.

Note

The account opening process with the sponsor bank is currently manual, and Passport facilitates it with the help of our Compliance Team, this endpoint is used after this process to link the objects.

Endpoint Details

Definition	Description
Endpoint	https://api.paas.sandbox.co.passportfintech.com/v1/accounts/link
Method	POST
Headers	Content-Type: application/json, Authorization
Authentication	Access Token (Bearer Token)

Response Body

Parameter	Type	Constraints	Required	Description
customer_id	UUID		Yes	The unique identifier of the entity customer for whom the account is being linked.
account_type	String	ENUM: `ORDINARY`	Yes	The type of account.
account_number	string	1-35	Yes	The bank-assigned account number, as allocated by the Sponsor Bank.

Example Request

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" }'

Note

Ensure that the provided customer_id is valid before making the request.

Response Body

HTTP Status Code: 200 OK.
Returns the linked account and its metadata.

Example of Response

{ "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" }

Note

The response includes account balances (pending_balance and available_balance) in COP (Colombian Pesos).
The id from the endpoint is the account_id for use on other endpoints.

Common Error and Handling

HTTP Status Code	Meaning	Description
400 Bad Request	Invalid Data	Required fields are missing or contain incorrect values.
401 Unauthorized	Expired Token	The access token is invalid or has expired.
403 Forbidden	Access Denied	The request is not authorized to create an account.
500 Internal Server Error	Server Error	An unexpected error occurred while creating the account.

Best Practices

Ensure the customer_id is correct and associated with a valid customer.
Use the returned account id for further transactions or queries.

Last updated on