> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> 创建和管理 Checkout 收款链接，实现无缝稳定币支付

<Note>
  概述<br />
  Blockradar Checkout 提供了一种接受稳定币支付的简单方式，无需客户拥有 Blockradar 账户或直接与您的应用程序集成。收款链接是 Checkout 系统的核心功能。
</Note>

## 前提条件

在创建收款链接之前，请确保您已完成以下步骤：

<Steps>
  <Step title="API 密钥">
    从 [Blockradar 控制面板](https://dashboard.blockradar.co) 获取您的 API 密钥。导航至 **Developers** 生成密钥。
  </Step>

  <Step title="创建主钱包">
    通过 [创建钱包 API](/zh/api-reference/wallets/create-wallet) 或控制面板创建主钱包。收款链接与钱包绑定。
  </Step>

  <Step title="Checkout 功能已激活">
    确保您的账户已启用 Checkout 功能。如需激活，请联系 [support@blockradar.co](mailto:support@blockradar.co)。
  </Step>

  <Step title="配置 Webhooks（可选）">
    设置 Webhook 以接收实时支付通知。详情请参阅 [Webhooks](/zh/essentials/webhooks)。
  </Step>
</Steps>

<iframe className="w-full h-[500px]" height="315" src="https://www.youtube.com/embed/nHCakfoSPWw?si=zar81as8HDK-HMrB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## 简介

收款链接是可分享的 URL，允许任何人向您的钱包发送稳定币支付。它们非常适合：

* **电子商务**：发送给客户用于产品购买
* **开票**：包含在服务发票中
* **捐赠**：在社交媒体或网站上分享
* **市场支付**：促进点对点交易
* **订阅计费**：定期收款

## 收款链接工作原理

<CardGroup cols={2}>
  <Card title="创建" icon="plus">
    使用特定参数创建收款链接，如金额、名称、描述和支付限制。
  </Card>

  <Card title="分享" icon="share">
    通过电子邮件、消息分享生成的 URL，或嵌入到您的网站中。
  </Card>

  <Card title="支付" icon="credit-card">
    客户点击链接，输入支付详情并完成交易。
  </Card>

  <Card title="确认" icon="check">
    您收到 Webhook 通知，可以实时跟踪支付状态。
  </Card>
</CardGroup>

## 收款链接功能

* **可自定义参数**：设置金额、描述、支付限制和元数据
* **可分享 URL**：为每笔交易生成唯一的收款链接
* **客户预填充**：通过 URL 查询参数预填充客户详情
* **实时跟踪**：监控支付状态并接收 Webhook 通知
* **多网络支持**：在不同区块链网络上接受支付
* **自动归集集成**：资金自动归集到主钱包

### **多资产支持**

* 多条区块链上支持 **USDT、USDC、DAI、BUSD**
* **Ethereum、BSC、Polygon、Base、Arbitrum、Optimism、Tron、Solana、Celo**
* 自动转换和路由以获得最佳用户体验

### **灵活配置**

* **固定金额**用于特定产品/服务
* **可变金额**用于捐赠或自定义支付
* **支付限制**确保及时支付
* **自定义元数据**用于跟踪和分析
* **Webhook 通知**用于实时更新

### **安全与合规**

* 对所有入金进行 **AML 筛查**
* **地址验证**和核实
* **欺诈检测**和预防
* 跨司法管辖区的**合规监管**

## 支付流程

### **1. 创建收款链接**

创建收款链接时，Blockradar 返回唯一的支付 URL：

```json theme={null}
{
  "id": "pl_123456789",
  "name": "Product Purchase",
  "url": "https://pay.blockradar.co/payment-link-10012",
  "amount": "100.00",
  "currency": "USD",
  "active": true
}
```

### **2. 使用查询参数预填充客户信息**

您可以使用查询参数增强支付 URL，以在支付页面上自动预填充客户详情：

```
https://pay.blockradar.co/payment-link-10012?name=Customer&email=customer@example.com&reference=ORDER123&amount=99.99&redirectUrl=https://yoursite.com/payment-success
```

**支持的可选查询参数：**

* `name` - 客户姓名（显示在支付页面上）
* `email` - 客户邮箱地址
* `reference` - 自定义引用，将包含在交易响应中
* `amount` - 预填充支付金额（如果设置，将覆盖链接的默认金额）
* `redirectUrl` - 支付完成后重定向的 URL

### **3. 支付后重定向**

提供 `redirectUrl` 时，客户在支付处理完成后将自动重定向到您指定的 URL。重定向 URL 将包含以下查询参数：

**重定向查询参数：**

* `status` - 支付状态（`success`、`failed`、`pending`）
* `tx_reference` - 交易参考 ID
* `reference` - 您的自定义引用（如果提供）
* `slug` - 收款链接标识符

**重定向 URL 示例：**

```
https://yoursite.com/payment-success?status=success&tx_reference=tx_abc123&reference=ORDER123&slug=payment-link-10012
```

<Note>
  重定向仅在支付处理完成后发生。如果未提供 `redirectUrl`，客户将看到默认的支付完成页面。
</Note>

### **4. 金额配置**

收款链接支持两种金额模式：

**固定金额（预设）**

* 创建时指定 `amount` 后，客户无法修改支付金额
* 适用于定价固定的特定产品或服务
* 示例：产品购买 \$99.99

**可变金额（客户输入）**

* 未指定 `amount` 时，客户可以输入自己的支付金额
* 非常适合捐赠、小费或灵活定价场景
* 客户在支付页面上看到金额输入框

### **4. 支付处理**

客户访问收款链接，查看预填充的详情，并使用其首选的稳定币完成交易。

### **5. 交易响应**

URL 中的 `reference` 参数将包含在交易响应和 Webhook 载荷中，允许您将支付链接回您的内部系统。

## 试用体验

通过我们的在线演示亲身体验 Blockradar 收款链接：

**演示收款链接**：[https://pay.blockradar.co/demo](https://pay.blockradar.co/demo)

此演示展示：

* **支付流程**：从链接到完成的完整客户体验
* **UI/UX**：现代、直观的支付界面
* **稳定币选项**：多种支付方式和网络
* **实时更新**：实时交易状态和确认

<Note>
  演示收款链接仅用于测试目的。不会处理真实交易。
</Note>

## 创建收款链接

### **基本收款链接**

为固定金额创建简单的收款链接：

```json theme={null}
{
  "name": "Product Purchase",
  "description": "Payment for Laptop Pro 2024",
  "amount": "100.00",
  "redirectUrl": "https://store.example.com/thank-you",
  "successMessage": "Thank you for your purchase!",
  "metadata": "{\"product_id\": \"prod_123\", \"order_id\": \"ord_456\"}"
}
```

### **可变金额收款链接**

允许客户选择支付金额：

```json theme={null}
{
  "name": "Donation Campaign",
  "description": "Support our disaster relief efforts",
  "redirectUrl": "https://charity.example.com/thank-you",
  "successMessage": "Thank you for your generous donation!",
  "metadata": "{\"campaign\": \"disaster_relief_2024\"}"
}
```

### **带文件上传的收款链接**

使用 form-data 在收款链接中包含文件（例如发票、产品图片）：

**Form Data 字段：**

* `name`：Service Invoice
* `description`：Web development services - January 2024
* `amount`：1500.00
* `redirectUrl`：[https://company.example.com/payment-success](https://company.example.com/payment-success)
* `successMessage`：Payment received! We'll start working on your project.
* `metadata`：invoice\_id: INV-2024-001, service: web\_development
* `file`：\[cover.png]（文件上传）

<Note>
  包含文件上传时，使用 form-data 而不是 JSON。文件将被存储并可通过收款链接访问。
</Note>

## 收款链接参数

### **必需参数**

| 参数     | 类型             | 描述     |
| ------ | -------------- | ------ |
| `name` | string（最大：250） | 收款链接名称 |

### **可选参数**

| 参数                | 类型               | 描述                                                      |
| ----------------- | ---------------- | ------------------------------------------------------- |
| `description`     | string（最大：250）   | 收款链接描述                                                  |
| `slug`            | string（最大：250）   | 唯一标识符（URL 友好）。必须匹配正则：`^[a-zA-Z0-9-]+$`                  |
| `amount`          | string           | 收款链接金额。必须是有效的字符串数字 > 0                                  |
| `redirectUrl`     | string（URL）      | 支付后重定向用户的 URL。必须包含 http\:// 或 https\://                 |
| `successMessage`  | string（最大：500）   | 支付成功时显示的消息                                              |
| `inactiveMessage` | string（最大：500）   | 收款链接非活跃时显示的消息                                           |
| `metadata`        | object（JSON 字符串） | 自定义元数据键值对（string 或 number）。在 form-data 中必须作为 JSON 字符串发送 |
| `paymentLimit`    | number（最小：1）     | 此链接允许的最大支付次数                                            |
| `file`            | file             | 可选文件上传（例如图片或文档），附加到收款链接                                 |

## 支付流程

### **客户体验**

1. **点击收款链接**

   * 客户收到并点击收款链接
   * 链接打开安全支付页面

2. **选择支付方式**

   * 从可用的稳定币中选择
   * 选择首选区块链网络
   * 输入支付金额（如果可变）

3. **完成支付**

   * 客户确认交易详情
   * 支付在区块链上处理
   * 实时确认和状态更新

4. **成功确认**
   * 支付确认页面
   * 可选重定向到您的网站
   * 收据和交易详情

### **商户体验**

1. **实时通知**

   * 支付状态的 Webhook 事件
   * 邮件通知（如已配置）
   * 控制面板更新

2. **支付跟踪**
   * 交易历史和状态
   * 支付分析和报告
   * 与您系统的集成

## 地址生命周期

<Warning>
  为结账链接生成的支付地址具有有限的生命周期：

  * **成功支付后**：地址立即停用，无法接收额外付款
  * **24小时不活动后**：如果24小时内没有向该地址付款，它将自动停用

  每个新的支付会话都会生成一个新地址。这确保了安全性并防止地址重复使用。
</Warning>

## Webhook 事件

收款链接在收到支付时触发以下 Webhook 事件：

| 事件                | 描述         |
| ----------------- | ---------- |
| `deposit.success` | 通过收款链接收到付款 |
| `deposit.failed`  | 支付尝试失败     |

### **Webhook 载荷示例**

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "id": "0d7a0b98-943c-48d0-8baa-216c29956050",
    "reference": "bjXPk7d00",
    "senderAddress": "0x451dEFC27B45808078e875556AF06bCFdC697BA4",
    "recipientAddress": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1",
    "amountPaid": "1",
    "amountUSD": "1",
    "rateUSD": "1",
    "fee": null,
    "feeHash": null,
    "currency": "USD",
    "toCurrency": null,
    "blockNumber": 34771099,
    "blockHash": "0xa9dc060dbe649676a15ae1faee725851fe1ecf2401b200e60fff33fc0ff41e84",
    "hash": "0x9f01af8f517afb3fd3ee17f36dabee03a4d6514885473115815de86c28ea7dfb",
    "confirmations": 6,
    "confirmed": true,
    "gasPrice": "7026436",
    "gasUsed": "62159",
    "gasFee": "0.000000436756235324",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "note": null,
    "amlScreening": {
      "provider": "ofac, fbi, tether, circle",
      "status": "success",
      "message": "Address is not sanctioned"
    },
    "assetSwept": true,
    "assetSweptAt": "2025-08-27T21:53:22.300Z",
    "assetSweptGasFee": "0.000000489848406004",
    "assetSweptHash": "0xe85efcf15ff8eaa2429aea32515347d65ff8098f22dac567611c258441bde809",
    "assetSweptSenderAddress": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
    "assetSweptRecipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "assetSweptAmount": "1",
    "reason": "Funds swept successfully",
    "network": "mainnet",
    "chainId": 8453,
    "metadata": {},
    "toAmount": null,
    "signedTransaction": null,
    "rate": null,
    "createdAt": "2025-08-27T21:52:19.839Z",
    "updatedAt": "2025-08-27T21:53:22.303Z",
    "asset": {
      "id": "3a18a31a-86ad-44a0-9b9c-cdb69d535c64",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "standard": null,
      "currency": "USD",
      "isActive": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800083/crypto-assets/usd-coin-usdc-logo_fs9mhv.png",
      "network": "mainnet",
      "isNative": false,
      "createdAt": "2024-06-08T12:59:11.303Z",
      "updatedAt": "2025-06-03T11:34:36.288Z"
    },
    "paymentLink": {
      "id": "dd8eb830-0971-4f61-97bc-b1ad352e1c48",
      "name": "Blockradar Checkout Demo",
      "description": "Blockradar payment links simplify stablecoin transactions into a clean, intuitive experience.",
      "slug": "demo",
      "amount": null,
      "currency": "USD",
      "redirectUrl": null,
      "successMessage": null,
      "active": true,
      "network": "mainnet",
      "type": "payment",
      "metadata": {},
      "configurations": {},
      "createdAt": "2024-06-20T05:38:13.863Z",
      "updatedAt": "2025-07-09T08:31:25.328Z"
    }
  }
}
```

### **关键 Webhook 数据字段**

| 字段             | 描述                                       |
| -------------- | ---------------------------------------- |
| `reference`    | URL 查询参数中的自定义引用（例如 ORDER123、customer ID） |
| `paymentLink`  | 完整的收款链接详情，包括名称、描述和元数据                    |
| `asset`        | 资产信息（USDC、USDT 等）及网络详情                   |
| `blockchain`   | 网络信息（Base、Ethereum 等）                    |
| `wallet`       | 主钱包详情和配置                                 |
| `address`      | 收到付款的客户地址                                |
| `amlScreening` | 反洗钱筛查结果                                  |
| `assetSwept`   | 自动归集状态和详情                                |
| `metadata`     | 收款链接中的自定义数据                              |

<Note>
  Webhook 载荷中的 `reference` 字段对应您在支付 URL 中包含的 `reference` 查询参数。这允许您将支付追溯到系统中的特定订单、客户或内部引用。
</Note>

## 最佳实践

### **安全**

* 对所有收款链接分享使用 **HTTPS**
* **监控 Webhook 事件**以发现可疑活动
* 在您的 Webhook 端点上**实施速率限制**

### **用户体验**

* **清晰描述**支付用途
* **移动端优化**支付页面
* 尽可能提供**多种支付选项**

### **集成**

* **存储收款链接 ID** 用于跟踪
* **使用元数据**将支付链接到您的系统
* **实施 Webhook 重试逻辑**以提高可靠性
* 首先在沙盒环境中**测试 Webhook**

## 使用案例与示例

### **电子商务商店**

```json theme={null}
{
  "name": "Laptop Pro 2024",
  "description": "High-performance laptop with latest specifications",
  "amount": "299.99",
  "redirectUrl": "https://store.example.com/thank-you",
  "successMessage": "Thank you for your purchase! Your order has been confirmed.",
  "metadata": "{\"product_id\": \"laptop_pro_2024\", \"category\": \"electronics\", \"customer_email\": \"customer@example.com\"}",
  "paymentLimit": 1
}
```

### **服务发票**

```json theme={null}
{
  "name": "Web Development Services",
  "description": "Professional web development services - January 2024",
  "amount": "1500.00",
  "redirectUrl": "https://company.example.com/payment-success",
  "successMessage": "Payment received! We'll start working on your project immediately.",
  "metadata": "{\"invoice_id\": \"INV-2024-001\", \"service\": \"web_development\", \"client_id\": \"client_789\"}",
  "paymentLimit": 1
}
```

### **捐赠活动**

```json theme={null}
{
  "name": "Disaster Relief 2024",
  "description": "Support our disaster relief efforts in affected regions",
  "amount": "10.00",
  "redirectUrl": "https://charity.example.com/thank-you",
  "successMessage": "Thank you for your generous donation! Every contribution makes a difference.",
  "metadata": "{\"campaign\": \"disaster_relief_2024\", \"organization\": \"charity_foundation\", \"tax_deductible\": true}",
  "paymentLimit": 1000
}
```

### **订阅服务**

```json theme={null}
{
  "name": "Premium Plan Monthly",
  "description": "Monthly subscription to our premium service",
  "amount": "29.99",
  "redirectUrl": "https://service.example.com/welcome",
  "successMessage": "Welcome to Premium! Your subscription is now active.",
  "metadata": "{\"plan\": \"premium_monthly\", \"billing_cycle\": \"monthly\", \"features\": \"unlimited_access\"}",
  "paymentLimit": 100
}
```

<Note>
  这些示例使用正确的 Blockradar 收款链接 API 参数。`metadata` 字段必须在 form-data 中作为 JSON 字符串发送，并支持 `file` 上传以添加额外内容。
</Note>

## 测试与开发

### **沙盒环境**

* 使用测试网络进行开发
* 测试 Webhook 交付和处理
* 端到端验证支付流程
* 测试边缘情况和错误场景

### **Webhook 测试**

* 使用 [webhook.site](https://webhook.site) 等工具进行测试
* 验证签名验证
* 测试重试机制
* 监控 Webhook 交付率

## Checkout 计划

**Blockradar Checkout** 是一个可编程的稳定币支付层，用于通过链接、嵌入式二维码和 WalletConnect 接受链上支付。资金直接结算到您的非托管钱包，内置支持兑换、跨链桥和资金路由。

### **定价**

<Card title="每笔交易 0.75%" icon="percent">
  简单透明的定价，无月度订阅费用。
</Card>

### **支持的稳定币**

* **USDC、USDT、cNGN、IDRX、EUROC** 等

### **多链支持**

* **Ethereum、Polygon、Base、Solana、Tron、Celo** 等

### **资金管理**

* **兑换和跨链桥**：在不同链之间转换和移动资产
* **自动结算**：自动结算为您偏好的货币
* **Circle Gateway**：访问 Circle 的跨链转账协议
* **自动归集**：将资金整合到您的主钱包

<Note>
  此计划不包括钱包即服务 (WaaS) 功能或为您的最终用户提供专用钱包。
</Note>

## 获取收款链接交易

您可以使用专用的交易端点检索与特定收款链接关联的所有交易。这对以下场景很有用：

* **支付跟踪**：监控通过特定链接收到的所有付款
* **对账**：将付款与订单或发票匹配
* **报告**：为特定收款链接生成报告

### **查询参数**

| 参数       | 类型     | 描述                                |
| -------- | ------ | --------------------------------- |
| `page`   | number | 分页页码（默认：1）                        |
| `limit`  | number | 每页结果数（默认：10）                      |
| `status` | string | 按交易状态筛选（如 SUCCESS、PENDING、FAILED） |
| `type`   | string | 按交易类型筛选（如 DEPOSIT）                |
| `order`  | string | 排序顺序（ASC 或 DESC）                  |

### **响应示例**

```json theme={null}
{
  "status": true,
  "message": "Transactions fetched successfully",
  "data": [
    {
      "id": "0d7a0b98-943c-48d0-8baa-216c29956050",
      "reference": "bjXPk7d00",
      "amount": "100.00",
      "amountUSD": "100.00",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "asset": {
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      },
      "customer": {
        "email": "customer@example.com",
        "name": "John Doe"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}
```

## 支持与资源

### **API 参考**

* [创建收款链接](/zh/api-reference/payment-links/create)
* [获取所有收款链接](/zh/api-reference/payment-links/get-all)
* [获取收款链接](/zh/api-reference/payment-links/get-one)
* [更新收款链接](/zh/api-reference/payment-links/update)
* [获取收款链接交易](/zh/api-reference/payment-links/get-transactions)

### **获取帮助**

* **邮箱**：[support@blockradar.co](mailto:support@blockradar.co)
* **API 参考**：[Checkout](/zh/api-reference/payment-links/create)

<Note>
  Checkout 和收款链接是一种以最少集成工作接受稳定币支付的强大方式。从简单的使用案例开始，随着您对系统越来越熟悉，逐渐增加复杂性。
</Note>