Link a Merchant

Overview

This endpoint provisions a new Customer resource on the Passport PaaS platform by linking it to an existing Merchant that was manually onboarded and approved by the Sponsor Bank. It supports BUSINESS customer types. Upon success, it returns the newly created customer’s unique identifier, contact details, identification metadata, In future iterations, full digital onboarding workflows will replace the manual Sponsor Bank approval process.

Our Compliance team helps you create the business profile and account(s) with the Sponsor Bank.

Endpoint Details

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

Request Body

Parameter	Type	Constraints	Required	Description
type	String	ENUM: `BUSINESS`	Yes	The customer type.
business_name	String	1-140	Yes	The business name if the customer is a company.
email	String	1-35	Yes	The email address associated with the customer.
mobile_phone_number	String	E.164 format, max 15 digits	Yes	The contact phone number for the customer. The following formats are accepted: `340977997` `+573402977997`
identification_type	String	ENUM: `NIT`	Yes	The type of identification
identification_number	String	9	Yes	The customer unique identification number, without check digit.
address	Object		Yes	Registered address of the Business in Colombia.
line_1	String		Yes	Address Information Line 1.
line_2	String		No	Address Information Line 2.
line_3	String		No	Address Information Line 3.
city	String		Yes	The city in which the Merchant is situated.
state	String		Yes	The state in which the Merchant is situated.
post_code	String		Yes	The postal code linked to the Merchant's address details.
country	String		Yes	The country code is consistently represented as `CO`.
merchant_category_code	String	4	Yes	The specific merchant category code designation for the Merchant, commonly referred to as the MCC, is an essential identifier that categorizes the type of business activities performed by the merchant.

Example Request

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

Response Body

HTTP Status Code: 200 OK
Returns the newly created key and its associated metadata.

Example of Response

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

Common Errors 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 validate the entity.
500 Internal Server Error	Server Error	An unexpected error occurred while validating the entity.

Best Practices

Ensure the identification type and number match the initial sign up data before validation as this is how the Sponsor Bank matches the information on their systems and will cause issues if it does not.

Last updated on