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

引き換えコードは1回限り有効です。ログに記録したり、成功した引き換えを再試行したりしないでください。

## チャージ履歴

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

アカウントのクォータは内部単位で表されます。[認証とクォータ](/ja/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`を確認したうえで機能を有効にしてください。

## 自動チャージの設定

連携後、3つの設定をすべて同時に更新してください。

```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`は0以上でなければなりません。現在のコンソールでは、チャージの`amount`は最低USD 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. 支払リンクまたは紐付け用リンクは1度だけ作成してください。
3. 返されたリンクにユーザーをリダイレクトします。
4. プロバイダーからのリダイレクトは処理待ちとして扱い、クレジット加算の確定証拠とはみなさないでください。
5. 期待する状態が表示されるまで、`/api/user/topup/self`、`/api/user/self`、または`/api/user/auto-recharge`を再取得してください。
6. アプリケーション側で再試行の冪等性を確保し、同じユーザー操作に対して複数の決済リンクを作成しないようにしてください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.