> For the complete documentation index, see [llms.txt](https://docs.topay.mobi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.topay.mobi/cn/integration/crypto-payments/acquiring.md).

# 数字货币收单

为数字货币支付流程选择钱包模式或收银台模式。

Topay 提供两种数字货币收款方式。需要将充值地址与客户关联时，选择**钱包模式**；需要在客户付款前创建具有预期金额的支付订单时，选择**收银台模式**。

两种模式均通过统一的 [Webhook 通知](/cn/integration/webhook.md)报告交易更新。主要区别在于您的系统如何将付款与客户或订单关联。

## 选择接入模式 <a href="#choose-an-integration-mode" id="choose-an-integration-mode"></a>

|          | 钱包模式          | 收银台模式            |
| -------- | ------------- | ---------------- |
| 付款关联对象   | 客户和资产         | 单笔支付订单           |
| 地址用途     | 用于持续充值的客户充值地址 | 与订单关联的收款地址或托管收银台 |
| 地址有效期    | 可重复用于后续充值     | 默认有效期为一天         |
| 本地订单创建时机 | 收到通知时记录入账交易   | 请求收银台前创建本地订单     |
| 金额处理     | 按确认收到的金额入账    | 核对实际付款金额与预期订单金额  |
| 典型使用场景   | 钱包充值和客户余额     | 电商收银台和一次性付款      |

## 钱包模式 <a href="#wallet-mode" id="wallet-mode"></a>

使用钱包模式，为客户和指定资产获取充值地址。保存 `customer_ref_id`、资产与返回地址之间的关联关系。客户向该地址转账后，您的后端通过交易通知识别客户并为其入账。

<figure><img src="https://708501463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5CoqhFwqwkrLal2C588B%2Fuploads%2Fgit-blob-5ba964aa575472d8d02f0d914aed2bd6b0c4cf4f%2Facquiring-wallet-mode.png?alt=media" alt="钱包模式：客户专属充值地址"><figcaption><p>每位客户关联一个可重复使用的充值地址。</p></figcaption></figure>

### 接入流程 <a href="#integration-flow" id="integration-flow"></a>

1. 完成[身份认证](/cn/integration/authentication.md)接入，并实现 [Webhook 通知](/cn/integration/webhook.md)验签。
2. 使用 `currency` 和 `customer_ref_id` 调用[获取充值地址](/cn/reference/api-reference/crypto-payments/acquiring/wallet-mode.md#get-deposit-address)接口。
3. 保存并展示返回的地址，以及必需的 tag 或 memo。
4. 收到通知后，先验签并检查交易状态。根据客户标识和通知金额记录充值，确认成功后按您的余额入账规则处理。
5. 需要交易详情时，使用[查询订单](/cn/reference/api-reference/query-order.md)。

重复通知必须进行幂等处理：同一笔交易不能重复增加客户余额。

## 收银台模式 <a href="#checkout-mode" id="checkout-mode"></a>

当您的系统提前知道付款金额时，使用收银台模式。先创建本地订单，再携带 `request_id` 请求收银台。Topay 为订单分配临时收款地址，默认有效期为一天。请在地址到期前展示返回的收银台链接或收款地址，并将付款通知与该订单关联对账。

<figure><img src="https://708501463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5CoqhFwqwkrLal2C588B%2Fuploads%2Fgit-blob-b2134347b6c790a888f821b805852a7baf44d6d4%2Facquiring-order-mode.png?alt=media" alt="收银台模式：按订单分配地址"><figcaption><p>每笔支付订单获得一个临时地址，默认有效期为一天。</p></figcaption></figure>

### 接入流程 <a href="#integration-flow-1" id="integration-flow-1"></a>

1. 完成[身份认证](/cn/integration/authentication.md)接入，并实现 [Webhook 通知](/cn/integration/webhook.md)验签。
2. 创建本地订单，包含唯一的请求 ID、币种和预期金额。
3. 调用 `POST /v1/order/pay`，设置 `payment_method=on_chain`。响应同时包含 `receive_address` 和 `checkout_url`；您可以展示收款地址，也可以引导客户进入托管收银台。
4. 保存平台订单号，并在收款地址到期前向客户展示返回的付款信息。
5. 验证收到的通知，检查订单最终状态，并在履约前核对实际付款金额与预期金额。
6. 需要时使用[查询订单](/cn/reference/api-reference/query-order.md)获取最新结果。

创建订单的响应或浏览器跳转本身不能证明付款成功。请以 Webhook 通知或订单查询返回的交易状态为准。

### 展示付款信息 <a href="#present-payment-instructions" id="present-payment-instructions"></a>

`on_chain` 响应同时包含同一订单的 `receive_address` 和 `checkout_url`：

* 在自有界面展示付款信息时，展示 `receive_address`。
* 使用托管收银台时，引导客户进入 `checkout_url`。

请求和响应示例请参阅[指定链收银台](/cn/reference/api-reference/crypto-payments/acquiring/checkout-mode/specified-chain-checkout.md)。示例包括数字货币计价订单，以及使用数字货币付款的法币计价订单。两者均属于数字货币支付，因为实际付款发生在链上。

### 地址有效期 <a href="#address-lifetime" id="address-lifetime"></a>

每笔收银台订单都会获得一个临时付款地址，**默认有效期为一天**。请在地址到期前展示地址或收银台链接，不要将其当作钱包模式中可重复使用的充值地址。

如果款项在地址到期后到账，请先根据 Webhook 通知或订单查询结果对账，再进行履约。不能仅凭地址已到期就判断逾期付款是否已被接受或退款。

### 付款金额差异 <a href="#payment-amount-differences" id="payment-amount-differences"></a>

默认情况下，仅当 `pay_amount = order_amount` 时，收银台订单才会成功并发送支付成功通知。如需接受少付或多付，请联系 Topay 运营团队为您的账户启用此配置。

履约前，请比较通知中的付款金额与预期金额，并检查交易状态。少付、多付、手续费示例及接受规则请参阅[支付金额处理](/cn/integration/crypto-payments/acquiring/payment-amount-handling.md)。

## 相关参考 <a href="#related-references" id="related-references"></a>

* [支持的资产](/cn/reference/supported-assets.md)
* [数字货币收单 API](/cn/reference/api-reference/crypto-payments/acquiring.md)
* [Webhook 通知](/cn/integration/webhook.md)
* [订单状态](/cn/reference/enums/order-status.md)