Cobre Keys 与 Bre-B 集成

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

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

Cobre Keys 作为可复用的目标标识符，通常用于即时收款，为个人和企业在与 Cobre 平台交互时简化支付体验。

Cobre Keys 没有过期日期，因此可根据需要多次用于接收收款。

Bre-B 收款转账限额

Cobre Keys 与哥伦比亚所有 Bre-B keys 一样，可接收 Bre-B 网络允许的最大金额以内的转账。但付款方向 Cobre Key 发送的金额可能受其银行施加的更低限额约束。

允许的组合

创建 Cobre Key 时，需考虑所支持的账户类型和地区，详情如下：

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

Keys 结构与个性化

Cobre Key 类型

Cobre 支持多种 Cobre Key 类型，每种类型均针对特定的标识需求和用户体验场景而设计。

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：您可以将别名放在 Key 的开头以创建姓名类 Keys，从而在生成的 Keys 中提升品牌辨识度。例如：@PEXTOCOLOMBICBARG452
请联系您的客户经理以启用上述部分功能。

可以将 Bre-B 的名称个性化，以作为交易目的地的客户名称，并预先确定 Pexto 或企业名称。该功能与 Cobre 的所有功能兼容。

各流程支持的 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。您将在与该 Key 绑定的 Cobre Balance 账户中看到一笔 breb_credit 类型的入账交易。

Block or Reactivate a Cobre Key

一旦 Cobre 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 后的预期结果