Payment Methods

Payment Method objects represent the different ways a customer can pay, such as with Stripe (credit cards, bank accounts) or through various cryptocurrency networks. This API allows you to configure, manage, and list the payment methods available to your customers.

Each payment method is linked to one or more Payment Currencies, which define the specific currencies accepted through that method.

The Payment Method Object#

A Payment Method object contains all the configuration details for a specific payment provider or network.

{
  "id": "pm_123abc",
  "name": "Stripe Credit Cards",
  "description": "Pay with credit card or bank account",
  "type": "stripe",
  "logo": "/methods/stripe.png",
  "active": true,
  "locked": false,
  "livemode": false,
  "default_currency_id": "pc_456def",
  "features": {
    "recurring": true,
    "refund": true,
    "dispute": true
  },
  "confirmation": {
    "type": "callback"
  },
  "settings": {
    "stripe": {
      "publishable_key": "pk_test_...",
      "secret_key": "sk_test_... (encrypted)"
    }
  },
  "payment_currencies": [

Create a Payment Method#

Creates a new Payment Method configuration. The required settings object varies depending on the type of the payment method.

Parameters

Name	Type	Description
name	string	Required. A human-readable name for the payment method (e.g., "Credit Card"). Maximum 32 characters.
description	string	Required. A short description of the payment method. Maximum 255 characters.
type	string	Required. The type of payment method. Supported values include stripe, ethereum, and other EVM-compatible chains like base.
settings	object	Required. A configuration object containing credentials and settings specific to the payment method type. See details below.
logo	string	Optional. A URL to a logo for the payment method. If not provided, a default logo will be used based on the type.

Stripe Settings Object Properties

When type is stripe, the settings.stripe object must contain the following properties:

Name	Type	Description
publishable_key	string	Required. Your Stripe publishable API key.
secret_key	string	Required. Your Stripe secret API key.

EVM Chain Settings Object Properties

When type is an EVM chain (e.g., ethereum), the settings.{type} object must contain the following properties:

Name	Type	Description
api_host	string	Required. The JSON-RPC API endpoint for the blockchain network.
explorer_host	string	Required. The base URL for the blockchain explorer (e.g., https://etherscan.io).
native_symbol	string	Required. The symbol for the native currency of the chain (e.g., "ETH").
confirmation	number	Optional. The number of block confirmations required to consider a transaction final. Defaults to 1.

Returns

Returns the newly created TPaymentMethodExpanded object, which includes an array of associated payment_currencies that were automatically created.

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_YOUR_PUBLISHABLE_KEY',
          secret_key: 'sk_test_YOUR_SECRET_KEY',
        },
      },
    });
    console.log('Stripe method created:', stripeMethod);
  } catch (error) {
    console.error('Error creating Stripe method:', error.message);
  }
}

createStripeMethod();

{
  "id": "pm_abc123",
  "name": "Credit Card",
  "description": "Pay with Visa, Mastercard, etc.",
  "type": "stripe",
  "active": true,
  // ... other fields
  "payment_currencies": [
    {
      "id": "pc_xyz789",
      "name": "Dollar",
      "symbol": "USD",
      // ... other currency fields
    }
  ]
}

Retrieve a Payment Method#

Retrieves the details of an existing Payment Method by its unique ID.

Parameters

Name	Type	Description
id	string	Required. The unique identifier of the Payment Method to retrieve.

Returns

Returns the TPaymentMethodExpanded object if found, otherwise returns a 404 error.

import payment from '@blocklet/payment-js';

async function getPaymentMethod(methodId) {
  try {
    const method = await payment.paymentMethods.retrieve(methodId);
    console.log('Retrieved method:', method.name);
  } catch (error) {
    console.error(`Error retrieving payment method ${methodId}:`, error.message);
  }
}

getPaymentMethod('pm_abc123'); // Replace with a valid Payment Method ID

Update a Payment Method#

Updates the specified Payment Method by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

Name	Type	Description
id	string	Required. The unique identifier of the Payment Method to update.
data	object	Required. An object containing the fields to update. See properties below.

Update Data Object Properties

Name	Type	Description
name	string	Optional. The new name for the payment method.
description	string	Optional. The new description for the payment method.
logo	string	Optional. The new logo URL for the payment method.
settings	object	Optional. The new settings object. The structure must match the method's type. When updating Stripe keys, the webhook signing secret will be reset and must be reconfigured.

Returns

Returns the updated TPaymentMethod object.

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('Payment method updated:', updatedMethod.description);
  } catch (error) {
    console.error(`Error updating payment method ${methodId}:`, error.message);
  }
}

updatePaymentMethod('pm_abc123'); // Replace with a valid Payment Method ID

List Payment Methods#

Returns a list of your Payment Methods. The methods are returned sorted by creation date, with the most recently created methods appearing first.

Parameters

Name	Type	Description
active	boolean	Optional. A boolean flag to filter payment methods by their active status.
livemode	boolean	Optional. A boolean flag to filter for live or test mode payment methods.
page	number	Optional. The page number for pagination, starting at 1.
pageSize	number	Optional. The number of items to return per page. Defaults to 20.

Returns

Returns an array of TPaymentMethodExpanded objects.

import payment from '@blocklet/payment-js';

async function listActiveMethods() {
  try {
    const methods = await payment.paymentMethods.list({
      active: true,
      livemode: false, // Filter for test methods
    });
    console.log(`Found ${methods.length} active test payment methods:`);
    methods.forEach(method => {
      console.log(`- ${method.name} (Type: ${method.type})`);
    });
  } catch (error) {
    console.error('Error listing payment methods:', error.message);
  }
}

listActiveMethods();

[
  {
    "id": "pm_abc123",
    "name": "Credit Card",
    "type": "stripe",
    "active": true,
    "livemode": false,
    // ... other fields
  },
  {
    "id": "pm_def456",
    "name": "Ethereum",
    "type": "ethereum",
    "active": true,
    "livemode": false,
    // ... other fields
  }
]