支付货币
支付货币 API 允许您管理可接受支付的货币。这包括标准的基于区块链的代币(如 ERC-20 或 ArcBlock 原生代币),以及用于实现基于信用的计费系统的自定义信用货币。
每种支付货币都与一个特定的支付方式相关联,该支付方式定义了其底层网络或系统(例如,以太坊、ArcBlock)。
支付货币对象#
PaymentCurrency 对象包含可用于交易的货币的所有详细信息。
Attribute | Type | Description |
|---|---|---|
|
| 支付货币对象的唯一标识符。 |
|
| 货币的全名(例如,“Ethereum Tether”)。 |
|
| 货币的简要描述。 |
|
| 代表该货币的图像 URL。 |
|
| 货币的简短、可识别的符号(例如,“USDT”)。 |
|
| 货币拥有的小数位数。 |
|
| 基于代币的货币的合约地址。 |
|
| 货币类型。可以是用于常规代币的 |
|
| 此货币当前是否可用。 |
|
| 如果货币处于生产模式,则为 |
|
| 指示这是否是原生链代币。 |
|
| 关联的 |
|
| 对于信用货币,此对象包含用于充值信用余额的配置。有关详细信息,请参见 |
|
| 您可以附加到对象的一组键值对。 |
创建支付货币#
创建一个新的支付货币。这通常用于在受支持的区块链上为新的 ERC-20 代币或类似资产添加支持。
参数#
Name | Type | Description |
|---|---|---|
|
| 必需。 货币的名称。最多 32 个字符。 |
|
| 必需。 货币的描述。最多 255 个字符。 |
|
| 必需。 此货币所属的支付方式的 ID(例如,一个以太坊支付方式)。 |
|
| 必需。 代币的合约地址。系统将在相应网络上验证此合约。 |
|
| 可选。 货币徽标的 URL。如果未提供,将使用支付方式的徽标。 |
返回值#
返回新创建的 PaymentCurrency 对象。
创建一个新的支付货币
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('支付货币已创建:', newCurrency);
} catch (error) {
console.error('创建支付货币时出错:', error.message);
}
}
createCurrency();响应示例
{
"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 |
|---|---|---|
|
| 必需。 要检索的支付货币的唯一标识符( |
返回值#
如果找到,则返回相应的 PaymentCurrency 对象;否则,返回 404 错误。
检索支付货币
import payment from '@blocklet/payment-js';
async function getCurrency(currencyId) {
try {
const currency = await payment.paymentCurrencies.retrieve(currencyId);
console.log('检索到的货币:', currency);
} catch (error) {
console.error('检索货币时出错:', error.message);
}
}
// 通过 ID 检索
getCurrency('curr_xxxxxxxxxxxxxx');
// 或者,通过符号检索
// getCurrency('USDT');响应示例
{
"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。 |
|
| 必需。 包含要更新字段的对象。 |
|
| 可选。 货币的新名称。 |
|
| 可选。 货币的新描述。 |
|
| 可选。 货币的新徽标 URL。 |
|
| 可选。 与对象一起存储的一组键值对。 |
|
| 可选。 仅适用于 |
返回值#
返回更新后的 PaymentCurrency 对象。
更新支付货币
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('货币已更新:', updatedCurrency);
} catch (error) {
console.error('更新货币时出错:', error.message);
}
}
updateCurrency('curr_xxxxxxxxxxxxxx');响应示例
{
"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 |
|---|---|---|
|
| 可选。 包含筛选条件的对象。 |
|
| 可选。 筛选列表,仅包括活动或非活动的货币。 |
|
| 可选。 根据环境(生产或测试)筛选列表。 |
|
| 可选。 如果为 |
返回值#
返回一个 PaymentCurrency 对象数组。
列出所有活动货币
import payment from '@blocklet/payment-js';
async function listCurrencies() {
try {
const currencies = await payment.paymentCurrencies.list({ active: true });
console.log(`找到 ${currencies.length} 个活动货币。`);
currencies.forEach(c => console.log(`- ${c.name} (${c.symbol})`));
} catch (error) {
console.error('列出货币时出错:', error.message);
}
}
listCurrencies();响应示例
[
{
"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 ( |
返回值#
返回一个配置对象,其中包含有关如何为指定的信用货币充值的详细信息。
Name | Type | Description |
|---|---|---|
|
| 信用货币的 ID。 |
|
| 关于信用货币的基本信息( |
|
| 详细说明充值机制的对象。 |
|
| 作为购买信用基础的 |
|
| 用于购买信用的结账页面的直接 URL。 |
|
| 与 |
|
| 用于充值的附加设置。 |
|
| 单次交易可充值的最小信用额度。 |
|
| 单次交易可充值的最大信用额度。 |
获取信用充值配置
import payment from '@blocklet/payment-js';
async function getRechargeConfig(creditCurrencyId) {
try {
const config = await payment.paymentCurrencies.getRechargeConfig(creditCurrencyId);
console.log('充值配置:', config);
if (config.recharge_config) {
console.log(`支付 URL: ${config.recharge_config.payment_url}`);
}
} catch (error) {
console.error('获取充值配置时出错:', error.message);
}
}
getRechargeConfig('curr_zzzzzzzzzzzzzz'); // 信用货币的 ID响应示例
{
"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
}See all 2 lines
更新充值配置#
更新 credit 类型货币的充值配置。虽然这可以通过编程方式完成,但为了更好的用户体验,建议通过 PaymentKit 仪表板管理这些设置。
参数#
Name | Type | Description |
|---|---|---|
|
| 必需。 要更新的信用货币的 ID。 |
|
| 必需。 新的配置对象。 |
|
| 必需。 定义每个信用成本的 |
|
| 可选。 用于充值的预配置 |
|
| 可选。 结账页面的自定义 URL。 |
|
| 可选。 用于充值限制的对象。 |
|
| 可选。 用户一次可以购买的最小信用额度。 |
|
| 可选。 用户一次可以购买的最大信用额度。 |
返回值#
返回一个对象,确认充值配置已成功更新。
更新信用充值配置
import payment from '@blocklet/payment-js';
async function updateRechargeConfig(creditCurrencyId) {
try {
const result = await payment.paymentCurrencies.updateRechargeConfig(creditCurrencyId, {
base_price_id: 'price_yyyyyyyyyyyyyy', // 一个新的价格 ID
settings: {
min_recharge_amount: 5
}
});
console.log(result.message);
} catch (error) {
console.error('更新充值配置时出错:', error.message);
}
}
updateRechargeConfig('curr_zzzzzzzzzzzzzz');响应示例
{
"currency_id": "curr_zzzzzzzzzzzzzz",
"recharge_config": {
"base_price_id": "price_yyyyyyyyyyyyyy",
"settings": {
"min_recharge_amount": 5
}
},
"message": "充值配置更新成功"
}