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

クレジットチャージ

PaymentKitのクレジットベースの課金システムでは、顧客はチャージによってクレジット残高を補充できます。クレジット通貨をチャージ可能に設定することで、手動による1回限りのチャージと、残高が設定したしきい値を下回った場合の自動リチャージの両方が可能になります。

このガイドでは、プログラムでクレジット通貨をチャージ用に設定するプロセスを説明します。顧客の実際の自動リチャージ設定（例：低残高のしきい値やリチャージ額）は、Payment Kitの課金ポータルを通じて顧客自身が直接管理するため、シームレスなユーザー体験が保証されます。

チャージのワークフロー概要

実装に入る前に、ユーザー視点でのチャージプロセス全体を理解しておくと役立ちます。クレジット通貨がリチャージ用に設定されると、チェックアウトリンクが生成されます。アプリケーションはユーザーをこのリンクにリダイレクトして支払いを完了させ、成功するとPaymentKitが自動的にクレジットを付与します。

Credit Top-Up

ステップ1：チャージパッケージを作成する

チャージパッケージは、顧客が受け取るクレジット数と支払額を定義する標準的なProductとPriceです。重要なのは、製品のメタデータにcredit_configオブジェクトを埋め込むことです。

まず、クレジットパックを表す製品を作成します。メタデータには、この製品がどのクレジット通貨を補充するのか、また購入時に付与されるクレジット額を指定する必要があります。

チャージパッケージ用の製品を作成する

javascript
const topUpProduct = await payment.products.create({
  name: '1000 Credits Pack',
  description: 'Top up your account with 1000 credits.',
  type: 'service',
  metadata: {
    // この製品は購入時にクレジットを付与します
    credit_config: {
      currency_id: 'pc_credit_xxxxxx', // あなたのクレジット通貨のID
      amount: '1000', // 付与するクレジットの額
    },
  },
});

次に、この製品に対して1回限りの価格を作成します。この価格によって、チャージのコストと支払い通貨（例：USDT、ETH）が決まります。

チャージパッケージ用の価格を作成する

javascript
const topUpPrice = await payment.prices.create({
  product_id: topUpProduct.id,
  type: 'one_time',
  unit_amount: '10', // 例：10 USDT
  currency_id: 'pc_usdt_xxxxxx', // クレジットの支払いに使用される通貨
});

ステップ2：クレジット通貨を設定する

チャージパッケージの価格を作成したら、それをクレジット通貨にリンクさせる必要があります。これはupdateRechargeConfigメソッドを使用して行います。このメソッドは、新しい価格をリチャージの基本パッケージとして指定します。

updateRechargeConfig(id, data)

このメソッドはbase_price_idをクレジット通貨に関連付け、チャージを有効にします。

パラメータ

名前タイプ説明
idstring必須。設定するクレジット通貨のID（例：pc_credit_xxxxxx）。
data.base_price_idstring必須。チャージパッケージとして機能するPriceオブジェクトのID。

例

リチャージ用にクレジット通貨を設定する

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

async function configureRecharge() {
  try {
    const creditCurrencyId = 'pc_credit_xxxxxx'; // あなたのクレジット通貨ID
    const topUpPriceId = 'price_yyyyyyyy'; // ステップ1で作成した価格ID

    const updatedCurrency = await payment.paymentCurrencies.updateRechargeConfig(
      creditCurrencyId,
      {
        base_price_id: topUpPriceId,
      }
    );

    console.log('リチャージ設定が更新されました：', updatedCurrency.recharge_config);
  } catch (error) {
    console.error('リチャージ設定エラー：', error.message);
  }
}

configureRecharge();

レスポンス例

json
{
  "currency_id": "pc_credit_xxxxxx",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyy"
  },
  "message": "リチャージ設定が正常に更新されました"
}

ステップ3：リチャージ設定を取得する

チャージを開始するには、アプリケーションでpayment_urlを取得する必要があります。getRechargeConfigメソッドを使用して、チェックアウトURLや基本価格の詳細を含む、完全なリチャージ設定を取得します。

getRechargeConfig(id)

指定されたクレジット通貨のリチャージ設定を取得します。

パラメータ

名前タイプ説明
idstring必須。クレジット通貨のID。

戻り値

通貨情報とそのrecharge_configを含むオブジェクトを返します。設定内のpayment_urlは、ユーザーをチェックアウトページに誘導するために使用するリンクです。

例

チャージURLを取得する

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

async function getTopUpLink(creditCurrencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);

    if (config.recharge_config && config.recharge_config.payment_url) {
      console.log('ユーザーをこのURLにリダイレクトします：', config.recharge_config.payment_url);
      return config.recharge_config.payment_url;
    } else {
      console.log('この通貨にはリチャージが設定されていません。');
      return null;
    }
  } catch (error) {
    console.error('リチャージ設定の取得エラー：', error.message);
  }
}

getTopUpLink('pc_credit_xxxxxx');

レスポンス例

json
{
  "currency_id": "pc_credit_xxxxxx",
  "currency_info": {
    "id": "pc_credit_xxxxxx",
    "name": "App Credits",
    "symbol": "CRD",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_yyyyyyyy",
    "basePrice": {
      "id": "price_yyyyyyyy",
      "unit_amount": "1000",
      "currency_id": "pc_usdt_xxxxxx",
      // ... other price details
      "product": {
        "id": "prod_zzzzzzzz",
        "name": "1000 Credits Pack",
        // ... other product details
      }
    },
    "payment_url": "https://payment.arcblock.io/checkout/pay/pl_xxxxxxxx"
  }
}

これらのステップを完了すると、クレジット通貨がチャージに完全に有効になります。アプリケーションは支払いURLを取得し、ユーザーがアカウントにクレジットを追加するためのシームレスな方法を提供できるようになります。クレジットシステムの詳細については、クレジットベースの課金ガイドを参照してください。