跳到主要內容

支付貨幣

支付貨幣 API 可讓您管理接受支付的貨幣。這包括標準的區塊鏈代幣(如 ERC-20 或 ArcBlock 原生代幣)以及用於實現基於點數計費系統的自訂點數貨幣。

每種支付貨幣都連結到一個特定的支付方式,該方式定義了底層網路或系統(例如,以太坊、ArcBlock)。

支付貨幣物件

PaymentCurrency 物件包含可用於交易的貨幣的所有詳細資訊。

AttributeTypeDescription
idstring支付貨幣物件的唯一識別碼。
namestring貨幣的全名(例如,「Ethereum Tether」)。
descriptionstring貨幣的簡要描述。
logostring代表貨幣的圖片 URL。
symbolstring貨幣的簡短、可識別的符號(例如,「USDT」)。
decimalnumber貨幣擁有的小數位數。
contractstring代幣類型貨幣的合約地址。
typestring貨幣的類型。可以是 standard(用於常規代幣)或 credit(用於自訂點數系統)。
activeboolean此貨幣目前是否可用。
livemodeboolean如果貨幣處於正式模式,則為 true;如果是測試模式,則為 false
is_base_currencyboolean表示這是否為原生鏈代幣。
payment_method_idstring關聯的 PaymentMethod 的 ID。
recharge_configobject對於點數貨幣,此物件包含儲值點數餘額的設定。詳情請參閱 getRechargeConfig 方法。
metadataobject一組您可以附加到物件上的鍵值對。

建立支付貨幣

建立一個新的支付貨幣。這通常用於在支援的區塊鏈上增加對新的 ERC-20 代幣或類似資產的支援。

參數

NameTypeDescription
namestring必填。 貨幣名稱。最多 32 個字元。
descriptionstring必填。 貨幣描述。最多 255 個字元。
payment_method_idstring必填。 此貨幣所屬的支付方式 ID(例如,一個以太坊支付方式)。
contractstring必填。 代幣的合約地址。系統將在相應的網路上驗證此合約。
logostring選填。 貨幣標誌的 URL。如果未提供,將使用支付方式的標誌。

返回

返回新建立的 PaymentCurrency 物件。

Create a new payment currency

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

async function createCurrency() {
  try {
    const newCurrency = await payment.paymentCurrencies.create({
      name: 'My Custom Token',
      description: 'An ERC-20 token for our platform',
      payment_method_id: 'pm_xxxxxxxxxxxxxx', // ID of an EVM-based payment method
      contract: '0x..._token_contract_address',
      logo: 'https://example.com/token_logo.png',
    });
    console.log('Payment Currency created:', newCurrency);
  } catch (error) {
    console.error('Error creating payment currency:', error.message);
  }
}

createCurrency();

Response Example

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An ERC-20 token for our platform",
  "contract": "0x..._token_contract_address",
  "logo": "https://example.com/token_logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

檢索支付貨幣

根據其唯一 ID 或符號檢索現有支付貨幣的詳細資訊。

參數

NameTypeDescription
idstring必填。 要檢索的支付貨幣的唯一識別碼(curr_...)或符號(例如,USDT)。

返回

如果找到,則返回對應的 PaymentCurrency 物件,否則返回 404 錯誤。

Retrieve a payment currency

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

async function getCurrency(currencyId) {
  try {
    const currency = await payment.paymentCurrencies.retrieve(currencyId);
    console.log('Retrieved Currency:', currency);
  } catch (error) {
    console.error('Error retrieving currency:', error.message);
  }
}

// Retrieve by ID
getCurrency('curr_xxxxxxxxxxxxxx');

// Or, retrieve by symbol
// getCurrency('USDT');

Response Example

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "livemode": false,
  "active": true,
  "name": "My Custom Token",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

更新支付貨幣

透過設定傳入參數的值來更新指定的支付貨幣。任何未提供的參數將保持不變。

參數

NameTypeDescription
idstring必填。 要更新的支付貨幣的 ID。
updateDataobject必填。 包含要更新欄位的物件。
updateData.namestring選填。 貨幣的新名稱。
updateData.descriptionstring選填。 貨幣的新描述。
updateData.logostring選填。 貨幣的新標誌 URL。
updateData.metadataobject選填。 一組與物件一起儲存的鍵值對。
updateData.symbolstring選填。 僅適用於 credit 類型的貨幣,更新其符號。

返回

返回更新後的 PaymentCurrency 物件。

Update a payment currency

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

async function updateCurrency(currencyId) {
  try {
    const updatedCurrency = await payment.paymentCurrencies.update(currencyId, {
      description: 'An updated description for my token.'
    });
    console.log('Currency updated:', updatedCurrency);
  } catch (error) {
    console.error('Error updating currency:', error.message);
  }
}

updateCurrency('curr_xxxxxxxxxxxxxx');

Response Example

json
{
  "id": "curr_xxxxxxxxxxxxxx",
  "name": "My Custom Token",
  "description": "An updated description for my token.",
  "symbol": "MCT",
  "decimal": 18,
  "updated_at": "2023-10-27T11:30:00.000Z"
}

列出支付貨幣

返回您的支付貨幣列表。貨幣按建立日期排序,最近建立的貨幣會最先出現。

參數

NameTypeDescription
filtersobject選填。 包含篩選條件的物件。
filters.activeboolean選填。 篩選列表,僅包含啟用或未啟用的貨幣。
filters.livemodeboolean選填。 根據環境(即時或測試)篩選列表。
filters.creditboolean選填。 如果為 true,除了 standard 類型的貨幣外,列表還將包含 credit 類型的貨幣。

返回

返回一個 PaymentCurrency 物件陣列。

List all active currencies

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

async function listCurrencies() {
  try {
    const currencies = await payment.paymentCurrencies.list({ active: true });
    console.log(`Found ${currencies.length} active currencies.`);
    currencies.forEach(c => console.log(`- ${c.name} (${c.symbol})`));
  } catch (error) {
    console.error('Error listing currencies:', error.message);
  }
}

listCurrencies();

Response Example

json
[
  {
    "id": "curr_xxxxxxxxxxxxxx",
    "name": "My Custom Token",
    "symbol": "MCT",
    "active": true
  },
  {
    "id": "curr_yyyyyyyyyyyyyy",
    "name": "Another Token",
    "symbol": "ATK",
    "active": true
  }
]

取得儲值設定

檢索 credit 類型貨幣的儲值設定。此設定定義了使用者如何購買或儲值該點數的餘額。

參數

NameTypeDescription
idstring必填。 點數貨幣的 ID (curr_...)。

返回

返回一個設定物件,其中包含有關如何儲值指定點數貨幣的詳細資訊。

NameTypeDescription
currency_idstring點數貨幣的 ID。
currency_infoobject關於點數貨幣的基本資訊(idnamesymboldecimaltype)。
recharge_configobject詳細說明儲值機制的物件。
recharge_config.base_price_idstring作為購買點數基礎的 Price 物件的 ID。
recharge_config.payment_urlstring用於購買點數的結帳頁面的直接 URL。
recharge_config.basePriceobjectbase_price_id 相關聯的完整 Price 物件,包括產品詳細資訊。
recharge_config.settingsobject用於儲值的額外設定。
recharge_config.settings.min_recharge_amountnumber單筆交易中最少可儲值的點數金額。
recharge_config.settings.max_recharge_amountnumber單筆交易中最多可儲值的點數金額。

Get credit recharge configuration

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

async function getRechargeConfig(creditCurrencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);
    console.log('Recharge Config:', config);
    if (config.recharge_config) {
      console.log(`Payment URL: ${config.recharge_config.payment_url}`);
    }
  } catch (error) {
    console.error('Error getting recharge config:', error.message);
  }
}

getRechargeConfig('curr_zzzzzzzzzzzzzz'); // ID of a credit currency

Response Example

json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "currency_info": {
    "id": "curr_zzzzzzzzzzzzzz",
    "name": "Platform Credits",
    "symbol": "PCC",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_xxxxxxxxxxxxxx",
    "payment_url": "https://your-app.arcblock.io/checkout/pay/pl_xxxxxxxxxxxxxx",
    "basePrice": {
      "id": "price_xxxxxxxxxxxxxx",
      "unit_amount": "1.00",
      // ... other price details
      "product": {
        "id": "prod_xxxxxxxxxxxxxx",
        "name": "Credit Top-up"
      }
    },
    "settings": {
      "min_recharge_amount": 10,
      "max_recharge_amount": 1000
    }
  }
}

更新儲值設定

更新 credit 類型貨幣的儲值設定。雖然這可以透過程式設計方式完成,但建議透過 PaymentKit 儀表板管理這些設定,以獲得更好的使用者體驗。

參數

NameTypeDescription
idstring必填。 要更新的點數貨幣的 ID。
configobject必填。 新的設定物件。
config.base_price_idstring必填。 定義每個點數成本的 Price 物件的 ID。該價格必須是啟用狀態。
config.payment_link_idstring選填。 用於儲值的預先設定的 PaymentLink 的 ID。
config.checkout_urlstring選填。 結帳頁面的自訂 URL。
config.settingsobject選填。 用於儲值限制的物件。
config.settings.min_recharge_amountnumber選填。 使用者一次可以購買的最少點數金額。
config.settings.max_recharge_amountnumber選填。 使用者一次可以購買的最多點數金額。

返回

返回一個確認儲值設定已成功更新的物件。

Update credit recharge configuration

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

async function updateRechargeConfig(creditCurrencyId) {
  try {
    const result = await payment.paymentCurrencies.updateRechargeConfig(creditCurrencyId, {
      base_price_id: 'price_yyyyyyyyyyyyyy', // A new price ID
      settings: {
        min_recharge_amount: 5
      }
    });
    console.log(result.message);
  } catch (error) {
    console.error('Error updating recharge config:', error.message);
  }
}

updateRechargeConfig('curr_zzzzzzzzzzzzzz');

Response Example

json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyyyyyyyy",
    "settings": {
      "min_recharge_amount": 5
    }
  },
  "message": "Recharge config updated successfully"
}