メインコンテンツへスキップ

クレジットベースの請求

クレジットベースの請求は、APIコール、データストレージ、計算時間など、使用量が変動するサービスに最適な、柔軟な従量課金モデルです。顧客は、固定の定期料金の代わりに、購入または付与されたクレジットを消費します。

このガイドでは、PaymentKit SDKを使用してクレジットベースの請求システムをセットアップし、管理するエンドツーエンドのプロセスを説明します。扱う主要なコンポーネントは以下の通りです。

  • メーター：特定の機能の使用量を定義し、追跡します。
  • クレジットの付与：顧客にクレジットを発行します。
  • メーターイベント：顧客の使用量を発生時に報告します。
  • クレジットトランザクション：付与や消費を含む、すべてのクレジット活動の台帳です。

クレジット請求のワークフロー

以下の図は、セットアップから使用状況の報告、残高の監視まで、クレジットベースの請求の完全なライフサイクルを示しています。

Credit-Based Billing

ステップ1：使用量を追跡するためのメーターを作成する

メーターは、特定の機能の消費を追跡するリソースです。追跡するイベント、使用量を集計する方法（例：すべての値の合計）、および測定単位を定義します。

メーターを作成

javascript
import payment from '@blocklet/payment-js';

async function setupMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.v1',
      aggregation_method: 'sum',
      unit: 'calls',
      description: '顧客が行ったAPIコールの数を追跡します。'
    });
    console.log('メーターが作成されました：', meter.id);
    return meter;
  } catch (error) {
    console.error('メーター作成エラー：', error.message);
  }
}

setupMeter();

この例では、api.calls.v1というイベントをリッスンする'API Calls'という名前のメーターを作成します。aggregation_method: 'sum'は、報告されたすべてのイベントのvalueを合計して総使用量を計算するようにPaymentKitに指示します。

ステップ2：顧客にクレジットを付与する

メーターを作成したら、顧客が消費するためのクレジットを付与する必要があります。プロモーションボーナスとして、または購入後にクレジットを付与できます。各クレジットの付与では、金額、通貨、およびそれが属する顧客を指定します。

プロモーションクレジットを付与

javascript
import payment from '@blocklet/payment-js';

async function grantNewUserBonus(customerId, currencyId) {
  try {
    const thirtyDaysFromNow = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
    const creditGrant = await payment.creditGrants.create({
      customer_id: customerId, // 例：'cus_xxx'
      currency_id: currencyId, // 例：'pc_xxx'
      amount: '1000',
      name: 'New User Bonus',
      category: 'promotional', // 'paid' または 'promotional' にすることができます
      expires_at: thirtyDaysFromNow
    });
    console.log('クレジット付与が作成されました：', creditGrant.id);
    return creditGrant;
  } catch (error) {
    console.error('クレジット付与作成エラー：', error.message);
  }
}

// grantNewUserBonus('cus_xxx', 'pc_xxx');

このコードは、顧客に1,000プロモーションクレジットを付与し、これは30日後に失効します。paidとして分類されたクレジットは、通常promotionalのものより先に消費されます。

ステップ3：メーターイベントで利用状況を報告する

顧客がメーターで計測される機能を使用した場合、アプリケーションはメーターイベントを作成してPaymentKitに報告する必要があります。このイベントは、作成したメーターのevent_nameと一致する必要があります。

ネットワークの問題やリトライによる重複した使用状況の報告を防ぐため、各イベントには常に一意のidentifierを含めてください。PaymentKitは、特定の識別子で受信した最初のイベントのみを処理します。

利用イベントを報告

javascript
import payment from '@blocklet/payment-js';

async function reportApiCall(customerId, subscriptionId) {
  try {
    const meterEvent = await payment.meterEvents.create({
      event_name: 'api.calls.v1', // メーターのevent_nameと一致する必要があります
      payload: {
        customer_id: customerId, // 'cus_xxx'
        value: '10', // 報告する使用量
        subscription_id: subscriptionId, // オプション：サブスクリプションに関連付ける
      },
      identifier: `unique_api_call_${Date.now()}` // べき等キー
    });
    console.log('メーターイベントが報告されました：', meterEvent.id);
    return meterEvent;
  } catch (error) {
    console.error('メーターイベント報告エラー：', error.message);
  }
}

// reportApiCall('cus_xxx', 'sub_xxx');

このイベントが処理されると、PaymentKitは自動的に顧客のアクティブなクレジット付与を見つけ、残高から10クレジットを差し引きます。

ステップ4：クレジット残高を確認する

summaryメソッドを使用して、いつでも顧客のクレジット残高を確認できます。これは、アプリケーションのUIに残高を表示するのに便利です。

クレジットサマリーを確認

javascript
import payment from '@blocklet/payment-js';

async function checkCreditBalance(customerId) {
  try {
    const creditSummary = await payment.creditGrants.summary({
      customer_id: customerId, // 'cus_xxx'
    });
    console.log('クレジットサマリー：', creditSummary);
    return creditSummary;
  } catch (error) {
    console.error('クレジットサマリー取得エラー：', error.message);
  }
}

// checkCreditBalance('cus_xxx');

レスポンス例

json
{
  "pc_xxx": { // currency_id
    "paymentCurrency": {
      "id": "pc_xxx",
      "name": "Credit",
      "symbol": "C",
      "decimal": 2,
      "type": "credit"
    },
    "totalAmount": "1000.00",
    "remainingAmount": "990.00",
    "grantCount": 1
  }
}

レスポンスは通貨ごとにグループ化されており、指定された顧客に対して付与されたクレジットの合計と残量を示します。

ステップ5：取引履歴を表示する

顧客のすべてのクレジット活動（付与、消費、失効を含む）の詳細な監査ログを確認するには、クレジットトランザクションをリストアップします。

クレジットトランザクションを一覧表示

javascript
import payment from '@blocklet/payment-js';

async function getTransactionHistory(customerId) {
  try {
    const transactions = await payment.creditTransactions.list({
      customer_id: customerId, // 'cus_xxx'
      pageSize: 10
    });
    console.log(`トランザクションが${transactions.total}件見つかりました。`);
    transactions.data.forEach(tx => {
      console.log(`- ID: ${tx.id}, タイプ: ${tx.type}, 金額: ${tx.amount}, 残高: ${tx.running_balance}`);
    });
    return transactions;
  } catch (error) {
    console.error('クレジットトランザクション一覧表示エラー：', error.message);
  }
}

// getTransactionHistory('cus_xxx');

これにより、完全な履歴が提供され、顧客のクレジット残高のすべての変更を追跡できます。

次のステップ

これで、クレジットベースの請求ワークフローの全体像を把握できました。各コンポーネントに関するすべての利用可能なパラメーターやメソッドを含む詳細情報については、APIリファレンスドキュメントを参照してください。

メーターAPIリファレンス

メーターの作成と管理に関するすべてのメソッドを調べます。

メーターイベントAPIリファレンス

使用状況の報告と統計の取得について詳しく学びます。

クレジット付与APIリファレンス

クレジットの付与と残高の管理方法を確認します。

クレジットトランザクションAPIリファレンス

取引履歴の取得に関する詳細情報を入手します。

顧客がクレジットを購入したり、自動リチャージを設定する方法については、クレジットのトップアップガイドを参照してください。