Creating Bre-B Keys

Overview

Bre-B is Colombia’s immediate payment system (Sistema de Pagos Inmediatos - SPI), enabling real-time transfers between individuals, businesses, government departments and financial entities. At the heart of this system lies Key Management, it revolves on the unique identifier, to simplify the payment flow.

Core Concepts

In Bre-B, a Key (or “alias”) serves as a simplified, human-readable identifier for a bank Account. Instead of sharing long account numbers, users register a key that can be used receive payments instantly (you don't need a key to send a payment).

Each key is mapped to a specific account and must be globally unique within the Bre-B ecosystem.

Note

The relationship type between an Account and Key is 1:M, which means an Account may have one or more Keys associated - irrespective of the different types of Keys that can be used.

Business Value

Bre-B key management provides a standardized, interoperable layer that benefits all participants in the financial ecosystem:

For Entities

Enhances the customer experience and adoption through easier onboarding and simplified transfers.
Increases operational efficiency with lower errors.

For Users

Enables real-time payments using simple identifiers.
Avoids errors related to entering long account numbers and personal information.
Makes payment experiences more intuitive, ideal for mobile-first scenarios.

For Regulators

Promotes financial inclusion and broader access to digital payments.
Provides centralized traceability of key ownership and transfers.
Aligns with regional interoperability goals across Latin America.

Benefits of Key-Based Transfers

Benefit	Description
Simplified UX	Customers initiate transfers with one of the supported Key Types, not an account number.
Speed & Reliability	Payments occur in real time, with instant confirmation.
Interoperability	Keys are usable across participating banks and entities.
Security & Privacy	Minimizes the exposure of sensitive financial data.
Multiple Keys per Account	A single account may have multiple identifiers.

Example of Use Cases

Peer-to-Peer (P2P) Transfers

A customer sends money to a friend using their email address or cellphone. No need to ask for or store account details.

Person-to-Merchant (P2M) Payments

A small merchant registers a key (tiendaelalcalde@correo.com) and receives instant customer payments directly into their business account.

Merchant-to-Merchant (M2M) Payments

A small merchant wishes to send money in real time to a supplier once the goods are delivered.

Merchant-to-Person (M2P) Payments

A marketplace wishes to send proceeds of sales back to an Individual who is earning an income by selling through the website or retail location.

Bre-B Key Lifecycle

Create a Key: Map a key_value to an account (account_id) with the Create Key endpoint.
Update a Key: Change the associated account (e.g., if the user switches financial entities).
Suspend a Key: Block key temporarily for security reasons.
**Activate a Key:**A blocked key can be reactivated.
Delete a Key: Unlink the key from the associated customer account.
Resolve a Key: Search the registry to resolve keys into accounts.

Create a Bre-B Key

For more information about the endpoint details, please refer to Create Key page.

Key Types and Key Value

The key_type field defines the format and purpose of the key used to identify a bank deposit account within the Bre-B system. These keys reduce friction, enabling fast, secure payments between customers (Individual and Business), across financial entities, without the need for traditional account information.

Key Type (Code)	Description	Example of Key Value
ID	Document Number	7922089
MOBILE	Mobile Phone Number	+573001234567
EMAIL	Email	user@example.com
ALPHA	Custom Alias	@clientalias123
BCODE	Entity Commercial Code	0012345678

Note

The combination of key_type and key_value must be unique within the Bre-B infrastructure. Our platform will ensure that this uniqueness is validated.

Request Example

Parameter	Description
account_id	ID of the account to link the key to.
key.key_type	Type of key. see 'Key Types and Key Value' section above for valid values.
key.key_value	Unique identifier for the key. Must match the format of the given type.

Note

The account_id relates to the ID generated in the Link Account endpoint. You may refer to the Product Guide Merchant Onboarding, to review the Onboarding process.

Request Body

curl --location --request POST 'https://api.paas-sandbox.co.passportfintech.com/keys' \ --header 'Content-Type: application/json' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \ --data-raw '{ "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "key": { "key_type": "EMAIL", "key_value": "jimmyjohns22000@passportfintech.com" } }'

Response Example

Parameter	Description
id	Unique ID of the key in the system.
key.key_value	The value registered for this key.
account_id	The account this key is linked to.
key.key_type	The type of key created (e.g., `E` for email).
status	The Key status.
created_at	Timestamp ISO-8601 in UTC. Indicates when the key has been created.
updated_at	Timestamp ISO-8601 in UTC. Indicates the last update in the key.

Response Body

{ "customer_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "account_id": "7472937f-cbe2-4e34-8b5e-6067e196325c", "id": "56188354-18be-412d-9e0b-64c8e0f54541", "key": { "key_value": "jimmyjohns22000@passportfintech.com", "key_type": "EMAIL" }, "status": "ACTIVE", "created_at": "2025-03-12T14:55:00.00000Z", "updated_at": "2025-03-12T14:55:00.00000Z" }

Support and Resources

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

Last updated on