Create Key

Overview

This endpoint creates a new Bre-B Key by submitting the request to the Visionamos - Passport Bre-B Node. It registers a linkage between a Customer, its Account, and a specific payment key (e.g., email, phone, alphanumeric) for use in QR code generation and payment routing.

Endpoint Details

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

Information

A Key can only be created after the Customer has been onboarded (refer to Link a Merchant) and has an Account with the Sponsor Bank.

Request Body

Parameter	Type	Constraints	Required	Description
account_id	string	UUID	Yes	Unique identifier of the account to associate the key with.
key_type	string	ENUM: `ID`, `PHONE`, `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 and/or numbers, and start with an @. `BCODE`: Commercial Entity Number - 10 numeric characters, starting with 00.
key_value	string	Varies by `key_type`	Yes	The actual key to be registered.
display_name	string		No	During the key resolution process, the display name of the payee will be shown for clarity and reference. This display name serves as an important identifier, helping users to easily recognize the payee involved in the transaction.

Relationship of Bre-B Key and Accounts

The relationship between Bre-B Keys and Accounts is 1:M, this means an account may have associated multiple Bre-B keys.

Example Request

curl --location --request POST 'https://api.paas.sandbox.co.passportfintech.com/v1/keys' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --data '{ "account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc", "key":{ "key_type": "BCODE", "key_value": "0016027228" }, "display_name": "Pepito Silva" }'

Response Body

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

Example of Response

{ "status": "ACTIVE", "key": { "key_type": "BCODE", "key_value": "0016027228" }, "display_name": "Pepito Silva", "account_id": "6c23f053-0e1a-46b4-b902-97ba47e351bc", "created_at": "2025-10-09T10:42:39.710Z", "updated_at": "2025-10-09T10:42:39.710Z", "id": "3184cbfd-73bd-4910-bd03-f8461e724247" }

Important

The id returned is the key_id to use in other endpoints.

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

Best Practices

Use appropriate key types: Make sure the key type matches the format of the value (e.g., E for emails).
Avoid duplicate keys across accounts: Keys must be unique per user in the system (an account may have multiple keys associated with).

Last updated on