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

# 接收充值

> 生成充值地址、跟踪入账的加密货币充值，并处理充值 webhook。

[Stablecoin Account API 发布方声明](/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

充值是入金（on-ramp）动作：你的账户通过 UQPAY 为你管理的充值地址接收加密货币。你按资产-网络组合申请地址，把它提供给付款方，系统会在交易确认时为你的余额入账并发送通知。

<Info>
  **前置条件**

  * 通过 `x-auth-token` 请求头发送的 API token
  * 想要接收的资产和网络，从 [List Supported Assets and Networks](/zh/stablecoin-account/v1.6/api-reference/list-supported-assets) 中选择 `deposit_enabled: true` 的组合
</Info>

<h2 id="step-1-get-a-deposit-address">
  步骤 1：获取充值地址
</h2>

调用 [Deposit Wallet Address](/zh/stablecoin-account/v1.6/api-reference/deposit-wallet-address)，传入资产和网络。首次调用会生成地址，后续调用返回同一个地址，可以放心重复调用。

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/deposit/address?asset=USDT&network=ETH" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

**响应：**

```json theme={null}
{
  "code": 200,
  "message": "Success",
  "data": {
    "asset": "USDT",
    "network": "ETH",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "qr_code": "https://cdn.uqpaytech.com/qr/...",
    "minimum_deposit": "10.00",
    "create_time": "2024-07-18T14:19:52+08:00"
  }
}
```

把 `wallet_address`（或托管的 `qr_code`）连同 `minimum_deposit` 一并展示给付款方。

<Warning>
  该地址只接受指定网络上的指定资产。以其他代币形式、或经其他网络发送的资金无法自动入账。请在你的界面中把这一点提示到位。
</Warning>

如需审计账户下生成过的所有地址，可分页调用 [List Deposit Addresses](/zh/stablecoin-account/v1.6/api-reference/list-deposit-addresses)，按需用 `asset` 或 `network` 过滤。

<h2 id="step-2-handle-the-deposit-webhook">
  步骤 2：处理充值 webhook
</h2>

系统检测到入账交易后会创建充值订单，并向你的端点推送[充值 webhook](/zh/stablecoin-account/v1.6/webhooks/deposit) 事件：

| 事件类型                   | 含义          |
| ---------------------- | ----------- |
| `ramp.deposit.pending` | 已检测到充值，等待确认 |
| `ramp.deposit.success` | 充值已确认并入账    |
| `ramp.deposit.failed`  | 充值失败        |

事件中的 `source_id` 就是充值 `order_id`；`data` 携带订单内容，包括付款方的 `from_address` 和链上 `txid`。

<Note>
  如果事件的 `data` 包含 `"need_travel_rule": true`，该笔充值会被暂缓，直到你提交付款方（发起方）信息 —— 参见[充值的 Travel Rule](/zh/stablecoin-account/v1.6/guide/travel-rule-for-deposits)。无需处理时该字段不会出现。
</Note>

<h2 id="step-3-query-deposit-orders">
  步骤 3：查询充值订单
</h2>

用 [List Deposits](/zh/stablecoin-account/v1.6/api-reference/list-deposits) 对账，或用 [Retrieve Deposit](/zh/stablecoin-account/v1.6/api-reference/retrieve-deposit) 查询单个订单：

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/deposit?page_num=1&page_size=20&asset=USDT&status=Success" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

每个充值订单包含：

| 字段                               | 描述                             |
| -------------------------------- | ------------------------------ |
| `order_id` / `short_order_id`    | 订单标识（长 UUID / 便于识别的短编号）        |
| `order_status`                   | `Pending`、`Success` 或 `Failed` |
| `balance_currency`               | 入账币种                           |
| `network`                        | 充值到账的网络                        |
| `amount`                         | 充值金额                           |
| `deposit_address`                | 收到资金的地址                        |
| `transaction_id`                 | 链上交易哈希                         |
| `create_time` / `completed_time` | 订单时间戳                          |

当 `order_status` 变为 `Success` 后，金额会出现在钱包的 `available_balance` 中 —— 可通过 [Retrieve Asset](/zh/stablecoin-account/v1.6/api-reference/retrieve-asset) 核对。

<h2 id="related">
  相关页面
</h2>

* [Deposit Wallet Address API](/zh/stablecoin-account/v1.6/api-reference/deposit-wallet-address)
* [List Deposits API](/zh/stablecoin-account/v1.6/api-reference/list-deposits)
* [充值 webhook](/zh/stablecoin-account/v1.6/webhooks/deposit)
* [充值的 Travel Rule](/zh/stablecoin-account/v1.6/guide/travel-rule-for-deposits) —— `need_travel_rule` 为 `true` 时
* [管理资产余额](/zh/stablecoin-account/v1.6/guide/manage-asset-balances)