Payment Methods
The Payment Methods API allows you to manage the payment options available for transactions. These methods represent the different ways your customers can pay, such as with a credit card via Stripe or with cryptocurrency on an EVM-compatible chain. These are typically configured by an administrator.
The Payment Method Object#
A Payment Method object represents a configured payment gateway.
{
"id": "pm_123abc",
"type": "stripe",
"name": "Credit Card",
"description": "Pay with Visa, Mastercard, etc.",
"livemode": false,
"active": true,
"locked": false,
"logo": "/methods/stripe.png",
"features": {
"recurring": true,
"refund": true,
"dispute": true
},
"confirmation": {
"type": "callback"
},
"settings": {
"stripe": {
"publishable_key": "pk_test_xxxxxxxxxxxx"
}
},
"default_currency_id": "pc_usd_123",
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z",
"payment_currencies": [
{
"id": "pc_usd_123",
"name": "Dollar",
"symbol": "USD",
"decimal": 2
}
]
}Create a Payment Method#
Adds a new payment method to your system. You must provide a type and the necessary settings for that type.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| A human-readable name for the payment method (e.g., "Credit Card"). Required. |
|
| A short description of the payment method. Required. |
|
| The type of the payment method. Supported values include |
|
| Configuration specific to the payment method type. Required. See details below. |
|
| An optional URL for the payment method's logo. If not provided, a default logo may be used. |
settings Object Properties
The structure of the settings object depends on the type.
For type: 'stripe'
Property | Type | Description |
|---|---|---|
|
| Your Stripe publishable API key. Required. |
|
| Your Stripe secret API key. Required. |
For EVM-compatible types (e.g., type: 'ethereum')
Property | Type | Description |
|---|---|---|
|
| The JSON-RPC API endpoint for the chain. Required. |
|
| The URL of the block explorer (e.g., |
|
| The symbol for the native currency (e.g., |
|
| The number of block confirmations to wait for. Optional, defaults to |
Returns
Returns the newly created TPaymentMethodExpanded object, which includes details about the payment method and its default currency.
Example
import payment from '@blocklet/payment-js';
async function createStripeMethod() {
try {
const stripeMethod = await payment.paymentMethods.create({
name: 'Credit Card',
description: 'Pay with Visa, Mastercard, etc.',
type: 'stripe',
settings: {
stripe: {
publishable_key: 'pk_test_xxxxxxxxxxxx',
secret_key: 'sk_test_xxxxxxxxxxxx'
}
}
});
console.log('Stripe method created:', stripeMethod);
} catch (error) {
console.error('Error creating Stripe method:', error.message);
}
}
createStripeMethod();Retrieve a Payment Method#
Fetches the details of a specific payment method using its unique ID.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The unique identifier of the payment method to retrieve. Required. |
Returns
Returns a TPaymentMethodExpanded object if found.
Example
import payment from '@blocklet/payment-js';
async function getPaymentMethod(methodId) {
try {
const method = await payment.paymentMethods.retrieve(methodId);
console.log('Retrieved Method:', method);
} catch (error) {
console.error('Error retrieving payment method:', error.message);
}
}
getPaymentMethod('pm_123abc');Update a Payment Method#
Modifies an existing payment method's details, such as its name, description, logo, or settings.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The unique identifier of the payment method to update. Required. |
|
| An object containing the fields to update (e.g., |
updateData Object Properties
Property | Type | Description |
|---|---|---|
|
| An updated name for the payment method. Optional. |
|
| An updated description. Optional. |
|
| A new URL for the logo. Optional. |
|
| Updated configuration for the payment method. The structure depends on the method |
Returns
Returns the updated TPaymentMethod object.
Example
import payment from '@blocklet/payment-js';
async function updatePaymentMethod(methodId) {
try {
const updatedMethod = await payment.paymentMethods.update(methodId, {
description: 'Accept all major credit and debit cards.',
});
console.log('Updated Method:', updatedMethod);
} catch (error) {
console.error('Error updating payment method:', error.message);
}
}
updatePaymentMethod('pm_123abc');List Payment Methods#
Retrieves a list of all configured payment methods, with options to filter the results.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Filter methods by their active status. Optional. |
|
| Filter methods by their live mode status. Optional. |
|
| If |
Returns
By default, returns an array of TPaymentMethodExpanded objects. If addresses is true, it returns an object of the shape { list, addresses, balances }.
Example (Basic List)
import payment from '@blocklet/payment-js';
async function listMethods() {
try {
const methods = await payment.paymentMethods.list();
methods.forEach(method => {
console.log(`- ${method.name} (ID: ${method.id})`);
});
} catch (error) {
console.error('Error listing payment methods:', error.message);
}
}
listMethods();Example Response (Basic List)
[
{
"id": "pm_123abc",
"type": "stripe",
"name": "Credit Card"
},
{
"id": "pm_456def",
"type": "ethereum",
"name": "Ethereum Mainnet"
}
]Example (With Addresses)
import payment from '@blocklet/payment-js';
async function listMethodsWithDetails() {
try {
const result = await payment.paymentMethods.list({ addresses: true });
console.log('Methods:', result.list);
console.log('Addresses:', result.addresses);
console.log('Balances:', result.balances);
} catch (error) {
console.error('Error listing payment methods with details:', error.message);
}
}
listMethodsWithDetails();Example Response (With Addresses)
{
"list": [
{
"id": "pm_123abc",
"type": "stripe"
}
],
"addresses": {
"arcblock": "z1...",
"ethereum": "0x..."
},
"balances": {
"ABT": { "balance": "100000000000000000000", "decimal": 18 },
"ETH": { "balance": "500000000000000000", "decimal": 18 }
}
}List Available Method Types#
This utility endpoint lists all supported payment method types that can be created. This is useful for dynamically populating a user interface where an administrator can choose which type of payment method to configure. This endpoint is not exposed as a direct SDK resource method, but you can call it via GET /api/payment-methods/types.
Returns
Returns an array of objects, where each object describes a supported payment method type.
Example Response
[
{
"type": "arcblock",
"name": "ArcBlock",
"description": "Instant payment with ArcBlock chain",
"logo": "/methods/arcblock.png"
},
{
"type": "stripe",
"name": "Stripe",
"description": "Pay with credit card or bank account",
"logo": "/methods/stripe.png"
},
{
"type": "ethereum",
"name": "Ethereum",
"description": "Pay with ethereum compatible chains",
"logo": "/methods/ethereum.png"
},
{
"type": "base",
"name": "Base",
"description": "Pay with base compatible chains",
"logo": "/methods/base.png"
}
]This endpoint is useful for building user interfaces that allow administrators to configure new payment gateways dynamically.