Cobre Keys 与 Bre-B 集成

Cobre Key API 提供创建、管理和检索由 Cobre 分配的 Bre-B Keys 的服务。

Cobre Key 是一种唯一标识符，允许终端用户无需提供传统银行账户信息即可向收款方转账，从而通过即时支付通道实现无缝收款。

Cobre Keys 作为可重复使用的收款标识符，常用于即时收款，简化了个人和企业在 Cobre 平台上的支付体验。

Cobre Keys 没有过期日期，因此可以无限次用于接收收款。

允许的组合

创建 Cobre Key 时，需考虑支持的账户类型和适用地区，详见下表：

账户类型	地区	Key 类型	Key 值示例
Cobre Balance	COL	字母数字	@CBARG452PEXTOCOLOMBI

Keys 结构与个性化

Cobre Keys 由以下三个元素拼接而成：

金融机构前缀	随机字符串	可配置字符串
@CB — 标识由 Cobre 创建的 Keys	确保全局唯一性	允许客户根据姓名、ID 或随机值对 Key 进行个性化设置

Cobre Key 类型

Cobre 支持多种类型的 Cobre Keys，每种类型针对特定的身份识别和用户体验需求而设计。

Name（姓名型）：根据客户别名的前 12 个字符（不含空格）生成 Cobre Key。

ID（证件型）：根据客户身份证号码的前 9–10 位数字生成 Cobre Key。

Random（随机型）：使用随机字母数字字符生成 Cobre Key。

Open Input（自定义输入型）：使用您希望输入的任意字母数字值生成 Cobre Key。

用于姓名型 Keys 的别名可通过 Cobre Portal 配置，或通过我们的支持渠道提交请求进行设置。

Key 类型	长度	示例
`name`	21	@CBARG452PEXTOCOLOMBI
`id`	17-18	@CBAQ1ER9001234567
`random`	10	@CBAQ1EXD8
`open_input`	21	@MYPERSONALIZEDKEY123

open_input：仅允许字母和数字，不允许空格，可自定义部分最少 5 个字符，最多 20 个字符。
name：您可以在生成的 Keys 中将别名置于开头，以提升品牌曝光度。例如：@PEXTOCOLOMBICBARG452
请联系您的 KAM 以启用上述部分功能。

各流程支持的 Cobre Key 类型

支付方式	open_input	name	id	random
Direct link Key		x	x	x
Direct link QR				x
Checkout Key				x
Checkout QR				x
Static Key	x	x	x	x

Cobre Key 生命周期与历史操作

Cobre Key 对象包含客户所执行的 previous_action（上一操作）的相关信息。这使您能够：

识别客户是否尝试过创建、冻结、重新激活或删除某个 Key

将请求的操作与 Cobre Key 的当前状态进行对比，以判断该操作是否已成功处理

Cobre Key 的管理操作已整合到 Key 的生命周期中，如下所示：

状态	描述
`processing`	中间状态，表示已提交的 Cobre Key 创建请求仍在处理中
`registered`	Cobre Key 已成功创建并注册，现可正常使用
`unregistered`	Cobre Key 已应用户请求通过我们的 Key 注销 API 取消。一旦取消，Key 将无法重新激活
`disabled`	Cobre Key 已被用户或 Cobre 禁用。处于禁用状态的 Key 可以重新激活
`failed`	对该 Key 执行的操作未成功，需要重新提交创建请求

请注意，Cobre Key 的创建为异步操作，因此创建请求始终以 processing（处理中）状态返回。Key 的最终状态需稍后通过"获取所有 Keys"接口端点或"获取指定 Key"接口端点进行查询，因此字段 key_value 和 source_id 仅在 Key 状态流转至 registered（已注册）后才会返回。

Cobre Key 幂等性

Cobre Key 创建目前不支持幂等性。

目前，每个 Cobre Balance 账户只能创建一个 Cobre Key。

对 Cobre Key 执行的操作

🔑 Create

🔍 Retrieval

❌ Block or Reactivate

❌ Cancel

描述： 创建 Cobre Key。
执行操作后的预期结果： Cobre Key 在 Cobre 中成功创建。
📘 了解更多：

🔗 创建 Cobre Key

如何开始

在开始之前，建议您先阅读以下注意事项。

使用本 API 前

You need a Cobre Balance in Colombia

要创建 Cobre Key，您必须在哥伦比亚拥有一个 Cobre Balance 账户。

Define the Cobre Key type

在创建 Cobre Key 之前，请仔细考虑哪种 Key 类型最适合您的使用场景。所选类型将决定 Key 值的生成方式、管理方式以及在您的支付流程中的复用方式。

Implement Webhooks to track Cobre Key status

为及时掌握 Cobre Key 生命周期的状态变化，我们强烈建议您接入 Webhooks。Webhooks 可在 Cobre Key 被创建、启用、禁用或删除时实时通知您的系统，使您能够及时响应每次状态变更。同时，请订阅所需事件以接收有关交易入账的通知。

详见通知。

使用本 API 后的预期结果

Start receiving transfers

Cobre Key 创建并可用后，您可以将其公开给终端用户，以便通过该 Key 开始接收转账，资金将直接入账至与该 Key 关联的 Cobre Balance 账户。您将在关联的 Cobre Balance 账户中看到类型为 breb_credit 的入账交易记录。

Block or Reactivate a Cobre Key

Cobre Key 创建并可用后，您可根据运营或业务需要随时启用或禁用该 Key。

Delete a Cobre Key

Cobre Key 创建并可用后，若您不再打算将其用于业务操作，可将其删除。Cobre Key 一旦删除，将无法再次使用。

Cobre Keys 与 Bre-B 集成

允许的组合#

Keys 结构与个性化#

Cobre Key 类型#

各流程支持的 Cobre Key 类型#

Cobre Key 生命周期与历史操作#

Cobre Key 幂等性#

对 Cobre Key 执行的操作#

如何开始#

使用本 API 前#

使用本 API 后的预期结果#

允许的组合

Keys 结构与个性化

Cobre Key 类型

各流程支持的 Cobre Key 类型

Cobre Key 生命周期与历史操作

Cobre Key 幂等性

对 Cobre Key 执行的操作

如何开始

使用本 API 前

使用本 API 后的预期结果