Silver 以上のメンバーシップが必要です — 申請時だけでなく、認証済みのすべての呼び出しでも同様です。キー所有者のメンバーシップが失効すると、再加入するまでプロジェクトは凍結されます。
/v1 配下でバージョン管理されています。
アクセスの取得
アクセスはプロジェクト単位で付与されます。次の 4 つすべてが必要です。1
有効な Silver 以上のメンバーシップ
承認時だけでなく、呼び出しのたびに確認されます。
2
承認された開発者申請
ダッシュボードの Vito API ページから送信します。Vetox チームが手作業で審査します。
3
API 開発者規約への同意
申請を送信する際に承諾します。
4
プロジェクトに必要なスコープ
記載内容に基づいて Vetox チームが付与します。
スコープ
認証
シークレットキーを Bearer トークンとして送信します。- IP 許可リスト — 呼び出しを特定のサーバー IP に限定します
- レート制限 — 所有者のメンバーシップ階層に応じて上がる、プロジェクトごとの上限です
キーのローテーションと保管
- サーバー側だけに保管してください — 手にした者は誰でもあなたのユーザーに請求できます
- ローテーションは API キータブから行います。以前のキーは 24 時間の猶予期間にわたり有効なままなので、停止なしでデプロイできます
- webhook の署名シークレットは別枠でローテーションされ、独自の 24 時間の重複期間を持ちます
- 漏洩した場合は直ちにローテーションしてください
ユーザーへの請求
1
アプリが POST /v1/deduct を呼び出す
ユーザー、金額、発生元の
guildId、商品の詳細を添えて送信します。2
Vito が confirmUrl を返す
保留中の確認で、有効期間は 10 分です。ユーザーには DM も届きます。
3
ユーザーが PIN で承認する
vetox.io 上で行います。4
Vito が決済して通知する
残高が引き落とされ、取引が記録され、設定していれば署名付き webhook が送信されます。
5
アプリが検証して完了する
署名を確認してから、コンテンツを解放するか商品を引き渡します。
リクエストパラメーター — /v1/deduct
ユーザーへの付与
POST /v1/add は自分の残高を原資にユーザーへ Vito を付与します。報酬や返金に使います。フィールドは guildId と product を除いて /deduct と同じです。
請求とは異なり、付与に確認ステップはありません — 即時に決済されます。
credit:create スコープと十分な残高が必要で、足りない場合は 402 VITO_INSUFFICIENT_OWNER_FUNDS が返ります。手数料
すべての請求は、プラットフォーム手数料を差し引いてあなたに支払われます。アプリ内の Vito 送金と同じ料率で、あなたのメンバーシップ階層に基づきます。5 Vito 以下の金額は手数料無料で、
/v1/add による付与は常に手数料無料です。Webhook
設定タブでhttps のコールバック URL を 1 つ以上追加します。確認が終了状態に達するたびに、Vito が署名付きの POST を送信します。
署名の検証
すべての配信にはX-Vito-Signature ヘッダーが付きます。
X-Vito-Event-Id を重複排除キーとして使ってください。
署名シークレットで
<ts>:<rawBody> の HMAC を再計算し、一定時間で比較してください。
イベント
イベントは 5 種類で、すべて同じペイロード形式を共有します。結果はdata.status が保持します。
webhook はバックオフを挟んで 5 回再試行されます。速やかに 2xx を返し、引き渡し処理は非同期で行ってください。
エラーコード
すべてのレスポンスはエンベロープに包まれます。成功時はdata、失敗時は error を持ち、両方が同時に入ることはありません。
レート制限
さらに、1 分あたりの上限の半分(下限 30)が IP ごとの制限として適用されます。
再試行を安全に重複排除するには
Idempotency-Key ヘッダーを送信してください。エンドポイント
制限
- 確認は 10 分で失効します — 未確認のリクエストは破棄されたものとして扱ってください
amountは正の整数である必要がありますmetadataは 10 キーまでです- 1 取引あたりと 1 日あたりの上限は Vetox チームが設定し、設定タブに読み取り専用で表示されます
セキュリティチェックリスト
シークレットはサーバー側に置く
シークレットはサーバー側に置く
API キーと署名シークレットをクライアントコードに置いてはいけません。いずれかが漏洩したら直ちにローテーションしてください。
すべての webhook を検証する
すべての webhook を検証する
生のボディに対して署名を確認し、約 5 分より古い配信は拒否してください。
completed のときだけ決済する
completed のときだけ決済する
/deduct のレスポンスで引き渡してはいけません。請求は confirmation.completed で初めて確定します。最小権限
最小権限
実際に使うスコープだけを申請し、IP 許可リストを有効にしてください。
トラブルシューティング
すべての呼び出しが未認証を返す
すべての呼び出しが未認証を返す
所有者のメンバーシップが失効しています。呼び出しのたびに再確認されます。
キーを紛失した
キーを紛失した
復元はできません — 保存されているのはハッシュだけです。ローテーションして新しいものを取得してください。
ローテーション後に webhook の署名検証が失敗する
ローテーション後に webhook の署名検証が失敗する
24 時間の重複期間中は両方のシークレットを受け入れてください。
請求がいつまでも完了しない
請求がいつまでも完了しない
ユーザーが承認していません。確認は 10 分で失効します。
webhook がまったく届かない
webhook がまったく届かない
プロジェクトにはコールバック URL と署名シークレットの両方が必要です。片方だけでは何も配信されません。
請求した額より少ない Vito しか届かない
請求した額より少ない Vito しか届かない
決済手数料です。避けるには 5 Vito 以下の金額を使うか、価格に織り込んでください。
402 VITO_INSUFFICIENT_OWNER_FUNDS
402 VITO_INSUFFICIENT_OWNER_FUNDS
/v1/add はあなた自身の残高を原資とし、無から作られるものではありません。残高を補充してください。Vito
残高、PIN、手数料について。
支払いリクエスト
請求したときにユーザーに見えるもの。