跳到主要內容

點數儲值

PaymentKit 的點數計費系統允許客戶透過儲值來補充其點數餘額。您可以將點數貨幣設定為可儲值，從而啟用手動單次儲值和餘額低於設定閾值時的自動儲值。

本指南將引導您以程式化方式設定點數貨幣以進行儲值。客戶的實際自動儲值設定（例如，低餘額閾值和儲值金額）由客戶直接透過 Payment Kit 計費入口網站管理，以確保無縫的使用者體驗。

儲值工作流程概覽

在深入實作之前，從使用者的角度了解整個儲值流程會很有幫助。當點數貨幣設定為可儲值時，會產生一個結帳連結。您的應用程式會將使用者重新導向到此連結以完成付款，PaymentKit 會在成功後自動處理點數的授予。

Credit Top-Up

步驟 1：建立儲值包

儲值包是一個標準的 Product 和 Price，它定義了客戶收到的點數數量以及他們支付的金額。關鍵是在產品的元資料中嵌入一個 credit_config 物件。

首先，建立一個代表點數包的產品。元資料應指定此產品補充的點數貨幣以及購買後授予的點數數量。

為儲值包建立產品

javascript
const topUpProduct = await payment.products.create({
  name: '1000 點數包',
  description: '為您的帳戶儲值 1000 點數。',
  type: 'service',
  metadata: {
    // 購買此產品時授予點數
    credit_config: {
      currency_id: 'pc_credit_xxxxxx', // 您的點數貨幣 ID
      amount: '1000', // 要授予的點數數量
    },
  },
});

接下來，為此產品建立一個一次性價格。此價格將決定儲值的成本和支付貨幣（例如，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 與點數貨幣關聯，使其可用於儲值。

參數

NameTypeDescription
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)

擷取指定點數貨幣的儲值設定。

參數

NameTypeDescription
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": "應用程式點數",
    "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 點數包",
        // ... other product details
      }
    },
    "payment_url": "https://payment.arcblock.io/checkout/pay/pl_xxxxxxxx"
  }
}

完成這些步驟後，您的點數貨幣現在已完全啟用儲值功能。您的應用程式可以擷取付款 URL，並為使用者提供一種無縫的方式來為其帳戶增加更多點數。有關更廣泛的點數系統的更多詳細資訊，請參閱 基於點數的計費 指南。