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.
Create a new payment currency
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
{
"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.
Retrieve a payment currency
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
{
"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.
Update a payment currency
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
{
"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.
List all active currencies
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
[
{
"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. |
Get credit recharge configuration
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 currencyResponse Example
{
"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.
Update credit recharge configuration
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
{
"currency_id": "curr_zzzzzzzzzzzzzz",
"recharge_config": {
"base_price_id": "price_yyyyyyyyyyyyyy",
"settings": {
"min_recharge_amount": 5
}
},
"message": "Recharge config updated successfully"
}