Skip to main content

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.

AttributeTypeDescription
idstringUnique identifier for the payment currency object.
namestringThe full name of the currency (e.g., "Ethereum Tether").
descriptionstringA brief description of the currency.
logostringURL of an image representing the currency.
symbolstringA short, recognizable symbol for the currency (e.g., "USDT").
decimalnumberThe number of decimal places the currency has.
contractstringThe contract address for token-based currencies.
typestringThe type of currency. Can be standard for regular tokens or credit for custom credit systems.
activebooleanWhether this currency is currently available for use.
livemodebooleantrue if the currency is in live mode, false for test mode.
is_base_currencybooleanIndicates if this is a native chain token.
payment_method_idstringThe ID of the associated PaymentMethod.
recharge_configobjectFor credit currencies, this object contains the configuration for topping up credit balances. See the getRechargeConfig method for details.
metadataobjectA 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

NameTypeDescription
namestringRequired. The name of the currency. Maximum 32 characters.
descriptionstringRequired. A description for the currency. Maximum 255 characters.
payment_method_idstringRequired. The ID of the payment method this currency belongs to (e.g., an Ethereum payment method).
contractstringRequired. The contract address of the token. The system will verify this contract on the corresponding network.
logostringOptional. 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.

Create a new payment currency

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('Payment Currency created:', newCurrency);
  } catch (error) {
    console.error('Error creating payment currency:', error.message);
  }
}

createCurrency();

Response Example

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

Retrieve a Payment Currency

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

Parameters

NameTypeDescription
idstringRequired. 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.

Retrieve a payment currency

javascript
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

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

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

NameTypeDescription
idstringRequired. The ID of the payment currency to update.
updateDataobjectRequired. An object containing the fields to update.
updateData.namestringOptional. A new name for the currency.
updateData.descriptionstringOptional. A new description for the currency.
updateData.logostringOptional. A new logo URL for the currency.
updateData.metadataobjectOptional. A set of key-value pairs to store with the object.
updateData.symbolstringOptional. For credit type currencies only, updates the symbol.

Returns

Returns the updated PaymentCurrency object.

Update a payment currency

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('Currency updated:', updatedCurrency);
  } catch (error) {
    console.error('Error updating currency:', error.message);
  }
}

updateCurrency('curr_xxxxxxxxxxxxxx');

Response Example

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

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

NameTypeDescription
filtersobjectOptional. An object containing filter criteria.
filters.activebooleanOptional. Filters the list to only include active or inactive currencies.
filters.livemodebooleanOptional. Filters the list based on the environment (live or test).
filters.creditbooleanOptional. If true, the list will include currencies of type credit in addition to standard currencies.

Returns

Returns an array of PaymentCurrency objects.

List all active currencies

javascript
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

json
[
  {
    "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

NameTypeDescription
idstringRequired. The ID of the credit currency (curr_...).

Returns

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

NameTypeDescription
currency_idstringThe ID of the credit currency.
currency_infoobjectBasic information about the credit currency (id, name, symbol, decimal, type).
recharge_configobjectAn object detailing the recharge mechanism.
recharge_config.base_price_idstringThe ID of the Price object that serves as the base for purchasing credits.
recharge_config.payment_urlstringA direct URL to a checkout page for purchasing credits.
recharge_config.basePriceobjectThe full Price object associated with base_price_id, including product details.
recharge_config.settingsobjectAdditional settings for recharging.
recharge_config.settings.min_recharge_amountnumberThe minimum amount of credit that can be recharged in a single transaction.
recharge_config.settings.max_recharge_amountnumberThe maximum amount of credit that can be recharged in a single transaction.

Get credit recharge configuration

javascript
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

Response Example

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

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

NameTypeDescription
idstringRequired. The ID of the credit currency to update.
configobjectRequired. The new configuration object.
config.base_price_idstringRequired. The ID of a Price object that defines the cost per credit. The price must be active.
config.payment_link_idstringOptional. The ID of a pre-configured PaymentLink to use for recharge.
config.checkout_urlstringOptional. A custom URL for the checkout page.
config.settingsobjectOptional. An object for recharge limits.
config.settings.min_recharge_amountnumberOptional. The minimum amount of credits a user can purchase at one time.
config.settings.max_recharge_amountnumberOptional. 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.

Update credit recharge configuration

javascript
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

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