收银台

Checkout API 提供服务，用于创建和管理托管支付体验，使终端用户能够通过支持的支付方式（PSE、Bancolombia、Nequi 和 BreB）直接向 Cobre Balance 发送资金。

Checkout 会生成一个托管的 Checkout URL，将付款方重定向至由 Cobre 管理的界面，所有支付步骤均由 Cobre 端到端处理，包括支付方式选择、操作说明、确认及成功页面。

Checkout 常用于在您希望减少前端开发工作量、并依托标准化、安全支付体验的场景下完成收款。

所有面向用户的页面——包括支付方式选择、支付说明、确认及成功提示——均由 Cobre 完全托管和管理。集成方仅需负责将用户重定向至 Checkout URL，并通过 Webhooks 处理支付后逻辑。

支持的支付方式

Checkout API 支持以下用于哥伦比亚 PayIn 操作的支付方式：

支付方式	通道	交互类型
PSE	`pse`	托管 Checkout（支付链接）
Bancolombia	`bancolombia`	托管 Checkout（支付链接）
Nequi	`nequi`	托管 Checkout（推送通知）
BreB QR	`breb_qr`	托管 Checkout（二维码）
BreB Key	`breb_key`	托管 Checkout（Key）

对于 PSE 支付，交易对手方中定义的电子邮件地址用于在 PSE 流程中验证用户身份。对于 Nequi 支付，交易对手方中定义的手机号码用于发送推送通知。

您可以为付款方设置账单描述符（与支付关联的说明），使其显示在收据中。请通过 Checkouts API 中的 checkout_item 字段进行设置。该功能暂不支持 Bre-B。

Bre-B 收款转账限额

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

Checkout 自定义

Cobre 的 Checkout 解决方案让您能够完全掌控向客户呈现支付链接的方式。通过灵活的参数组合，您可以打造适合各类使用场景的 Checkout 体验，从简单的一次性购买到周期性付款均可支持。可配置选项如下：

可自定义体验	说明	字段
选择 Checkout 名称	指定一个清晰、描述性的标题（例如 "我的公司"），以便客户立即了解所支付的内容。	`checkout_header`
开放或固定的商品描述	决定是否预设商品条目描述，或允许付款方填写自定义备注。（例如，"月度会员" 或 "捐赠给 XYZ"）	`checkout_item`
开放或固定金额	决定金额是固定的还是由付款方自行指定。例如，为商品设置固定价格，或允许自由填写金额。	`amount`
可复用链接	确定您的 Checkout 链接是一次性使用还是可重复使用（固定次数或不限次数）。	`money_movement_intent_limit`
设置到期日期	通过设置到期日期来控制 Checkout 链接的有效期。到期后，链接将失效。	`valid_until`
选择支付通道	选择要在 Checkout 中提供的支付方式（例如 Nequi、PSE、Bancolombia、BreB）。	`checkout_rail`

对于无到期日期的开放链接和/或无使用次数限制的开放链接和/或开放金额和/或开放条目值，请使用 -1

通过灵活组合上述选项，您可以打造一个灵活、品牌化且用户友好的 Checkout 体验，完美契合您的业务模式。

您还可以在 Checkout 中自定义以下内部字段（这些字段不会显示在 Checkout 页面上）：

可自定义条目	说明	字段
外部 ID	传递至资金流动的外部参考或追踪 ID。	external_id
收款方说明	显示在您的 Cobre Balance 中交易记录上的支付说明。	description_to_payee
跳转 URL	支付链接完成支付后，客户被重定向至的 URL。	redirect_url

允许的 Checkout 组合

地区	来源类型	目标类型	通道
COL	`r2p`	`cobre_balance`	`PSE`、`Bancolombia`、`Nequi`、`BreB`
COL	`r2p_breb`	`cobre_balance`	`BreB`

Checkout 生命周期

托管 Checkout 遵循简单的生命周期：

创建 r2p 类型的交易对手方（可选）。
在使用 Checkout 时，创建包含付款方信息的交易对手方是可选操作。
如果事先未创建交易对手方，Checkout 将在托管流程中收集所有必要的付款方信息，并自动创建对应的 r2p 交易对手方。

创建 Checkout
通过指定以下参数来创建 Checkout：

将上一步获得的 counterparty_id 作为 source_id（可选）

将您希望接收资金的 account_id 作为 destination_id

在 checkout_rails 中定义您希望为付款方提供的支付方式

在 checkout_header 和 checkout_item 中提供自定义详情

amount 以货币最小单位表示（例如，100.00 MXN 应发送为 10000）

将 Checkout 链接的到期日期设置为 valid_until

redirect_url 为付款方在 Cobre 显示确认页面后将被重定向至的地址

money_movement_intent_limit 定义同一 Checkout 链接可创建的资金流动次数

获取 Checkout URL
Checkout 创建完成后，Cobre 将返回一个代表托管支付体验的 checkout_url。

将用户重定向至 Checkout
将付款方重定向至 checkout_url 以完成支付。

用户完成支付
付款方在 Cobre 托管的 Checkout 中选择支付方式并完成交易。支付发起后，Checkout 将创建一条资金流动记录，用于追踪支付状态及后续状态变更。

接收状态更新
资金流动状态变更通过 Webhooks 进行通知。

资金到账
支付成功后，资金将记入关联的 Cobre Balance。

Checkout 生成的资金流动记录将在 batch_id 字段中包含 checkout_id，便于您将支付与发起该交易的 Checkout 进行关联和对账。

对 Checkout 执行的操作

🔑 Create

🔍 Retrieval

❌ Deactivate

说明： 创建 Checkout。
操作后预期结果： Checkout 在 Cobre 中创建成功。
📘 了解更多：

🔗 创建 Checkout

Checkout 幂等性

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

如何开始

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

使用此 API 前

You need a Cobre Balance in Colombia

要能够接收资金，您必须在哥伦比亚拥有一个 Cobre Balance 账户。

Create the Counterparty (Optional)

在创建资金流动之前，您必须先创建包含付款方信息的交易对手方。

Define the Checkout configuration

确定将提供哪些支付方式，以及金额、有效期和向付款方显示的参考信息。

Implement Webhooks to track payment status

为及时了解收款交易的状态，我们强烈建议您实现 Webhooks。Webhooks 会在支付发起、处理中、完成或失败时通知您的系统。同时请订阅所需事件，以接收交易入账通知。

更多详情请参阅通知与订阅。

使用此 API 后的预期结果

Redirect the user to Checkout

将付款方重定向至 Checkout 创建时返回的 checkout_url。

End user completes the payment

付款方通过托管的 Checkout 界面完成支付。

Receive funds in your Cobre Balance

支付成功后，资金将记入您的 Cobre Balance，并更新对应的资金流动记录。

收银台

支持的支付方式#

Checkout 自定义#

允许的 Checkout 组合#

Checkout 生命周期#

对 Checkout 执行的操作#

Checkout 幂等性#

如何开始#

使用此 API 前#

使用此 API 后的预期结果#

支持的支付方式

Checkout 自定义

允许的 Checkout 组合

Checkout 生命周期

对 Checkout 执行的操作

Checkout 幂等性

如何开始

使用此 API 前

使用此 API 后的预期结果