支付貨幣 API 可讓您管理接受支付的貨幣。這包括標準的區塊鏈代幣(如 ERC-20 或 ArcBlock 原生代幣)以及用於實現基於點數計費系統的自訂點數貨幣。
每種支付貨幣都連結到一個特定的支付方式,該方式定義了底層網路或系統(例如,以太坊、ArcBlock)。
支付貨幣物件
PaymentCurrency 物件包含可用於交易的貨幣的所有詳細資訊。
| Attribute | Type | Description |
|---|---|---|
id | string | 支付貨幣物件的唯一識別碼。 |
name | string | 貨幣的全名(例如,「Ethereum Tether」)。 |
description | string | 貨幣的簡要描述。 |
logo | string | 代表貨幣的圖片 URL。 |
symbol | string | 貨幣的簡短、可識別的符號(例如,「USDT」)。 |
decimal | number | 貨幣擁有的小數位數。 |
contract | string | 代幣類型貨幣的合約地址。 |
type | string | 貨幣的類型。可以是 standard(用於常規代幣)或 credit(用於自訂點數系統)。 |
active | boolean | 此貨幣目前是否可用。 |
livemode | boolean | 如果貨幣處於正式模式,則為 true;如果是測試模式,則為 false。 |
is_base_currency | boolean | 表示這是否為原生鏈代幣。 |
payment_method_id | string | 關聯的 PaymentMethod 的 ID。 |
recharge_config | object | 對於點數貨幣,此物件包含儲值點數餘額的設定。詳情請參閱 getRechargeConfig 方法。 |
metadata | object | 一組您可以附加到物件上的鍵值對。 |
建立支付貨幣
建立一個新的支付貨幣。這通常用於在支援的區塊鏈上增加對新的 ERC-20 代幣或類似資產的支援。
參數
| Name | Type | Description |
|---|---|---|
name | string | 必填。 貨幣名稱。最多 32 個字元。 |
description | string | 必填。 貨幣描述。最多 255 個字元。 |
payment_method_id | string | 必填。 此貨幣所屬的支付方式 ID(例如,一個以太坊支付方式)。 |
contract | string | 必填。 代幣的合約地址。系統將在相應的網路上驗證此合約。 |
logo | string | 選填。 貨幣標誌的 URL。如果未提供,將使用支付方式的標誌。 |
返回
返回新建立的 PaymentCurrency 物件。
Create a new payment currency
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
{
"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 或符號檢索現有支付貨幣的詳細資訊。
參數
| Name | Type | Description |
|---|---|---|
id | string | 必填。 要檢索的支付貨幣的唯一識別碼(curr_...)或符號(例如,USDT)。 |
返回
如果找到,則返回對應的 PaymentCurrency 物件,否則返回 404 錯誤。
Retrieve a payment currency
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
{
"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"
}更新支付貨幣
透過設定傳入參數的值來更新指定的支付貨幣。任何未提供的參數將保持不變。
參數
| Name | Type | Description |
|---|---|---|
id | string | 必填。 要更新的支付貨幣的 ID。 |
updateData | object | 必填。 包含要更新欄位的物件。 |
updateData.name | string | 選填。 貨幣的新名稱。 |
updateData.description | string | 選填。 貨幣的新描述。 |
updateData.logo | string | 選填。 貨幣的新標誌 URL。 |
updateData.metadata | object | 選填。 一組與物件一起儲存的鍵值對。 |
updateData.symbol | string | 選填。 僅適用於 credit 類型的貨幣,更新其符號。 |
返回
返回更新後的 PaymentCurrency 物件。
Update a payment currency
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
{
"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"
}列出支付貨幣
返回您的支付貨幣列表。貨幣按建立日期排序,最近建立的貨幣會最先出現。
參數
| Name | Type | Description |
|---|---|---|
filters | object | 選填。 包含篩選條件的物件。 |
filters.active | boolean | 選填。 篩選列表,僅包含啟用或未啟用的貨幣。 |
filters.livemode | boolean | 選填。 根據環境(即時或測試)篩選列表。 |
filters.credit | boolean | 選填。 如果為 true,除了 standard 類型的貨幣外,列表還將包含 credit 類型的貨幣。 |
返回
返回一個 PaymentCurrency 物件陣列。
List all active currencies
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
[
{
"id": "curr_xxxxxxxxxxxxxx",
"name": "My Custom Token",
"symbol": "MCT",
"active": true
},
{
"id": "curr_yyyyyyyyyyyyyy",
"name": "Another Token",
"symbol": "ATK",
"active": true
}
]取得儲值設定
檢索 credit 類型貨幣的儲值設定。此設定定義了使用者如何購買或儲值該點數的餘額。
參數
| Name | Type | Description |
|---|---|---|
id | string | 必填。 點數貨幣的 ID (curr_...)。 |
返回
返回一個設定物件,其中包含有關如何儲值指定點數貨幣的詳細資訊。
| Name | Type | Description |
|---|---|---|
currency_id | string | 點數貨幣的 ID。 |
currency_info | object | 關於點數貨幣的基本資訊(id、name、symbol、decimal、type)。 |
recharge_config | object | 詳細說明儲值機制的物件。 |
recharge_config.base_price_id | string | 作為購買點數基礎的 Price 物件的 ID。 |
recharge_config.payment_url | string | 用於購買點數的結帳頁面的直接 URL。 |
recharge_config.basePrice | object | 與 base_price_id 相關聯的完整 Price 物件,包括產品詳細資訊。 |
recharge_config.settings | object | 用於儲值的額外設定。 |
recharge_config.settings.min_recharge_amount | number | 單筆交易中最少可儲值的點數金額。 |
recharge_config.settings.max_recharge_amount | number | 單筆交易中最多可儲值的點數金額。 |
Get credit recharge configuration
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 currencyResponse Example
{
"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 儀表板管理這些設定,以獲得更好的使用者體驗。
參數
| Name | Type | Description |
|---|---|---|
id | string | 必填。 要更新的點數貨幣的 ID。 |
config | object | 必填。 新的設定物件。 |
config.base_price_id | string | 必填。 定義每個點數成本的 Price 物件的 ID。該價格必須是啟用狀態。 |
config.payment_link_id | string | 選填。 用於儲值的預先設定的 PaymentLink 的 ID。 |
config.checkout_url | string | 選填。 結帳頁面的自訂 URL。 |
config.settings | object | 選填。 用於儲值限制的物件。 |
config.settings.min_recharge_amount | number | 選填。 使用者一次可以購買的最少點數金額。 |
config.settings.max_recharge_amount | number | 選填。 使用者一次可以購買的最多點數金額。 |
返回
返回一個確認儲值設定已成功更新的物件。
Update credit recharge configuration
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
{
"currency_id": "curr_zzzzzzzzzzzzzz",
"recharge_config": {
"base_price_id": "price_yyyyyyyyyyyyyy",
"settings": {
"min_recharge_amount": 5
}
},
"message": "Recharge config updated successfully"
}