- 固定金额：订单创建时即指定具体的应付金额
- 有效期限：付款方需要在指定时间内完成支付
- 异常处理：支持多种异常情况的处理，包括：
- 取消尚未支付的订单
- 对已支付订单发起退款
- 处理多付、少付、晚付等支付异常
创建订单
您可以通过两种方式创建订单：- 调用 Create pay-in order 直接创建一个支付订单。调用成功后，您将得到应付金额、付款地址等信息；
- 调用 Create order link 创建一个订单支付链接。该链接会跳转到由 Cobo 提供的支付页面，付款方可在该页面创建订单并完成支付，无需您自行开发前端交互流程。您还可以通过 iFrame 方式将该支付页面嵌入到您的网站或应用中。
前提条件
您已完成前置准备中提到的所有步骤。操作步骤
- 使用 Payments API 创建支付订单
- 使用 Payments API 创建支付链接
您可以调用 Create pay-in order 来创建一个支付订单。下图展示了付款方、商户与 Cobo 之间的完整交互流程：创建订单时，您需要在以下两种方式中选择一种适合业务的金额参数组合：下表展示了在不同设置下，系统如何计算应付金额：
- **方式一：**原订单商品以法币定价，您需要收取数字货币金额
- 填写：
pricing_currency、pricing_amount、payable_currency； - 不填：
payable_amount
- 填写：
- **方式二：**原订单商品以数币定价，您直接按原币种收取数字货币金额
- 填写：
payable_currency、payable_amount； - 不填：
pricing_currency、pricing_amount
- 填写：
- 定价币种（
pricing_currency）：商品法币计价单位，目前支持设置法币币种请参考 支持的币种与公链。该字段为可选字段，如果您商品定价为数字货币则无需填写。 - 定价金额（
pricing_amount）：商品法币计价金额，以pricing_currency指定的法币为单位。该字段为可选字段，如果您商品定价为数字货币则无需填写。 - 应付币种（
payable_currency）： 付款方需要支付的数字货币币种，目前支持数字货币币种请参考 支持的币种与公链 - 应付金额（
payable_amount）：付款方需要支付的数字货币金额，以payable_currency指定的加密货币为单位。该字段为可选字段：- 如果您指定了
payable_amount，则系统直接使用该值作为付款方需支付的金额。 - 如果您未指定
payable_amount，系统将使用实时汇率计算：应付金额 =（订单金额 + 开发者费用）/ 汇率。汇率以创建订单时调用 Get exchange rate 操作返回的汇率为准。
- 如果您指定了
- 开发者费用（
fee_amount）：如果您是服务多个下游商户的平台机构，需要在您和下游商户之间分配收入，可以通过设置该费用来实现。此费用以payable_currency指定的加密货币为单位。实际分成的开发者费用=开发者费用/应付金额*实际收款金额，更多信息请参考账户与资金分配。
如果您是商户（直接服务于付款方），通常无需设置开发者费用。
| 场景 1 | 场景 2 | |
|---|---|---|
| 场景描述 | - 订单金额以法币计价 - 无需设置开发者费用 - 系统计算应付金额 | - 订单金额以加密货币计价 - 设置开发者费用 - 自定义应付金额 |
pricing_currency | "USD" | 不设置 |
pricing_amount | "100" | 不设置 |
payable_currency | "ETH_USDT" | "ETH_USDT" |
payable_amount | 不设置 | "104.08" |
fee_amount | "0" 或不设置 | "2" |
| 实时汇率 | 0.99 | 不适用（使用自定义应付金额） |
| 应付计算过程 | (100 + 0) / 0.99 | 直接使用指定的 payable_amount |
| 最终应付金额 | "101.01" | "104.08" |
| 开发者费用计算过程 | 0 | 2/104.08*104.08 |
| 最终开发者费用 | "0" | "2" |
查询订单状态
您可以订阅以下 Webhook 事件，以获取订单状态的实时更新通知。请参考 Webhook reference 了解每个事件的触发时间和返回的数据结构。payment.status.updatedpayment.transaction.latepayment.transaction.completed
- Payments App
- Payments API
异常情况
在订单模式下，您可能要处理以下几种异常情况。撤销支付订单
当一笔支付订单在Pending 状态下，即尚未检测到入账交易时，您可以调用 Update pay-in order 撤销该订单。撤销后，订单状态将变更为 Expired。
多付、少付和晚付
在支付过程中可能出现以下三种异常情况：| 异常情况 | 描述 | 影响 |
|---|---|---|
| 多付 | 在订单有效期内，付款方实付金额超过应付金额 | 订单最终状态为 Completed。 |
| 少付 | 在订单有效期内，付款方实付金额少于应付金额 | 订单状态为 Underpaid（终态）。 |
| 晚付 | 付款方在订单过期后进行首次或再次付款 | 不会改变订单状态。每次晚付都会触发一次 payment.transaction.late Webhook 事件。 |
处理退款申请
您可以通过 Payments App 或 Payments API 发起一笔退款订单，将资金退还给付款方。下图展示了退款环节中，付款方、商户以及 Cobo 之间的交互流程。创建退款订单
- Payments App
- Payments API
- 登录 Cobo Portal 开发环境或生产环境。
- 在左侧导航栏中点击 Apps，然后点击 Payments 卡片，启动 App。
- 在 App 的左侧导航栏中点击收款 > 订单。
- 选择目标订单，然后点击右侧的查看详情按钮。
- 在订单详情页面，点击退款按钮。
- 在弹出的表单中：
- 选择退款金额的来源，可以选择商户余额或开发者余额。
- 填入退款金额。该金额不得高于对应的商户余额或开发者余额。
- （可选）填入开发者费用金额。该手续费会从退款金额中扣除，归入开发者余额。有关开发者费用的详细说明，请参考账户与资金分配。
- 输入收款地址。您可以点击使用原始支付地址，系统将自动填入该笔订单的原始支付地址。如果您想退款到其他地址，也可以手动输入目标地址。
- 点击预览确认所有信息无误后，点击提交创建退款订单。
查询退款订单状态
您可以订阅payment.refund.status.updated 事件，获取退款订单状态的实时更新。请参考 Webhook reference 了解每个事件的详细触发条件和返回的数据结构。
您也可以通过 Payments App 或 Payments API 主动查询退款订单状态。
- Payments App
- Payments API
合规筛查不通过
当某笔交易收到payment.transaction.failed 事件时，这表明该笔交易未能通过 Cobo KYT 或 Screening App 的合规筛查。这种情况下，您需要按照以下步骤进行处理：
- 若该笔交易后续通过人工审核：
- 如果订单未过期：该笔资金将计入订单实收金额，订单状态将根据实收金额相应更新
- 如果订单已过期：系统将触发
payment.transaction.late事件，该笔资金将全部计入开发者余额
- 若该笔交易最终未通过人工审核：
- 资金将被冻结，不会被计入订单实收金额
- 订单状态将保持不变
- 付款方需要在订单有效期内重新充入足额资金并通过合规筛查，订单才能转为
Completed状态
- Cobo KYT：请通过 [email protected] 联系 Cobo 支持团队处理
- Screening App：您可以在应用内自行评估和处理
最小入账金额限制
为优化您的账户成本，避免因粉尘金额产生的入账手续费高于交易金额，系统设定了最小入账阈值。当单笔交易金额低于 0.05 USDT（或等值币种）时，系统将不自动进行入账处理。注：若您需要对此类低于阈值的累积资金进行手动处理，请联系 Cobo 客服或技术支持，我们将协助您从归集地址提取。