> ## 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'
```

帳號額度使用內部單位，請按照[認證與額度](/zh-hant/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. 在應用層保證重試冪等，避免同一次使用者操作生成多個付款連結。