Cobre Keys with Bre-B

The Cobre Key API provides services to create, manage, and retrieve Bre-B keys assigned 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	Alphanumeric	@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.

Open Input: Generates a Cobre Key using any alphanumeric value you want to insert.

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

Key Type	Length	Example
`name`	21	@CBARG452PEXTOCOLOMBI
`id`	17-18	@CBAQ1ER9001234567
`random`	10	@CBAQ1EXD8
`open_input`	21	@MYPERSONALIZEDKEY123

open_input: Only letters and numbers allowed, no spaces, min 5 characters and max 20 for the customizable part.
name: You can create name-type keys with your alias at the beginning to enhance your brand visibility in the generated keys. For example: @PEXTOCOLOMBICBARG452
Please contact your KAM to enable some of these features.

Cobre Key Types Supported by Flow

Payment Method	open_input	name	id	random
Direct link Key			x	x
Direct link QR				x
Checkout Key				x
Checkout QR				x
Static Key	x	x	x	x

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.

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.

Actions performed on a Cobre Key

🔑 Create

🔍 Retrieval

❌ Block or Reactivate

❌ Cancel

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

🔗 Create a Cobre Key

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 Types Supported by Flow#

Cobre Key lifecycle and previous actions#

Cobre Key Idempotency#

Actions performed on a Cobre Key#

How to Get Started#

Before using this API#

What to expect after using this API#

Allowed Combinations

Keys structure and personalization

Cobre Key types

Cobre Key Types Supported by Flow

Cobre Key lifecycle and previous actions

Cobre Key Idempotency

Actions performed on a Cobre Key

How to Get Started

Before using this API

What to expect after using this API