サブアカウントの自動リチャージ（カスタム決済プロバイダー） #

Stripe以外のプロバイダー（銀行振込、ローカル決済ゲートウェイ、カスタム課金システムなど）を使用してサブアカウントのクレジット支払いを処理したい場合、プラットフォームが提供するWebhookとAPIのペアを使用することで、課金から付与までの一連の処理を独自に実行できます。技術的な詳細以外の概要についてはエージェンシーアカウントページをご覧ください。このページでは、正確なWebhookペイロードと、その後にクレジットを付与するために呼び出すAPIについて説明します。

Webhookは、自動チャージの支払い方法の1つに過ぎません。SaaSモードで Stripe または PayPal を接続している場合、プラットフォームがクライアントの保存済みカードやPayPalアカウントに直接課金してクレジットを付与するため、このページで何かを構築する必要はありません。ご自身で決済を処理したい場合のみ、以下をお読みください。

フローの概要 #

1. サブアカウントのクレジット残高が自動リチャージのしきい値を下回ります。
2. プラットフォームが、サブアカウントの詳細と必要なクレジット数を指定して、お客様のWebhook URLを呼び出します。
3. お客様のサーバーが、利用しているプロバイダーを通じて顧客に課金します。
4. お客様のサーバーがクレジット付与APIを呼び出し、そのサブアカウントにクレジットを追加します。
5. お客様のサーバーが 200 を返し、Webhookを受信したことを通知します。

1. Webhook: agency_sub_account_auto_recharge #

メインサイドバーの SaaS Mode をクリックし、Use a Custom Payment Provider Instead を選択する（または、設定済みの場合は Custom Payment Provider カードを開く）ことで、Auto-Recharge Webhook フィールドにWebhook URLを設定します。

トリガー条件 #

サブアカウントのクレジット残高が、設定された自動リチャージのしきい値を下回ったときに実行されます。

ペイロード #

{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<sub-account-id>",
  "sub_account_email": "customer@example.com",
  "sub_account_name": "John Doe",
  "agency_id": "<agency-id>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}

重要な注意点 #

• 5分間のクールダウン — サブアカウントに対してリチャージを試みた後、プラットフォームは少なくとも5分間は、残高がさらに低下してもそのサブアカウントに対して別のWebhookを送信しません。これにより、処理中の二重課金を防ぎます。
• べき等キーの使用 — クレジットを付与する前に、必ず idempotency_key を確認してください。クレジット付与後にサーバーがクラッシュし、応答を返す前に停止した場合、プラットフォームは次のクレジット低下時にWebhookを再送する可能性があります。
• 失敗時の安全性と自己修復 — Webhook URLに到達できない、またはエラーが返された場合、クレジットは付与されません。サブアカウントがしきい値を下回っている限り、プラットフォームはWebhookを再送し続けます（5分間のクールダウンごとに1回）。残高がしきい値を超えて再び下回るのを待つ必要はありません。1回の課金失敗によって、サブアカウントが永久にリチャージされない状態になることはありません。
• リチャージ金額をしきい値以上に設定する — 設定するリチャージ金額は、自動リチャージのしきい値以上である必要があります。これにより、1回のリチャージで必ず残高がしきい値以上に戻ります。（しきい値を大幅に下回ってしまったサブアカウントを修正する必要がある場合、プラットフォームは不足分を自動的に全額補充します。上記の credits_requested を参照してください。）

2. クレジット付与API #

サーバーでの支払処理が完了した後、このエンドポイントを呼び出してサブアカウントにクレジットを追加します。

リクエスト #

POST https://api.dmchamp.com/v1/subaccounts/credits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}

認証: APIキーをリクエストヘッダー（X-API-Key: YOUR_API_KEY または Authorization: Bearer YOUR_API_KEY）で送信してください。URLにキーを含めるとブラウザの履歴、プロキシログ、サーバーアクセスログに残ってしまうため、ヘッダーでの送信が推奨されます。?apiKey=YOUR_API_KEY クエリパラメータおよびJSONボディ内の apiKey フィールドも引き続き利用可能なため、古いインテグレーションも変更なしで動作し続けます。

レスポンス #

{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}

毎月のリセット時に付与されたクレジットはどうなりますか #

これはサブアカウントの設定方法によって異なります。

• 再販（サブアカウントがあなたにクレジットの対価を支払う場合）：ここで付与したクレジットは購入済みクレジットとして記録され、毎月繰り越されます。サブアカウントが消費しなかった分は、そのまま残高として保持されます。
• 割り当て（サブアカウントに毎月の許容量を与える場合）：リセット日に残高が毎月の許容量まで補充されるため、消費されなかった分は繰り越されません。これは意図的な仕様であり、許容量は毎月新たに付与されます。

サブアカウントの残高を新しい月間許容量と置き換えるのではなく、上乗せしたい場合は、クレジットの繰り越しを有効にしてください。

PUT https://api.dmchamp.com/v1/subaccounts/{subAccountUid}/limits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "usageLimits": { "roll_over_to_next_month": true }
}

サブアカウント（またはそのサブアカウントが属するプラン）に繰越上限や有効期限が設定されている場合、リセットはその設定が適用されるタイミングで行われます。つまり、新しい許容量が追加される前に、繰り越された許容量が許可された月数分に調整され、有効期限を過ぎて未使用のまま残っていた許容量は削除されます。このエンドポイントを通じて付与されたクレジット、自動リチャージ、およびクライアント自身によるチャージは、一度限りのクレジットであり、調整（削除）されることはありません。詳細は 繰越上限の設定 を参照してください。

エンドツーエンドの例 #

一般的なハンドラーは次のようになります。

on POST /your-recharge-webhook:
  payload = request.body

  if seen(payload.idempotency_key):
    return 200  // already processed, ack and exit

  charge_result = your_payment_provider.charge(
    email = payload.sub_account_email,
    amount_cents = payload.total_amount_cents,
    currency = payload.price_per_credit_currency,
  )

  if not charge_result.ok:
    return 500  // platform will retry on next balance drop

  api.post("/v1/subaccounts/credits", {
    email = payload.sub_account_email,
    amount = payload.credits_requested,
    description = "Auto-recharge via " + your_provider_name,
  })

  mark_seen(payload.idempotency_key)
  return 200