Payment Currencies

The Payment Currencies API allows you to manage the currencies accepted for payments. This includes standard blockchain-based tokens (like ERC-20 or ArcBlock native tokens) as well as custom credit currencies used for implementing credit-based billing systems.

Each payment currency is linked to a specific Payment Method, which defines the underlying network or system (e.g., Ethereum, ArcBlock).

The Payment Currency Object#

A PaymentCurrency object contains all the details about a currency available for transactions.

Attribute	Type	Description
id	string	Unique identifier for the payment currency object.
name	string	The full name of the currency (e.g., "Ethereum Tether").
description	string	A brief description of the currency.
logo	string	URL of an image representing the currency.
symbol	string	A short, recognizable symbol for the currency (e.g., "USDT").
decimal	number	The number of decimal places the currency has.
contract	string	The contract address for token-based currencies.
type	string	The type of currency. Can be standard for regular tokens or credit for custom credit systems.
active	boolean	Whether this currency is currently available for use.
livemode	boolean	true if the currency is in live mode, false for test mode.
is_base_currency	boolean	Indicates if this is a native chain token.
payment_method_id	string	The ID of the associated PaymentMethod.
recharge_config	object	For credit currencies, this object contains the configuration for topping up credit balances. See the getRechargeConfig method for details.
metadata	object	A set of key-value pairs that you can attach to an object.

Create a Payment Currency#

Creates a new payment currency. This is typically used to add support for a new ERC-20 token or a similar asset on a supported blockchain.

Parameters#

Name	Type	Description
name	string	Required. The name of the currency. Maximum 32 characters.
description	string	Required. A description for the currency. Maximum 255 characters.
payment_method_id	string	Required. The ID of the payment method this currency belongs to (e.g., an Ethereum payment method).
contract	string	Required. The contract address of the token. The system will verify this contract on the corresponding network.
logo	string	Optional. A URL for the currency's logo. If not provided, the logo of the payment method will be used.

Returns#

Returns the newly created PaymentCurrency object.

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

{
  "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"
}

Retrieve a Payment Currency#

Retrieves the details of an existing payment currency by its unique ID or symbol.

Parameters#

Name	Type	Description
id	string	Required. The unique identifier (curr_...) or the symbol (e.g., USDT) of the payment currency to retrieve.

Returns#

Returns the corresponding PaymentCurrency object if found, otherwise returns a 404 error.

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

{
  "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"
}

Update a Payment Currency#

Updates the specified payment currency by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters#

Name	Type	Description
id	string	Required. The ID of the payment currency to update.
updateData	object	Required. An object containing the fields to update.
updateData.name	string	Optional. A new name for the currency.
updateData.description	string	Optional. A new description for the currency.
updateData.logo	string	Optional. A new logo URL for the currency.
updateData.metadata	object	Optional. A set of key-value pairs to store with the object.
updateData.symbol	string	Optional. For credit type currencies only, updates the symbol.

Returns#

Returns the updated PaymentCurrency object.

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

{
  "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"
}

List Payment Currencies#

Returns a list of your payment currencies. The currencies are returned sorted by creation date, with the most recently created currencies appearing first.

Parameters#

Name	Type	Description
filters	object	Optional. An object containing filter criteria.
filters.active	boolean	Optional. Filters the list to only include active or inactive currencies.
filters.livemode	boolean	Optional. Filters the list based on the environment (live or test).
filters.credit	boolean	Optional. If true, the list will include currencies of type credit in addition to standard currencies.

Returns#

Returns an array of PaymentCurrency objects.

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

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

Get Recharge Configuration#

Retrieves the recharge configuration for a credit type currency. This configuration defines how users can purchase or top up their balance for that credit.

Parameters#

Name	Type	Description
id	string	Required. The ID of the credit currency (curr_...).

Returns#

Returns a configuration object with details about how to recharge the specified credit currency.

Name	Type	Description
currency_id	string	The ID of the credit currency.
currency_info	object	Basic information about the credit currency (id, name, symbol, decimal, type).
recharge_config	object	An object detailing the recharge mechanism.
recharge_config.base_price_id	string	The ID of the Price object that serves as the base for purchasing credits.
recharge_config.payment_url	string	A direct URL to a checkout page for purchasing credits.
recharge_config.basePrice	object	The full Price object associated with base_price_id, including product details.
recharge_config.settings	object	Additional settings for recharging.
recharge_config.settings.min_recharge_amount	number	The minimum amount of credit that can be recharged in a single transaction.
recharge_config.settings.max_recharge_amount	number	The maximum amount of credit that can be recharged in a single transaction.

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

{
  "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
    }

Update Recharge Configuration#

Updates the recharge configuration for a credit type currency. While this can be done programmatically, it is recommended to manage these settings through the PaymentKit dashboard for a better user experience.

Parameters#

Name	Type	Description
id	string	Required. The ID of the credit currency to update.
config	object	Required. The new configuration object.
config.base_price_id	string	Required. The ID of a Price object that defines the cost per credit. The price must be active.
config.payment_link_id	string	Optional. The ID of a pre-configured PaymentLink to use for recharge.
config.checkout_url	string	Optional. A custom URL for the checkout page.
config.settings	object	Optional. An object for recharge limits.
config.settings.min_recharge_amount	number	Optional. The minimum amount of credits a user can purchase at one time.
config.settings.max_recharge_amount	number	Optional. The maximum amount of credits a user can purchase at one time.

Returns#

Returns an object confirming that the recharge configuration has been updated successfully.

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

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