Checkout

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。

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 执行的操作#

Checkout 幂等性#

如何开始#

使用此 API 前#

使用此 API 后的预期结果#