Skip to main content

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.

The Payment Method Object

json
{
  "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": [
    {
      "id": "pc_456def",
      "livemode": false,
      "active": true,
      "locked": true,
      "is_base_currency": false,
      "payment_method_id": "pm_123abc",
      "type": "standard",
      "name": "Dollar",
      "description": "US Dollar",
      "logo": "/currencies/dollar.png",
      "symbol": "USD",
      "decimal": 2,
      "maximum_precision": 2,
      "minimum_payment_amount": "1",
      "maximum_payment_amount": "100000000000",
      "contract": "",
      "metadata": {},
      "created_at": "2023-10-27T10:00:01.000Z",
      "updated_at": "2023-10-27T10:00:01.000Z"
    }
  ],
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

Create a Payment Method

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

Parameters

NameTypeDescription
namestringRequired. A human-readable name for the payment method (e.g., "Credit Card"). Maximum 32 characters.
descriptionstringRequired. A short description of the payment method. Maximum 255 characters.
typestringRequired. The type of payment method. Supported values include stripe, ethereum, and other EVM-compatible chains like base.
settingsobjectRequired. A configuration object containing credentials and settings specific to the payment method type. See details below.
logostringOptional. 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:

NameTypeDescription
publishable_keystringRequired. Your Stripe publishable API key.
secret_keystringRequired. 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:

NameTypeDescription
api_hoststringRequired. The JSON-RPC API endpoint for the blockchain network.
explorer_hoststringRequired. The base URL for the blockchain explorer (e.g., https://etherscan.io).
native_symbolstringRequired. The symbol for the native currency of the chain (e.g., "ETH").
confirmationnumberOptional. 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.

Create a Stripe Payment Method

javascript
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();

Example Response

json
{
  "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

NameTypeDescription
idstringRequired. The unique identifier of the Payment Method to retrieve.

Returns

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

Retrieve a Payment Method

javascript
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

NameTypeDescription
idstringRequired. The unique identifier of the Payment Method to update.
dataobjectRequired. An object containing the fields to update. See properties below.

Update Data Object Properties

NameTypeDescription
namestringOptional. The new name for the payment method.
descriptionstringOptional. The new description for the payment method.
logostringOptional. The new logo URL for the payment method.
settingsobjectOptional. 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.

Update a Payment Method

javascript
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

NameTypeDescription
activebooleanOptional. A boolean flag to filter payment methods by their active status.
livemodebooleanOptional. A boolean flag to filter for live or test mode payment methods.
pagenumberOptional. The page number for pagination, starting at 1.
pageSizenumberOptional. The number of items to return per page. Defaults to 20.

Returns

Returns an array of TPaymentMethodExpanded objects.

List all active Payment Methods

javascript
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();

Example Response

json
[
  {
    "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
  }
]