API Reference

Payment Methods

The Payment Methods API allows you to configure and manage the different ways your customers can pay. Each payment method represents a specific payment provider or blockchain network, such as Stripe, ArcBlock, or Ethereum. Properly configuring these methods is a prerequisite for processing payments and creating checkout sessions.
Usage
Configuration
Defines
payment.paymentMethods.create()
Payment Method Object
(e.g., Stripe, ArcBlock)
Checkout Session
Uses configured method

This document covers how to create, retrieve, update, and list payment methods using the PaymentKit SDK.
The Payment Method Object#A payment method object contains all the configuration details for a specific payment option.
Attribute
Type
Description
id
string
Unique identifier for the payment method.
active
boolean
Whether this payment method is active and can be used for new transactions.
livemode
boolean
true if the object exists in live mode or false if it exists in test mode.
locked
boolean
If true, this payment method cannot be modified.
type
string
The type of payment method. Can be 'stripe', 'arcblock', 'ethereum', 'bitcoin', or 'base'.
name
string
The name of the payment method displayed to users.
description
string
A description of the payment method.
logo
string
URL of the logo for this payment method.
default_currency_id
string
(Optional) The ID of the default currency for this payment method.
confirmation
object
Defines when a payment is considered confirmed. Contains type ('immediate', 'callback', 'block') and optional block count.
settings
object
Configuration specific to the payment method type. See PaymentMethodSettings in the types reference. For example, for Stripe it contains API keys.
features
object
An object indicating supported features: recurring, refund, dispute.
metadata
object
A set of key-value pairs that you can attach to an object.
created_at
Date
The timestamp when the payment method was created.
updated_at
Date
The timestamp when the payment method was last updated.
Create a Payment Method#Creates a new payment method configuration.
Parameters#Name
Type
Description
name
string
Required. The name of the payment method.
type
string
Required. The type, e.g., 'stripe', 'arcblock'.
description
string
A description for the payment method.
settings
object
Required. An object containing the configuration keys and secrets for the specified type. See PaymentMethodSettings for details.
active
boolean
Whether the payment method is active. Defaults to false.
livemode
boolean
Whether the payment method is for live or test mode. Defaults to false.
confirmation
object
Confirmation settings for the payment.
Returns#Returns the newly created PaymentMethod object.
Example#import payment from '@blocklet/payment-js';

async function createStripeMethod() {
  try {
    const newMethod = await payment.paymentMethods.create({
      name: 'Stripe Credit Cards',
      type: 'stripe',
      description: 'Accept credit card payments via Stripe.',
      active: true,
      livemode: false, // For test environment
      settings: {
        stripe: {
          dashboard: 'https://dashboard.stripe.com/test',
          publishable_key: 'pk_test_xxxxxxxx',
          secret_key: 'sk_test_xxxxxxxx',
          webhook_signing_secret: 'whsec_xxxxxxxx',
        }
      }
    });
    console.log('Payment method created:', newMethod);
  } catch (error) {
    console.error('Error creating payment method:', error.message);
  }
}

createStripeMethod();Response Example#{
  "id": "pm_123456789",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "stripe",
  "name": "Stripe Credit Cards",
  "description": "Accept credit card payments via Stripe.",
  "logo": "/assets/stripe.png",
  "default_currency_id": null,
  "confirmation": {
    "type": "callback"
  },
  "settings": {
    "stripe": {
      "dashboard": "https://dashboard.stripe.com/test",
      "publishable_key": "pk_test_xxxxxxxx",
      "secret_key": "...",
      "webhook_signing_secret": "..."
    }
  },
  "features": {
    "recurring": true,
    "refund": true,
    "dispute": true
  },
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Payment Method#Retrieves the details of an existing payment method.
Parameters#Name
Type
Description
id
string
Required. The unique identifier of the payment method to retrieve.
Returns#Returns the PaymentMethod 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 payment method:', method.name);
  } catch (error) {
    console.error(`Error retrieving payment method ${methodId}:`, error.message);
  }
}

getPaymentMethod('pm_123456789');Response Example#{
  "id": "pm_123456789",
  "active": true,
  "livemode": false,
  "locked": false,
  "type": "stripe",
  "name": "Stripe Credit Cards",
  "description": "Accept credit card payments via Stripe.",
  "logo": "/assets/stripe.png",
  "default_currency_id": null,
  "confirmation": {
    "type": "callback"
  },
  "settings": {
    "stripe": {
      "dashboard": "https://dashboard.stripe.com/test",
      "publishable_key": "pk_test_xxxxxxxx",
      "secret_key": "...",
      "webhook_signing_secret": "..."
    }
  },
  "features": {
    "recurring": true,
    "refund": true,
    "dispute": true
  },
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:15:00.000Z"
}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. This can include name, description, active, settings, etc.
Returns#Returns the updated PaymentMethod object.
Example#import payment from '@blocklet/payment-js';

async function updatePaymentMethod(methodId) {
  try {
    const updatedMethod = await payment.paymentMethods.update(methodId, {
      description: 'Accept major credit and debit cards via Stripe.',
      active: false
    });
    console.log('Payment method updated:', updatedMethod);
  } catch (error) {
    console.error(`Error updating payment method ${methodId}:`, error.message);
  }
}

updatePaymentMethod('pm_123456789');Response Example#{
  "id": "pm_123456789",
  "active": false,
  "livemode": false,
  "locked": false,
  "type": "stripe",
  "name": "Stripe Credit Cards",
  "description": "Accept major credit and debit cards via Stripe.",
  "logo": "/assets/stripe.png",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:30:00.000Z"
}List all Payment Methods#Returns a list of your payment methods. The payment methods are returned sorted by creation date, with the most recently created payment methods appearing first.
Parameters#Name
Type
Description
page
number
The page number for pagination, starting from 1.
pageSize
number
The number of items to return per page. Defaults to 20.
order
string or string[]
The order to sort the results. Example: 'created_at:DESC'.
Returns#Returns an array of PaymentMethod objects.
Example#import payment from '@blocklet/payment-js';

async function listPaymentMethods() {
  try {
    const methods = await payment.paymentMethods.list({ pageSize: 5 });
    console.log(`Found ${methods.length} payment methods:`);
    methods.forEach(method => {
      console.log(`- ${method.name} (ID: ${method.id})`);
    });
  } catch (error) {
    console.error('Error listing payment methods:', error.message);
  }
}

listPaymentMethods();Response Example#[
  {
    "id": "pm_123456789",
    "active": false,
    "livemode": false,
    "type": "stripe",
    "name": "Stripe Credit Cards",
    "created_at": "2023-10-27T10:00:00.000Z"
  },
  {
    "id": "pm_abcdefgh",
    "active": true,
    "livemode": true,
    "type": "arcblock",
    "name": "ArcBlock DID Wallet",
    "created_at": "2023-10-26T14:00:00.000Z"
  }
]
Now that you know how to manage payment methods, you might want to configure the currencies they can accept. Proceed to the Payment Currencies guide for more information.

Attribute	Type	Description
`id`	`string`	Unique identifier for the payment method.
`active`	`boolean`	Whether this payment method is active and can be used for new transactions.
`livemode`	`boolean`	`true` if the object exists in live mode or `false` if it exists in test mode.
`locked`	`boolean`	If `true`, this payment method cannot be modified.
`type`	`string`	The type of payment method. Can be `'stripe'`, `'arcblock'`, `'ethereum'`, `'bitcoin'`, or `'base'`.
`name`	`string`	The name of the payment method displayed to users.
`description`	`string`	A description of the payment method.
`logo`	`string`	URL of the logo for this payment method.
`default_currency_id`	`string`	(Optional) The ID of the default currency for this payment method.
`confirmation`	`object`	Defines when a payment is considered confirmed. Contains `type` (`'immediate'`, `'callback'`, `'block'`) and optional `block` count.
`settings`	`object`	Configuration specific to the payment method `type`. See `PaymentMethodSettings` in the types reference. For example, for Stripe it contains API keys.
`features`	`object`	An object indicating supported features: `recurring`, `refund`, `dispute`.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`created_at`	`Date`	The timestamp when the payment method was created.
`updated_at`	`Date`	The timestamp when the payment method was last updated.

Name	Type	Description
`name`	`string`	Required. The name of the payment method.
`type`	`string`	Required. The type, e.g., `'stripe'`, `'arcblock'`.
`description`	`string`	A description for the payment method.
`settings`	`object`	Required. An object containing the configuration keys and secrets for the specified `type`. See `PaymentMethodSettings` for details.
`active`	`boolean`	Whether the payment method is active. Defaults to `false`.
`livemode`	`boolean`	Whether the payment method is for live or test mode. Defaults to `false`.
`confirmation`	`object`	Confirmation settings for the payment.

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. This can include `name`, `description`, `active`, `settings`, etc.

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

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Payment Methods

The Payment Method Object#

Create a Payment Method#

Parameters#

Returns#

Example#

Response Example#

Retrieve a Payment Method#

Parameters#

Returns#

Example#

Response Example#

Update a Payment Method#

Parameters#

Returns#

Example#

Response Example#

List all Payment Methods#

Parameters#

Returns#

Example#

Response Example#

Payment Currencies

Payment Links