API Reference

Payment Currencies

Payment Currency objects represent the different currencies your application can accept for payments. These are typically tied to a specific PaymentMethod, such as an ERC-20 token on an EVM-compatible chain or a native token on the ArcBlock platform. They also define configurations for credit-based billing systems.
This document details how to create, retrieve, update, list, and manage payment currencies, including their recharge configurations, using the SDK.
The Payment Currency Object#A TPaymentCurrency object contains the following properties:
Attribute
Type
Description
id
string
Unique identifier for the payment currency.
livemode
boolean
true if the currency is for live mode, false for test mode. Inherited from the parent PaymentMethod.
active
boolean
Whether this currency is active and can be used for payments. Inherited from the parent PaymentMethod.
locked
boolean
true if the currency is locked and cannot be deleted.
is_base_currency
boolean
true if this is a native/base currency of a blockchain (e.g., ETH, ABT).
payment_method_id
string
The ID of the PaymentMethod this currency belongs to.
name
string
The name of the currency (e.g., "Tether USD").
description
string
A description of the currency.
contract
string
The contract address for token-based currencies.
logo
string
URL of the currency's logo.
symbol
string
The currency's symbol (e.g., "USDT").
decimal
number
The number of decimal places the currency supports.
type
string
The type of currency. Can be standard or credit.
minimum_payment_amount
string
The minimum amount for a single payment, in the smallest unit of the currency.
maximum_payment_amount
string
The maximum amount for a single payment, in the smallest unit of the currency.
metadata
object
A set of key-value pairs that you can attach to an object.
recharge_config
object
Configuration for credit top-ups. See the updateRechargeConfig method for details.
vault_config
object
Configuration for the automated deposit and withdrawal vault.
Create a Payment Currency#Adds a new payment currency, typically a token, to an existing payment method.
POST /api/payment-currencies
Parameters
Name
Type
Description
name
string
Required. The name of the currency.
description
string
Required. A description for the currency.
payment_method_id
string
Required. The ID of the PaymentMethod to associate this currency with.
contract
string
Required. The token's contract address.
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 TPaymentCurrency object.
Example
import payment from '@blocklet/payment-js';

async function createCurrency() {
  try {
    const newCurrency = await payment.paymentCurrencies.create({
      payment_method_id: 'pm_12345',
      name: 'My Custom Token',
      description: 'A custom ERC20 token for payments.',
      contract: '0x1234567890abcdef1234567890abcdef12345678',
    });
    console.log('Currency created:', newCurrency);
  } catch (error) {
    console.error('Error creating currency:', error.message);
  }
}

createCurrency();Example Response
{
  "id": "pc_5a7b3c9d2e1f",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_12345",
  "name": "My Custom Token",
  "description": "A custom ERC20 token for payments.",
  "contract": "0x1234567890abcdef1234567890abcdef12345678",
  "logo": "https://example.com/default-logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "minimum_payment_amount": "1000000000000",
  "maximum_payment_amount": "100000000000000000000000000000",
  "metadata": {}
}Retrieve a Payment Currency#Fetches the details of a specific payment currency by its ID or symbol.
GET /api/payment-currencies/{id}
Parameters
Name
Type
Description
id
string
Required. The unique identifier or symbol of the currency to retrieve.
Returns
Returns the TPaymentCurrency object if found, otherwise returns a 404 error.
Example
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);
  }
}

getCurrency('pc_5a7b3c9d2e1f');Example Response
{
  "id": "pc_5a7b3c9d2e1f",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_12345",
  "name": "My Custom Token",
  "description": "A custom ERC20 token for payments.",
  "contract": "0x1234567890abcdef1234567890abcdef12345678",
  "logo": "https://example.com/default-logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "minimum_payment_amount": "1000000000000",
  "maximum_payment_amount": "100000000000000000000000000000",
  "metadata": {}
}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.
PUT /api/payment-currencies/{id}
Parameters
Name
Type
Description
id
string
Required. The ID of the currency to update.
name
string
Optional. The new name for the currency.
description
string
Optional. The new description for the currency.
logo
string
Optional. The new logo URL for the currency.
metadata
object
Optional. A set of key-value pairs to store with the object.
symbol
string
Optional. The new symbol. Can only be updated if type is credit.
Returns
Returns the updated TPaymentCurrency object.
Example
import payment from '@blocklet/payment-js';

async function updateCurrency(currencyId) {
  try {
    const updatedCurrency = await payment.paymentCurrencies.update(currencyId, {
      description: 'An updated description for my custom token.',
      metadata: { order_id: '6735' }
    });
    console.log('Currency updated:', updatedCurrency);
  } catch (error) {
    console.error('Error updating currency:', error.message);
  }
}

updateCurrency('pc_5a7b3c9d2e1f');Example Response
{
  "id": "pc_5a7b3c9d2e1f",
  "livemode": false,
  "active": true,
  "locked": false,
  "is_base_currency": false,
  "payment_method_id": "pm_12345",
  "name": "My Custom Token",
  "description": "An updated description for my custom token.",
  "contract": "0x1234567890abcdef1234567890abcdef12345678",
  "logo": "https://example.com/default-logo.png",
  "symbol": "MCT",
  "decimal": 18,
  "type": "standard",
  "minimum_payment_amount": "1000000000000",
  "maximum_payment_amount": "100000000000000000000000000000",
  "metadata": { "order_id": "6735" }
}List Payment Currencies#Returns a list of your payment currencies.
GET /api/payment-currencies
Parameters
Name
Type
Description
active
boolean
Optional. Filters the list to only include active or inactive currencies.
livemode
boolean
Optional. Filters the list based on the currency's mode (live or test).
credit
boolean
Optional. If true, the list will include currencies of type credit in addition to standard.
Returns
An array of TPaymentCurrency objects.
Example
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();Example Response
[
  {
    "id": "pc_5a7b3c9d2e1f",
    "livemode": false,
    "active": true,
    "locked": false,
    "is_base_currency": false,
    "payment_method_id": "pm_12345",
    "name": "My Custom Token",
    "description": "An updated description for my custom token.",
    "contract": "0x1234567890abcdef1234567890abcdef12345678",
    "logo": "https://example.com/default-logo.png",
    "symbol": "MCT",
    "decimal": 18,
    "type": "standard",
    "minimum_payment_amount": "1000000000000",
    "maximum_payment_amount": "100000000000000000000000000000",
    "metadata": { "order_id": "6735" }
  }
]Delete a Payment Currency#Deletes a payment currency. It cannot be deleted if it is locked or has been used in transactions.
DELETE /api/payment-currencies/{id}
Parameters
Name
Type
Description
id
string
Required. The ID of the currency to delete.
Returns
Returns a success status code 200 if the deletion is successful.
Example
import payment from '@blocklet/payment-js';

async function deleteCurrency(currencyId) {
  try {
    await payment.paymentCurrencies.del(currencyId);
    console.log(`Currency ${currencyId} has been deleted.`);
  } catch (error) {
    console.error('Error deleting currency:', error.message);
  }
}

deleteCurrency('pc_5a7b3c9d2e1f');Get Recharge Configuration#Retrieves the recharge configuration for a credit currency. This is used to allow users to top-up their credit balance.
GET /api/payment-currencies/{id}/recharge-config
Parameters
Name
Type
Description
id
string
Required. The ID of the credit currency.
Returns
Returns an object containing the currency's recharge configuration. The recharge_config object includes details like the base price for purchasing credits and a ready-to-use payment URL.
Example
import payment from '@blocklet/payment-js';

async function getRechargeConfig(currencyId) {
  try {
    const config = await payment.paymentCurrencies.getRechargeConfig(currencyId);
    if (config.recharge_config) {
      console.log('Recharge Payment URL:', config.recharge_config.payment_url);
    } else {
      console.log('Recharge is not configured for this currency.');
    }
  } catch (error) {
    console.error('Error getting recharge config:', error.message);
  }
}

getRechargeConfig('pc_credit_123');Example Response
{
  "currency_id": "pc_credit_123",
  "currency_info": {
    "id": "pc_credit_123",
    "name": "App Credits",
    "symbol": "CRD",
    "decimal": 2,
    "type": "credit"
  },
  "recharge_config": {
    "base_price_id": "price_abc123",
    "payment_link_id": "pl_def456",
    "settings": {
      "min_recharge_amount": 100
    },
    "basePrice": {
      "id": "price_abc123",
      "unit_amount": "100",
      "currency_id": "pc_eth_mainnet",
      "product": {
        "id": "prod_ghi789",
        "name": "Credit Top-Up"
      }
    },
    "payment_url": "https://example.com/checkout/pay/pl_def456"
  }
}Update Recharge Configuration#Updates the recharge configuration for a credit currency. This allows you to define how users can purchase credits.
PUT /api/payment-currencies/{id}/recharge-config
Parameters
Name
Type
Description
id
string
Required. The ID of the credit currency.
base_price_id
string
Required. The ID of the Price object that defines the cost of one unit of credit. This price must be active.
payment_link_id
string
Optional. The ID of a pre-existing PaymentLink to use for recharges.
checkout_url
string
Optional. A custom URL for the checkout page. If not provided, a payment link will be used or generated.
settings
object
Optional. Additional settings for the recharge process.
settings Object Properties
Name
Type
Description
min_recharge_amount
number
Optional. The minimum amount of credits a user can purchase in a single transaction.
max_recharge_amount
number
Optional. The maximum amount of credits a user can purchase in a single transaction.
Returns
Returns an object confirming the update and showing the new configuration.
Example
import payment from '@blocklet/payment-js';

async function updateRechargeConfig(currencyId) {
  try {
    const config = {
      base_price_id: 'price_new_abc',
      settings: {
        min_recharge_amount: 500, // 5.00 credits if decimal is 2
        max_recharge_amount: 100000, // 1000.00 credits
      }
    };
    const result = await payment.paymentCurrencies.updateRechargeConfig(currencyId, config);
    console.log(result.message);
  } catch (error) {
    console.error('Error updating recharge config:', error.message);
  }
}

updateRechargeConfig('pc_credit_123');Example Response
{
  "currency_id": "pc_credit_123",
  "recharge_config": {
    "base_price_id": "price_new_abc",
    "settings": {
      "min_recharge_amount": 500,
      "max_recharge_amount": 100000
    }
  },
  "message": "Recharge config updated successfully"
}This completes the overview of managing Payment Currencies. You can use these methods to control which assets are accepted for payment and to enable credit top-up functionality for your users.

Attribute	Type	Description
`id`	`string`	Unique identifier for the payment currency.
`livemode`	`boolean`	`true` if the currency is for live mode, `false` for test mode. Inherited from the parent `PaymentMethod`.
`active`	`boolean`	Whether this currency is active and can be used for payments. Inherited from the parent `PaymentMethod`.
`locked`	`boolean`	`true` if the currency is locked and cannot be deleted.
`is_base_currency`	`boolean`	`true` if this is a native/base currency of a blockchain (e.g., ETH, ABT).
`payment_method_id`	`string`	The ID of the `PaymentMethod` this currency belongs to.
`name`	`string`	The name of the currency (e.g., "Tether USD").
`description`	`string`	A description of the currency.
`contract`	`string`	The contract address for token-based currencies.
`logo`	`string`	URL of the currency's logo.
`symbol`	`string`	The currency's symbol (e.g., "USDT").
`decimal`	`number`	The number of decimal places the currency supports.
`type`	`string`	The type of currency. Can be `standard` or `credit`.
`minimum_payment_amount`	`string`	The minimum amount for a single payment, in the smallest unit of the currency.
`maximum_payment_amount`	`string`	The maximum amount for a single payment, in the smallest unit of the currency.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`recharge_config`	`object`	Configuration for credit top-ups. See the `updateRechargeConfig` method for details.
`vault_config`	`object`	Configuration for the automated deposit and withdrawal vault.

Name	Type	Description
`name`	`string`	Required. The name of the currency.
`description`	`string`	Required. A description for the currency.
`payment_method_id`	`string`	Required. The ID of the `PaymentMethod` to associate this currency with.
`contract`	`string`	Required. The token's contract address.
`logo`	`string`	Optional. A URL for the currency's logo. If not provided, the logo of the payment method will be used.

Name	Type	Description
`id`	`string`	Required. The ID of the currency to update.
`name`	`string`	Optional. The new name for the currency.
`description`	`string`	Optional. The new description for the currency.
`logo`	`string`	Optional. The new logo URL for the currency.
`metadata`	`object`	Optional. A set of key-value pairs to store with the object.
`symbol`	`string`	Optional. The new symbol. Can only be updated if `type` is `credit`.

Name	Type	Description
`active`	`boolean`	Optional. Filters the list to only include active or inactive currencies.
`livemode`	`boolean`	Optional. Filters the list based on the currency's mode (live or test).
`credit`	`boolean`	Optional. If `true`, the list will include currencies of type `credit` in addition to `standard`.

Name	Type	Description
`id`	`string`	Required. The ID of the credit currency.
`base_price_id`	`string`	Required. The ID of the `Price` object that defines the cost of one unit of credit. This price must be active.
`payment_link_id`	`string`	Optional. The ID of a pre-existing `PaymentLink` to use for recharges.
`checkout_url`	`string`	Optional. A custom URL for the checkout page. If not provided, a payment link will be used or generated.
`settings`	`object`	Optional. Additional settings for the recharge process.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Payment Currencies

The Payment Currency Object#

Create a Payment Currency#

Retrieve a Payment Currency#

Update a Payment Currency#

List Payment Currencies#

Delete a Payment Currency#

Get Recharge Configuration#

Update Recharge Configuration#

Payment Links

Subscriptions

Name	Type	Description
`min_recharge_amount`	`number`	Optional. The minimum amount of credits a user can purchase in a single transaction.
`max_recharge_amount`	`number`	Optional. The maximum amount of credits a user can purchase in a single transaction.