支付货币


支付货币 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 对象。

创建一个新的支付货币

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

id

string

必需。 要检索的支付货币的唯一标识符(curr_...)或符号(例如,USDT)。

返回值#

如果找到,则返回相应的 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

string

必需。 要更新的支付货币的 ID。

updateData

object

必需。 包含要更新字段的对象。

updateData.name

string

可选。 货币的新名称。

updateData.description

string

可选。 货币的新描述。

updateData.logo

string

可选。 货币的新徽标 URL。

updateData.metadata

object

可选。 与对象一起存储的一组键值对。

updateData.symbol

string

可选。 仅适用于 credit 类型的货币,更新其符号。

返回值#

返回更新后的 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

filters

object

可选。 包含筛选条件的对象。

filters.active

boolean

可选。 筛选列表,仅包括活动或非活动的货币。

filters.livemode

boolean

可选。 根据环境(生产或测试)筛选列表。

filters.credit

boolean

可选。 如果为 true,列表将除了 standard 货币外,还包括 credit 类型的货币。

返回值#

返回一个 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

string

必需。 信用货币的 ID (curr_...)。

返回值#

返回一个配置对象,其中包含有关如何为指定的信用货币充值的详细信息。

Name

Type

Description

currency_id

string

信用货币的 ID。

currency_info

object

关于信用货币的基本信息(idnamesymboldecimaltype)。

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

单次交易可充值的最大信用额度。

获取信用充值配置

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

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

可选。 用户一次可以购买的最大信用额度。

返回值#

返回一个对象,确认充值配置已成功更新。

更新信用充值配置

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": "充值配置更新成功"
}