Cobre Keys with Bre-B

The Cobre Key API provides services to create, manage, and retrieve Bre-B keys assined by Cobre.

A Cobre Key is a unique identifier that allows end users to send funds to a recipient without requiring traditional bank account details, enabling seamless money collection through immediate payment rails.

Cobre Keys act as reusable destination identifiers and are commonly used to collect funds instantly, simplifying the payment experience for both individuals and businesses interacting with the Cobre platform.

Cobre Keys do not have an expiration date, so they can be used as many times as needed to receive payins.

Allowed Combinations

When creating a Cobre Key, the supported account types and geographies must be taken into account, as detailed below:

Account Type	Geo	Key Type	Key Value Example
Cobre Balance	COL	Alphannumeric	@CBARG452PEXTOCOLOMBI

Keys structure and personalization

Cobre Keys are composed by concatenating three elements:

Financial Institution Prefix	Random String	Configurable String
@CB — Identifies keys created by Cobre	Ensures global uniqueness	Allows the client to personalize the key based on name, ID, or a random value

Cobre Key types

Cobre supports different types of Cobre Keys, each designed for specific identification and user experience needs.

Name: Generates a Cobre Key based on the first 12 characters (without spaces) of the client’s alias.

ID: Generates a Cobre Key based on the first 9–10 digits of the client’s identification number.

Random: Generates a Cobre Key using random alphanumeric characters.

Key Type	Lenght	Example
name	21	@CBARG452PEXTOCOLOMBI
ID	17-18	@CBAQ1ER9001234567
random	10	@CBAQ1EXD8

The alias used for name-based keys can be configured from the Cobre Portal or through a request via our support channels.

Cobre Key lifecycle and previous actions

The Cobre Key object includes information about the previous_action performed by the client. This allows you to:

Identify whether the client attempted to create, block, reactivate, or delete a key

Compare the requested action with the current status of the Cobre Key to determine whether the operation was successfully processed

Cobre Key administration actions are integrated into the key lifecycle, as follows:

status	description
processing	An intermediate state indicating that the submitted Cobre key creation is still being processed
registered	The Cobre key was successfully created and registered, and is now available for use
unregistered	The Cobre key was cancelled at the user’s request via our key cancellation API. Once cancelled, a key cannot be reactivated
disabled	The Cobre key was disabled either by the user or by Cobre. A key in the disabled state can be reactivated
failed	The attempted action on the key was unsuccessful and it is necessary to submit the creation request again

Keep in mind that Cobre key creation is asynchronous, so creation requests will always return in processing status. The final status of the key must be checked later through the obtain all keys endpoint or obtain one specific endpoint, and therefore the fields key_value and source_id will only be returned once the key transitions to the registered status.

Actions performed on a Cobre Key

🔑 Create

🔍 Retrieval

❌ Block or Reactivate

❌ Delete

Description: Cobre Key Creation.
What to expect after the action: Cobre Key is created in Cobre.
📘 Learn more:

🔗 Create a Cobre Key

Cobre Key Idempotency

Cobre Key creation does not currently support idempotency.

At this time, only one Cobre Key can be created per Cobre Balance account.

How to Get Started

Before you begin, we recommend reviewing the following considerations.

Before using this API

You need a Cobre Balance in Colombia

To be able to create a Cobre Key, you must have a Cobre Balance account in Colombia.

Define the Cobre Key type

Before creating a Cobre Key, carefully consider which key type best fits your use case. The selected type determines how the key value is generated, managed, and reused across your payment flows..

Implement Webhooks to track Cobre Key status

To stay informed about changes in the lifecycle of a Cobre Key, we strongly recommend implementing Webhooks. Webhooks notify your system in real time when a Cobre Key is created, enabled, disabled, or deleted, allowing you to react promptly to each state change. Also subscribe to the required events to receive notifications about transaction credits.

See Notifications for more details.

What to expect after using this API

Start receiving transfers

Once the Cobre Key is created and available, you can expose it to your end users to start receiving transfers through the key and have the funds credited directly to your Cobre Balance. You will see a breb_credit type credit transaction in the Cobre Balance account linked to the key.

Block or Reactivate a Cobre Key

Once the Cobre Key is created and available, you can enable or disable it at any time, depending on your operational or business needs.

Delete a Cobre Key

Once the Cobre Key is created and available, you can delete it if you no longer intend to use it for operations. Once a Cobre Key is deleted, it cannot be used again.

Cobre Keys with Bre-B

Allowed Combinations#

Keys structure and personalization#

Cobre Key types#

Cobre Key lifecycle and previous actions#

Actions performed on a Cobre Key#

Cobre Key Idempotency#

How to Get Started#

Before using this API#

What to expect after using this API#