請求と自動チャージ

概要

ウォレットのエンドポイントでは、認証済みユーザーがチャージ設定の確認、支払いリンクの作成、コードの引き換え、チャージ履歴の確認、および自動チャージの管理を行えます。

支払いと自動チャージのエンドポイントは、金銭に関わる処理を実行します。ユーザーによる明示的な確認を得た後、信頼できるバックエンドからのみ呼び出してください。

チャージ設定を取得

金額や支払方法を提示する前に、必ず現在の設定を読み取ってください。

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

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にリダイレクトします。リンクを受け取っただけでは、ウォレットにクレジットが加算されたことにはなりません。決済プロバイダーが完了を確認した後に、クレジットが加算されます。

リダイレクトURLにシステムアクセストークンを埋め込んだり、決済プロバイダーに送信したりしないでください。

チャージコードの引き換え

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回限り有効です。ログに記録したり、成功した引き換えを再試行したりしないでください。

チャージ履歴

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を使用します。決済完了後、チャージ履歴とアカウント残高の両方を更新してください。

curl -fsS "$BASE_URL/api/user/self" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq '.data.quota'

アカウントのクォータは内部単位で表されます。認証とクォータの説明に従って、quota_per_unitを使用して換算してください。

自動チャージの状態を取得

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: 自動チャージを設定できるかどうか

支払方法を紐付ける

支払方法が連携されていない場合は、設定フローを開始してください。

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つの設定をすべて同時に更新してください。

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を設定して送信すると、紐付けられた支払い方法を削除せずに自動チャージを無効にできます。

紐付けを解除

curl -fsS -X DELETE "$BASE_URL/api/user/auto-recharge/binding" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

連携を解除すると、自動チャージも無効になり、保存されたカード参照も削除されます。このエンドポイントを呼び出す前に、明示的な確認を必須にしてください。

推奨される支払いフロー

/api/user/topup/infoを読み取り、金額と方法を検証してください。
支払リンクまたは紐付け用リンクは1度だけ作成してください。
返されたリンクにユーザーをリダイレクトします。
プロバイダーからのリダイレクトは処理待ちとして扱い、クレジット加算の確定証拠とはみなさないでください。
期待する状態が表示されるまで、/api/user/topup/self、/api/user/self、または/api/user/auto-rechargeを再取得してください。
アプリケーション側で再試行の冪等性を確保し、同じユーザー操作に対して複数の決済リンクを作成しないようにしてください。

人気モデル

OpenAI SDKの使い方

システムAPI

テキストシリーズ

意思決定モデル

埋め込みシリーズ

画像シリーズ

動画シリーズ

その他

請求と自動チャージ

概要

チャージ設定を取得

決済リンクを作成する

チャージコードの引き換え

チャージ履歴

自動チャージの状態を取得

支払方法を紐付ける

自動チャージの設定

紐付けを解除

推奨される支払いフロー

​概要

​チャージ設定を取得

​決済リンクを作成する

​チャージコードの引き換え

​チャージ履歴

​自動チャージの状態を取得

​支払方法を紐付ける

​自動チャージの設定

​紐付けを解除

​推奨される支払いフロー

概要

チャージ設定を取得

決済リンクを作成する

チャージコードの引き換え

チャージ履歴

自動チャージの状態を取得

支払方法を紐付ける

自動チャージの設定

紐付けを解除

推奨される支払いフロー