Create Recipient

Overview

This endpoint creates a new Recipient for a specific Customer by registering a payment key in the Visionamos - Passport Bre-B Node. Recipients represent destination accounts or keys (such as email, phone, alphanumeric, national ID, or business code) used when initiating payments.

Endpoint Details

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

Request Body

Parameter	Type	Constraints	Required	Description
customer_id	String	UUID	Yes	The unique identifier of the entity customer creating the recipient.
key_type	String	ENUM: `ID`, `MOBILE`, `EMAIL`, `ALPHA`, `BCODE`	Yes	Type of key. Accepted values: `ID` : Document Number - up to 18 alphanumeric characters, no hyphens (-), spaces, or special characters allowed. `PHONE`: Mobile Phone Number - 10 digits, must start with 3. `EMAIL`: Email - up to 92 characters, must have an @ before the domain, with a maximum of 30 characters before the @ and 61 after. `ALPHA`: Alphanumeric Number - between 6 and 21 characters, must include letters, numbers, and start with an @. `BCODE`: Commercial Entity Number - 10 numeric characters, starting with 00.
key_value	String	Varies by `key_type`	Yes	The value of the recipient’s key.
alias	String		No	A friendly name that can be used and presented along side the Bre-B Key

Example Request

JSON
    
 
curl --location 'https://api.paas.sandbox.co.passportfintech.com/v1/recipients/breb' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c",
    "key": {  
        "key_type": "PHONE",
        "key_value": "3975999158"  
    },
    "alias": "Pepito SAS5"
}'
Copy

Ensure that the provided entity_customer_id and recipient information are valid before making the request.

Response Body

HTTP Status Code: 200 OK.
The response will contain the recipient details along with its unique identifier.

Example of Response

JSON
    
 
{
    "customer_id": "31eb66c3-f309-48ce-8b12-086f9e76b84c",
    "key": {
        "key_type": "PHONE",
        "key_value": "3975999158"
    },
    "type": "BREB",
    "updated_at": "2025-10-10T07:43:41.267Z",
    "created_at": "2025-10-10T07:43:41.267Z",
    "alias": "Pepito SAS5",
    "id": "daa209f9-fbdf-4f2b-aadc-db42fe16358c"
}
Copy

The response confirms the recipient has been successfully created and returns a unique recipient id for future transactions.

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 create a recipient.
500 Internal Server Error	Server Error	An unexpected error occurred while creating the recipient.

Best Practices

Ensure the customer_id is correct and associated with a valid entity customer.
Validate the recipient’s key_type and key_value before making the request.

Last updated on