> ## 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.

# 稳定币结账

> 创建并管理结账支付链接，实现无缝的稳定币支付

<Note>
  简而言之<br />
  Blockradar Checkout 让您可以通过可分享的链接接收稳定币付款，无需客户账户或复杂的集成。创建链接，分享它，然后直接在您的 wallet 中收款。
</Note>

<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 />

## 前置条件

在创建支付链接之前，请确保您具备：

<Steps>
  <Step title="API 密钥">
    从 [Blockradar Dashboard](https://dashboard.blockradar.co) 获取您的 API 密钥。前往 **Developers** 生成密钥。
  </Step>

  <Step title="已创建 Master Wallet">
    通过 [Create Wallet API](/en/api-reference/wallets/create-wallet) 或 dashboard 创建一个 master wallet。支付链接绑定到 wallet。
  </Step>

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

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

## 简介

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

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

## 支付链接的工作原理

<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>

## 支付链接功能

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

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

* 跨多个区块链支持 **USDT、USDC、DAI、BUSD**
* **Ethereum、BSC、Polygon、Base、Arbitrum、Optimism、Tron、Solana、Celo**
* 自动转换和路由，提供最佳的用户体验

### **灵活配置**

* 针对特定产品/服务的**固定金额**
* 针对捐赠或自定义支付的**可变金额**
* **支付限制**以确保按时支付
* **自定义 metadata** 用于跟踪和分析
* **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. 通过 Query 参数预填充客户信息**

您可以使用 query 参数增强支付 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
```

**支持的可选 Query 参数：**

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

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

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

**重定向 Query 参数：**

* `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 payload 中，使您能够将支付与内部系统关联起来。

## 立即体验

通过我们的实时演示亲身体验 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 字符串） | 自定义 metadata，作为键值对（字符串或数字）。必须以 JSON 字符串形式在 form-data 中发送 |
| `paymentLimit`    | number（最小：1）     | 此链接允许的最大支付次数                                             |
| `file`            | file             | 附加到支付链接的可选文件上传（例如图像或文档）                                  |

## 支付流程

### **客户体验**

1. **点击支付链接**

   * 客户接收并点击支付链接
   * 链接打开一个安全的支付页面

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

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

3. **完成支付**

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

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

### **商家体验**

1. **实时通知**

   * 支付状态的 webhook 事件
   * 电子邮件通知（如果已配置）
   * Dashboard 更新

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

## 地址生命周期

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

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

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

## Webhook 事件

收到付款时，支付链接会触发以下 webhook 事件：

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

### **Webhook Payload 示例**

```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"
    },
    "address": {
      "id": "824d8ff9-1ee4-43d1-bec0-c77f25699cd6",
      "address": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
      "name": null,
      "isActive": true,
      "type": "INTERNAL",
      "derivationPath": "m/44'/60'/0'/0/503",
      "metadata": null,
      "configurations": {
        "aml": {
          "status": "success",
          "message": "Address is not sanctioned",
          "provider": "ofac, fbi, tether, circle"
        }
      },
      "network": "mainnet",
      "createdAt": "2025-08-27T21:52:19.839Z",
      "updatedAt": "2025-08-27T21:52:19.839Z"
    },
    "blockchain": {
      "id": "28a730d3-211b-40f7-bb8f-dd589dcc738e",
      "name": "base",
      "symbol": "eth",
      "slug": "base",
      "derivationPath": "m/44'/60'/0'/0",
      "isEvmCompatible": true,
      "isL2": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800080/crypto-assets/Base_Network_Logo_vqyh7r.png",
      "isActive": true,
      "tokenStandard": null,
      "createdAt": "2024-06-07T11:09:56.586Z",
      "updatedAt": "2025-11-26T15:26:21.825Z"
    },
    "wallet": {
      "id": "6b741fbc-8a9c-48a1-92b0-ae7b52de8b9e",
      "name": "Base Mainnet Wallet",
      "description": "This is base mainnet wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
      "derivationPath": "m/44'/60'/0'/0/0",
      "isActive": true,
      "status": "ACTIVE",
      "network": "mainnet",
      "configurations": {
        "withdrawal": {
          "gasless": {
            "isActive": true
          }
        },
        "autoSweeping": {
          "isActive": true
        }
      },
      "createdAt": "2024-06-15T02:53:23.409Z",
      "updatedAt": "2025-08-18T23:26:13.469Z",
      "business": {
        "id": "a109729b-3b97-4fb3-a90a-769a0cbf6a25",
        "name": "Blockradar",
        "sector": "infrastructure",
        "userId": "831b739e-ed85-499a-b273-8a1a5b41b7a0",
        "status": "ACTIVE",
        "pipedriveOrganizationId": "308",
        "createdAt": "2023-04-28T17:40:18.541Z",
        "updatedAt": "2025-06-19T23:51:01.019Z"
      }
    },
    "beneficiary": null,
    "paymentLink": {
      "id": "dd8eb830-0971-4f61-97bc-b1ad352e1c48",
      "name": "Blockradar Checkout Demo",
      "description": "Blockradar payment links simplify stablecoin transactions into a clean, intuitive experience. This demo shows how users can pay securely using stablecoins with just a few clicks, fast, transparent, and onchain.",
      "slug": "demo",
      "amount": null,
      "currency": "USD",
      "imageUrl": "https://res.cloudinary.com/blockradar/image/upload/v1752049884/payment-links/ndlbgyb5wg70bpr3p1uu.png",
      "redirectUrl": null,
      "successMessage": null,
      "active": true,
      "inactiveMessage": null,
      "network": "mainnet",
      "type": "payment",
      "createdChannel": "dashboard",
      "metadata": {},
      "configurations": {},
      "createdAt": "2024-06-20T05:38:13.863Z",
      "updatedAt": "2025-07-09T08:31:25.328Z"
    },
    "toAsset": null,
    "toBlockchain": null,
    "toWallet": null
  }
}
```

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

Webhook payload 包含有关支付的全面信息：

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

<Note>
  Webhook payload 中的 `reference` 字段对应于您在支付 URL 中包含的 `reference` query
  参数。这使您能够将支付追溯到您系统中
  的特定订单、客户或内部引用。
</Note>

## 最佳实践

### **安全性**

* **使用 HTTPS** 共享所有支付链接
* **监控 webhook 事件**以发现可疑活动
* **在 webhook 端点上实施 rate limiting**

### **用户体验**

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

### **集成**

* **存储支付链接 ID** 以进行跟踪
* **使用 metadata** 将支付与您的系统关联
* **实施 webhook 重试逻辑**以提高可靠性
* 首先在沙箱环境中**测试 webhooks**

## 用例和示例

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

```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`
  字段必须以 JSON 字符串形式在 form-data 中发送，并且支持上传 `file`
  以添加额外内容。
</Note>

## 测试与开发

### **沙箱环境**

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

### **Webhook 测试**

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

## Checkout 计划

**Blockradar Checkout** 是一个可编程的稳定币支付层，用于通过链接、嵌入式 QR 码和 WalletConnect 接收链上支付。资金直接结算到您的非托管 wallets 中，并内置对 swap、bridge 和资金路由的支持。

### **定价**

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

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

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

### **多链支持**

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

### **资金管理**

* **Swap 和 Bridge**：跨链转换和移动资产
* **自动结算**：自动结算为您的首选货币
* **Circle Gateway**：访问 Circle 的跨链转账协议
* **Auto-sweeping**：将资金归集到您的 master wallet

<Note>
  此计划不包括 Wallet-as-a-Service (WaaS) 功能，也不包括为您的
  最终用户提供专用 wallets。
</Note>

## 获取支付链接的交易

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

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

### **Query 参数**

| 参数       | 类型     | 描述                                 |
| -------- | ------ | ---------------------------------- |
| `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 参考**

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

### **获取帮助**

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

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