Merchant Onboarding

Overview

This guide helps you understand how to connect the Platform to the profile at the Sponsor Bank and link financial Accounts using the Passport PaaS platform. This simple and effective process lets your entity quickly create your Customer, link Account(s), and get set up for easy and secure payments. By completing these steps, you will be ready for Payments and Key creation through the national Bre-B infrastructure.

If you manage payments under your business (especially if you hold a Payments License), ensure the customer details entered here match your manually registered business information. Think of this step as digitally registering your own business, setting you up to manage your accounts at the Sponsor Bank.

Business Value

Accelerate customer registration, enabling quicker access to financial services.
Reduce manual paperwork and errors, improving operational efficiency.
Create a seamless customer experience by rapidly onboarding users digitally.

Link Your Profile

During the onboarding process, the Merchant will have been manually created at the Sponsor Bank - this enhanced due diligence process ensures that the business model and money flows are satisfactory for accepting via the licensed Financial Entity.

it is a necessary step in order to prepare for offering financial products via the Sponsor Bank model - as payments processing is considered a High Risk activity for compliance teams. In the Passport Platform, the profile is saved as a Customer - linked to the Customer profile at the Sponsor Bank.

Link a Merchant: Request Example

Note

For more details of the endpoint, please refer to the document: Link a Merchant

Parameter	Description
business_name	Enter the registered legal name of your or your customer’s business.
mobile_phone_number	Provide the mobile phone number in Colombia format (including country code +57).
identification_type	Specify the type of identification document (NIT).
identification_number	Input the official NIT number from the business.
address	An object capturing the registered address of the business.
merchant_category_code	A four digit identifier that defines the business model of the business - allocated by the licensing body.

Link a Merchant: Request Body

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

Link a Merchant: Response Example

Parameter	Description
id	A unique identifier assigned to this business customer. You'll use it to link an account in the next step.
type	Confirms the customer is registered as a `BUSINESS`.
business_name	The official name of the business.
email	Business email used for communication and verification.
mobile_phone_number	Stored contact number of the business.
identification_type	The type of ID provided (NIT).
identification_number	The NIT number of the business.
address	Contains the address object of the business's registered address.Contains the address object of the business's registered address.
created_at	A timestamp for when the Customer resource was created (linked) on the Passport platform.
updated_at	A timestamp for when the Customer resource was updated on the Passport platform.

Link a Merchant: Response Body

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

Now that the profile has been successfully linked to the Customer at the Sponsor Bank, you're ready to link the bank Account (or Accounts, plural) that was opened during the manual onboarding process. The Customer ID returned in the previous step is essential for this and will be used as the customer_id for future requests.

Customers cannot transact until they have an Account. It is essential for accessing the platform's financial services, such as real-time payments.

Link a Bank Account

With the customer_id generated and the processes of linking a merchant has been completed, now the link step between the objects can be done. Business customers can only have accounts with the following type:

ORDINARY: Best for Merchants, with no set transaction limits or limitations. These Accounts are manually configured to be free from any local transactions taxes.

Note

A Merchant may have multiple bank Accounts, in a 1:M relationship. There is no limit on the number of Accounts that can be opened, but to do so requires a manual process similar to the original approval flow (albeit accelerated).

Business Value

Programmable Bank Account that can be used to facilitate various transactions.
Enable immediate use of financial services through instantly available Accounts.

Request Example

Use the customer_id obtained in the Link a Merchant call.

Parameter	Description
customer_id	Unique identifier from the Link a Merchant response body.
type	The Account Type: `ORDINARY`
number	The Account Number that was provided during the manual onboarding phase

Request Body

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

Response Example

Parameter	Description
customer_id	The ID of the Customer the Account is linked to.
available_balance	The object that contains the amount and currency information of the available balance of the Account.
available_balance.currency	The currency type of the Account (COP - Colombian Peso).
available_balance.value	The monetary value of money currently available in the Account.
id	The unique identifier of the newly linked Account. You'll use this for transactions and key creation.
number	The internal number assigned to the Account, this acts as the Account identifier within the Sponsor Bank.
type	Indicates the account type: `ORDINARY` (no transaction limits).
pending_balance	The object that contains the pending amounts and currency information of the transactions that were not liquidated.
pending_balance.currency	The currency type of the account (COP - Colombian Peso).
pending_balance.value	The monetary value of money in pending status for the Account.
created_at	A timestamp for when the Account was created on the Passport Platform.
updated_at	A timestamp for when the Account was last updated on the Passport Platform.

Note

The notation object.parameter relates to the object and parameter relationship, within the request or response, in the example given. pending_balance.currency, refers to the currency parameter within the pending_balance object.

Next Steps

After setting up your Account, proceed to Creating Bre-B Keys to interact with the Bre-B infrastructure and this enables making instant secure payments easy.

Support and Resources

Visit the Postman Collection for practical examples.
Contact your Passport representative or technical support for further guidance.

Last updated on