跳到主要内容

支付货币

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

创建一个新的支付货币

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('支付货币已创建:', newCurrency);
  } catch (error) {
    console.error('创建支付货币时出错:', error.message);
  }
}

createCurrency();

响应示例

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 错误。

检索支付货币

javascript
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');

响应示例

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 对象。

更新支付货币

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('货币已更新:', updatedCurrency);
  } catch (error) {
    console.error('更新货币时出错:', error.message);
  }
}

updateCurrency('curr_xxxxxxxxxxxxxx');

响应示例

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 对象数组。

列出所有活动货币

javascript
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();

响应示例

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单次交易可充值的最大信用额度。

获取信用充值配置

javascript
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

响应示例

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可选。 用户一次可以购买的最大信用额度。

返回值

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

更新信用充值配置

javascript
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');

响应示例

json
{
  "currency_id": "curr_zzzzzzzzzzzzzz",
  "recharge_config": {
    "base_price_id": "price_yyyyyyyyyyyyyy",
    "settings": {
      "min_recharge_amount": 5
    }
  },
  "message": "充值配置更新成功"
}