API 参考

支付方式

支付方式 API 允许你配置和管理客户可以使用的不同支付方式。每种支付方式代表一个特定的支付提供商或区块链网络，如 Stripe、ArcBlock 或以太坊。正确配置这些方式是处理支付和创建结账会话的前提条件。
Usage
Configuration
Defines
payment.paymentMethods.create()
Payment Method Object
(e.g., Stripe, ArcBlock)
Checkout Session
Uses configured method

本文档介绍了如何使用 PaymentKit SDK 创建、检索、更新和列出支付方式。
支付方式对象#支付方式对象包含特定支付选项的所有配置详情。
属性
类型
描述
id
string
支付方式的唯一标识符。
active
boolean
此支付方式是否已激活并可用于新交易。
livemode
boolean
如果对象存在于生产模式，则为 true；如果存在于测试模式，则为 false。
locked
boolean
如果为 true，则无法修改此支付方式。
type
string
支付方式的类型。可以是 'stripe'、'arcblock'、'ethereum'、'bitcoin' 或 'base'。
name
string
向用户显示的支付方式名称。
description
string
支付方式的描述。
logo
string
此支付方式徽标的 URL。
default_currency_id
string
（可选）此支付方式的默认货币 ID。
confirmation
object
定义支付何时被视为已确认。包含 type（'immediate'、'callback'、'block'）和可选的 block 数量。
settings
object
特定于支付方式 type 的配置。请参阅类型参考中的 PaymentMethodSettings。例如，对于 Stripe，它包含 API 密钥。
features
object
一个指示所支持功能的对象：recurring、refund、dispute。
metadata
object
一组可以附加到对象的键值对。
created_at
Date
创建支付方式时的时间戳。
updated_at
Date
上次更新支付方式时的时间戳。
创建支付方式#创建新的支付方式配置。
参数#名称
类型
描述
name
string
必需。支付方式的名称。
type
string
必需。类型，例如 'stripe'、'arcblock'。
description
string
支付方式的描述。
settings
object
必需。包含指定 type 的配置密钥和机密的对象。有关详细信息，请参阅 PaymentMethodSettings。
active
boolean
支付方式是否激活。默认为 false。
livemode
boolean
支付方式是用于生产模式还是测试模式。默认为 false。
confirmation
object
支付的确认设置。
返回值#返回新创建的 PaymentMethod 对象。
示例#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, // 用于测试环境
      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('支付方式已创建：', newMethod);
  } catch (error) {
    console.error('创建支付方式时出错：', error.message);
  }
}

createStripeMethod();响应示例#{
  "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"
}检索支付方式#检索现有支付方式的详细信息。
参数#名称
类型
描述
id
string
必需。要检索的支付方式的唯一标识符。
返回值#如果找到，则返回 PaymentMethod 对象。
示例#import payment from '@blocklet/payment-js';

async function getPaymentMethod(methodId) {
  try {
    const method = await payment.paymentMethods.retrieve(methodId);
    console.log('已检索到支付方式：', method.name);
  } catch (error) {
    console.error(`检索支付方式 ${methodId} 时出错：`, error.message);
  }
}

getPaymentMethod('pm_123456789');响应示例#{
  "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"
}更新支付方式#通过设置所传递参数的值来更新指定的支付方式。任何未提供的参数将保持不变。
参数#名称
类型
描述
id
string
必需。要更新的支付方式的唯一标识符。
data
object
必需。包含要更新字段的对象。可包括 name、description、active、settings 等。
返回值#返回更新后的 PaymentMethod 对象。
示例#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('支付方式已更新：', updatedMethod);
  } catch (error) {
    console.error(`更新支付方式 ${methodId} 时出错：`, error.message);
  }
}

updatePaymentMethod('pm_123456789');响应示例#{
  "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"
}列出所有支付方式#返回你的支付方式列表。支付方式按创建日期排序返回，最新创建的支付方式会最先出现。
参数#名称
类型
描述
page
number
用于分页的页码，从 1 开始。
pageSize
number
每页返回的项目数。默认为 20。
order
string or string[]
结果的排序顺序。例如：'created_at:DESC'。
返回值#返回一个 PaymentMethod 对象数组。
示例#import payment from '@blocklet/payment-js';

async function listPaymentMethods() {
  try {
    const methods = await payment.paymentMethods.list({ pageSize: 5 });
    console.log(`找到 ${methods.length} 个支付方式：`);
    methods.forEach(method => {
      console.log(`- ${method.name} (ID: ${method.id})`);
    });
  } catch (error) {
    console.error('列出支付方式时出错：', error.message);
  }
}

listPaymentMethods();响应示例#[
  {
    "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"
  }
]
现在你已经了解如何管理支付方式，你可能希望配置它们可以接受的货币。请继续阅读支付货币指南以获取更多信息。

属性	类型	描述
`id`	`string`	支付方式的唯一标识符。
`active`	`boolean`	此支付方式是否已激活并可用于新交易。
`livemode`	`boolean`	如果对象存在于生产模式，则为 `true`；如果存在于测试模式，则为 `false`。
`locked`	`boolean`	如果为 `true`，则无法修改此支付方式。
`type`	`string`	支付方式的类型。可以是 `'stripe'`、`'arcblock'`、`'ethereum'`、`'bitcoin'` 或 `'base'`。
`name`	`string`	向用户显示的支付方式名称。
`description`	`string`	支付方式的描述。
`logo`	`string`	此支付方式徽标的 URL。
`default_currency_id`	`string`	（可选）此支付方式的默认货币 ID。
`confirmation`	`object`	定义支付何时被视为已确认。包含 `type`（`'immediate'`、`'callback'`、`'block'`）和可选的 `block` 数量。
`settings`	`object`	特定于支付方式 `type` 的配置。请参阅类型参考中的 `PaymentMethodSettings`。例如，对于 Stripe，它包含 API 密钥。
`features`	`object`	一个指示所支持功能的对象：`recurring`、`refund`、`dispute`。
`metadata`	`object`	一组可以附加到对象的键值对。
`created_at`	`Date`	创建支付方式时的时间戳。
`updated_at`	`Date`	上次更新支付方式时的时间戳。

名称	类型	描述
`name`	`string`	必需。支付方式的名称。
`type`	`string`	必需。类型，例如 `'stripe'`、`'arcblock'`。
`description`	`string`	支付方式的描述。
`settings`	`object`	必需。包含指定 `type` 的配置密钥和机密的对象。有关详细信息，请参阅 `PaymentMethodSettings`。
`active`	`boolean`	支付方式是否激活。默认为 `false`。
`livemode`	`boolean`	支付方式是用于生产模式还是测试模式。默认为 `false`。
`confirmation`	`object`	支付的确认设置。

名称	类型	描述
`id`	`string`	必需。要更新的支付方式的唯一标识符。
`data`	`object`	必需。包含要更新字段的对象。可包括 `name`、`description`、`active`、`settings` 等。

名称	类型	描述
`page`	`number`	用于分页的页码，从 1 开始。
`pageSize`	`number`	每页返回的项目数。默认为 20。
`order`	`string` or `string[]`	结果的排序顺序。例如：`'created_at:DESC'`。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

支付方式

支付方式对象#

创建支付方式#

参数#

返回值#

示例#

响应示例#

检索支付方式#

参数#

返回值#

示例#

响应示例#

更新支付方式#

参数#

返回值#

示例#

响应示例#

列出所有支付方式#

参数#

返回值#

示例#

响应示例#

支付货币

支付链接