API Reference

Payment Currencies

The Payment Currencies API allows you to manage the different currencies your application accepts for payments. Each currency is linked to a specific payment method and defines properties such as its name, symbol, and decimal precision.
This is a core resource that is referenced by other objects, such as Prices.
The Payment Currency Object#A PaymentCurrency object contains detailed information about a supported currency.
Attribute
Type
Description
id
string
Unique identifier for the currency object.
payment_method_id
string
The ID of the payment method this currency is associated with.
active
boolean
Whether this currency is active and can be used for payments.
livemode
boolean
true if the object exists in live mode, or false if it exists in test mode.
locked
boolean
If true, this currency cannot be modified.
is_base_currency
boolean
Indicates if this is a base currency for the associated payment method.
name
string
The full name of the currency (e.g., "Ethereum").
description
string
A description of the currency.
logo
string
A URL to an image or logo for the currency.
symbol
string
The currency symbol (e.g., "ETH").
decimal
number
The number of decimal places the currency supports.
maximum_precision
number
The maximum number of digits after the decimal point.
minimum_payment_amount
string
The minimum amount required for a single payment, as a string.
maximum_payment_amount
string
The maximum amount allowed for a single payment, as a string.
contract
string
The contract address for token-based currencies, if applicable.
type
string
The type of currency. Can be 'standard' or 'credit'.
vault_config
object
Configuration for the currency vault. Contains enabled, deposit_threshold, withdraw_threshold, buffer_threshold.
metadata
Record<string, any>
A set of key-value pairs that you can attach to an object.
created_at
Date
The timestamp of when the currency was created.
updated_at
Date
The timestamp of the last update to the currency.
Create a Currency#Creates a new payment currency that your application can accept.
Parameters
Name
Type
Description
name
string
Required. The full name of the currency.
payment_method_id
string
Required. The ID of the payment method this currency belongs to.
symbol
string
Required. The currency's symbol.
logo
string
Required. A URL for the currency's logo.
description
string
An optional description for the currency.
decimal
number
The number of decimal places. Defaults to 18.
type
string
The type of currency. Can be standard or credit. Defaults to standard.
active
boolean
Whether the currency is active. Defaults to true.
minimum_payment_amount
string
The minimum payment amount. Defaults to '0'.
maximum_payment_amount
string
The maximum payment amount. Defaults to a very large number string.
contract
string
The contract address for token-based currencies.
Example
import payment from '@blocklet/payment-js';

async function createCurrency() {
  try {
    const currency = await payment.paymentCurrencies.create({
      name: 'ArcBlock Token',
      symbol: 'ABT',
      logo: 'https://www.arcblock.io/images/abt-logo.png',
      description: 'The native token of the ArcBlock platform.',
      payment_method_id: 'pm_xxxxxxxxxxxx',
      decimal: 18,
      type: 'standard'
    });
    console.log('Currency created:', currency);
  } catch (error) {
    console.error('Error creating currency:', error);
  }
}

createCurrency();Example Response
{
  "id": "curr_1234567890",
  "payment_method_id": "pm_xxxxxxxxxxxx",
  "active": true,
  "livemode": false,
  "locked": false,
  "is_base_currency": false,
  "name": "ArcBlock Token",
  "description": "The native token of the ArcBlock platform.",
  "logo": "https://www.arcblock.io/images/abt-logo.png",
  "symbol": "ABT",
  "decimal": 18,
  "maximum_precision": 8,
  "minimum_payment_amount": "0",
  "maximum_payment_amount": "10000000000000000000000000000",
  "contract": null,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "vault_config": null,
  "type": "standard"
}Retrieve a Currency#Retrieves the details of an existing payment currency.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the currency to retrieve.
Example
import payment from '@blocklet/payment-js';

async function getCurrency(currencyId) {
  try {
    const currency = await payment.paymentCurrencies.retrieve(currencyId);
    console.log('Retrieved currency:', currency.name);
  } catch (error) {
    console.error('Error retrieving currency:', error);
  }
}

getCurrency('curr_1234567890');Example Response
{
  "id": "curr_1234567890",
  "payment_method_id": "pm_xxxxxxxxxxxx",
  "active": true,
  "livemode": false,
  "locked": false,
  "is_base_currency": false,
  "name": "ArcBlock Token",
  "description": "The native token of the ArcBlock platform.",
  "logo": "https://www.arcblock.io/images/abt-logo.png",
  "symbol": "ABT",
  "decimal": 18,
  "maximum_precision": 8,
  "minimum_payment_amount": "0",
  "maximum_payment_amount": "10000000000000000000000000000",
  "contract": null,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "vault_config": null,
  "type": "standard"
}Update a Currency#Updates the specified payment currency by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
The first argument is the id of the currency to update. The second argument is an object containing the fields to update.
Name
Type
Description
name
string
The full name of the currency.
description
string
A description for the currency.
logo
string
A URL for the currency's logo.
active
boolean
Whether the currency is active.
minimum_payment_amount
string
The minimum payment amount.
maximum_payment_amount
string
The maximum payment amount.
metadata
Record<string, any>
A set of key-value pairs to store with the currency.
Example
import payment from '@blocklet/payment-js';

async function updateCurrency(currencyId) {
  try {
    const currency = await payment.paymentCurrencies.update(currencyId, {
      description: 'An updated description for the native token of ArcBlock.'
    });
    console.log('Currency updated:', currency.description);
  } catch (error) {
    console.error('Error updating currency:', error);
  }
}

updateCurrency('curr_1234567890');Example Response
{
  "id": "curr_1234567890",
  "payment_method_id": "pm_xxxxxxxxxxxx",
  "active": true,
  "livemode": false,
  "locked": false,
  "is_base_currency": false,
  "name": "ArcBlock Token",
  "description": "An updated description for the native token of ArcBlock.",
  "logo": "https://www.arcblock.io/images/abt-logo.png",
  "symbol": "ABT",
  "decimal": 18,
  "maximum_precision": 8,
  "minimum_payment_amount": "0",
  "maximum_payment_amount": "10000000000000000000000000000",
  "contract": null,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T11:00:00.000Z",
  "vault_config": null,
  "type": "standard"
}List 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
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of items per page. Defaults to 20.
order
string or string[]
The order to sort the results by. Example: ['created_at', 'DESC'].
Example
import payment from '@blocklet/payment-js';

async function listCurrencies() {
  try {
    const currencyList = await payment.paymentCurrencies.list({ pageSize: 5 });
    console.log(`Found ${currencyList.length} currencies:`);
    currencyList.forEach(currency => {
      console.log(`- ${currency.name} (${currency.symbol})`);
    });
  } catch (error) {
    console.error('Error listing currencies:', error);
  }
}

listCurrencies();Example Response
The list method returns an array of PaymentCurrency objects.
[
  {
    "id": "curr_1234567890",
    "name": "ArcBlock Token",
    "symbol": "ABT",
    "active": true,
    "livemode": false,
    "logo": "https://www.arcblock.io/images/abt-logo.png"
  },
  {
    "id": "curr_abcdefghij",
    "name": "Ethereum",
    "symbol": "ETH",
    "active": true,
    "livemode": false,
    "logo": "https://example.com/eth_logo.png"
  }
]Now that you know how to manage currencies, you can explore how to manage the Payment Methods they are associated with or how to use them in Prices.

Attribute	Type	Description
`id`	`string`	Unique identifier for the currency object.
`payment_method_id`	`string`	The ID of the payment method this currency is associated with.
`active`	`boolean`	Whether this currency is active and can be used for payments.
`livemode`	`boolean`	`true` if the object exists in live mode, or `false` if it exists in test mode.
`locked`	`boolean`	If `true`, this currency cannot be modified.
`is_base_currency`	`boolean`	Indicates if this is a base currency for the associated payment method.
`name`	`string`	The full name of the currency (e.g., "Ethereum").
`description`	`string`	A description of the currency.
`logo`	`string`	A URL to an image or logo for the currency.
`symbol`	`string`	The currency symbol (e.g., "ETH").
`decimal`	`number`	The number of decimal places the currency supports.
`maximum_precision`	`number`	The maximum number of digits after the decimal point.
`minimum_payment_amount`	`string`	The minimum amount required for a single payment, as a string.
`maximum_payment_amount`	`string`	The maximum amount allowed for a single payment, as a string.
`contract`	`string`	The contract address for token-based currencies, if applicable.
`type`	`string`	The type of currency. Can be `'standard'` or `'credit'`.
`vault_config`	`object`	Configuration for the currency vault. Contains `enabled`, `deposit_threshold`, `withdraw_threshold`, `buffer_threshold`.
`metadata`	`Record<string, any>`	A set of key-value pairs that you can attach to an object.
`created_at`	`Date`	The timestamp of when the currency was created.
`updated_at`	`Date`	The timestamp of the last update to the currency.

Name	Type	Description
`name`	`string`	Required. The full name of the currency.
`payment_method_id`	`string`	Required. The ID of the payment method this currency belongs to.
`symbol`	`string`	Required. The currency's symbol.
`logo`	`string`	Required. A URL for the currency's logo.
`description`	`string`	An optional description for the currency.
`decimal`	`number`	The number of decimal places. Defaults to `18`.
`type`	`string`	The type of currency. Can be `standard` or `credit`. Defaults to `standard`.
`active`	`boolean`	Whether the currency is active. Defaults to `true`.
`minimum_payment_amount`	`string`	The minimum payment amount. Defaults to `'0'`.
`maximum_payment_amount`	`string`	The maximum payment amount. Defaults to a very large number string.
`contract`	`string`	The contract address for token-based currencies.

Name	Type	Description
`name`	`string`	The full name of the currency.
`description`	`string`	A description for the currency.
`logo`	`string`	A URL for the currency's logo.
`active`	`boolean`	Whether the currency is active.
`minimum_payment_amount`	`string`	The minimum payment amount.
`maximum_payment_amount`	`string`	The maximum payment amount.
`metadata`	`Record<string, any>`	A set of key-value pairs to store with the currency.

Name	Type	Description
`page`	`number`	The page number for pagination. Defaults to `1`.
`pageSize`	`number`	The number of items per page. Defaults to `20`.
`order`	`string` or `string[]`	The order to sort the results by. Example: `['created_at', 'DESC']`.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Payment Currencies

The Payment Currency Object#

Create a Currency#

Retrieve a Currency#

Update a Currency#

List Currencies#

Payment Intents

Payment Methods