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

# 充值与自动充值

> 创建充值链接、兑换充值码、查询钱包记录并配置自动充值。

## 概述

钱包接口允许已认证用户读取充值配置、创建支付链接、兑换充值码、查询充值记录以及管理自动充值。

<Warning>
  支付和自动充值接口会创建真实的财务操作。只能在可信服务端、获得用户明确确认后调用。
</Warning>

## 读取充值配置

展示金额或付款方式前，始终先读取当前配置：

```bash theme={null}
topup_info=$(curl -fsS "$BASE_URL/api/user/topup/info" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

jq '.data' <<< "$topup_info"
```

常用字段包括：

| 字段                      | 含义              |
| ----------------------- | --------------- |
| `amount_options`        | 建议充值金额          |
| `min_topup`             | 通用最低充值金额        |
| `stripe_min_topup`      | Stripe 最低充值金额   |
| `pay_methods`           | 已启用的支付处理方及限制    |
| `daily_recharge_tiers`  | 金额区间和赠送比例       |
| `enable_stripe_topup`   | 是否启用 Stripe 充值  |
| `enable_redotpay_topup` | 是否启用对应的加密货币支付流程 |

这些值属于部署和活动配置。创建支付链接前，应再次校验所选金额。

## 创建支付链接

当前钱包流程接收整数美元金额以及以下付款方式：

| `payment_method` | 流程      |
| ---------------- | ------- |
| `credit_card`    | 信用卡结账   |
| `usdt`           | USDT 结账 |

```bash theme={null}
payment=$(curl -fsS -X POST "$BASE_URL/api/user/topup/pay" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "payment_method": "credit_card"
  }')

pay_link=$(jq -er '
  select(.success == true or .message == "success")
  | .data.pay_link
' <<< "$payment")
```

在浏览器中将用户重定向到 `pay_link`。获得支付链接并不代表余额已经到账；支付提供商确认完成后，系统才会入账。

<Note>
  不要把系统访问令牌放入跳转 URL，也不要将其发送给支付提供商。
</Note>

## 兑换充值码

```bash theme={null}
curl -fsS -X POST "$BASE_URL/api/user/topup" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_REDEMPTION_CODE"}' | jq
```

充值码只能使用一次。不要记录充值码，也不要重试已经成功的兑换操作。

## 充值记录

```bash theme={null}
curl -fsS --get "$BASE_URL/api/user/topup/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "p=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "keyword=" | jq
```

响应包含 `items`、`page`、`page_size` 和 `total`。支付完成后，应同时刷新充值记录和账号余额：

```bash theme={null}
curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq '.data.quota'
```

账号额度使用内部单位，请按照[认证与额度](/cn/api-reference/system-api/authentication-and-quota)中的方法通过 `quota_per_unit` 换算。

## 读取自动充值状态

```bash theme={null}
curl -fsS "$BASE_URL/api/user/auto-recharge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

响应字段包括：

* `bound`：是否已绑定可重复扣款的付款方式
* `card_last4`：卡号末四位掩码
* `enabled`：是否已启用自动充值
* `threshold`：触发充值的钱包美元余额
* `amount`：每次触发时充值的美元金额
* `stripe_ready`：当前账号是否可以配置自动充值

## 绑定付款方式

尚未绑定付款方式时，启动设置流程：

```bash theme={null}
setup=$(curl -fsS -X POST "$BASE_URL/api/user/auto-recharge/setup" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 10,
    "amount": 50
  }')

setup_link=$(jq -er '.data.pay_link' <<< "$setup")
```

将用户重定向到 `setup_link`。等待支付提供商回调后，再次调用 `GET /api/user/auto-recharge`，确认 `bound: true` 后才能启用自动充值。

## 配置自动充值

绑定完成后，一次性更新三个设置：

```bash theme={null}
curl -fsS -X PUT "$BASE_URL/api/user/auto-recharge" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 10,
    "amount": 50
  }' | jq
```

`threshold` 不能为负数。当前控制台要求自动充值的 `amount` 至少为 10 美元，但客户端仍应遵守服务器和支付提供商返回的最新限制。

如果只想关闭自动充值而保留绑定的付款方式，请发送相同请求体，并将 `enabled` 设置为 `false`。

## 删除付款绑定

```bash theme={null}
curl -fsS -X DELETE "$BASE_URL/api/user/auto-recharge/binding" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

删除绑定会同时关闭自动充值并移除已保存的卡片引用。调用前必须取得用户明确确认。

## 推荐支付流程

1. 读取 `/api/user/topup/info`，校验金额和付款方式。
2. 只创建一次支付或绑定链接。
3. 将用户重定向到返回的链接。
4. 将支付提供商的跳转结果视为待确认状态，而不是到账证明。
5. 轮询 `/api/user/topup/self`、`/api/user/self` 或 `/api/user/auto-recharge`，直到出现预期状态。
6. 在应用层保证重试幂等，避免同一次用户操作生成多个支付链接。