支付方式

支付方式对象代表了客户可以使用的不同支付途径，例如通过 Stripe（信用卡、银行账户）或各种加密货币网络。此 API 允许您配置、管理和列出可供客户使用的支付方式。

每种支付方式都与一种或多种支付货币相关联，这些货币定义了通过该方式接受的具体货币种类。

支付方式对象#

支付方式对象包含特定支付提供商或网络的所有配置详情。

The Payment Method Object

{
  "id": "pm_123abc",
  "name": "Stripe 信用卡",
  "description": "使用信用卡或银行账户支付",
  "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": [

See all 25 lines

创建支付方式#

创建一个新的支付方式配置。所需的 settings 对象根据支付方式的 type 而有所不同。

参数

Name

Type

Description

name

string

必需。 支付方式的人类可读名称（例如，“信用卡”）。最多 32 个字符。

description

string

必需。 支付方式的简短描述。最多 255 个字符。

type

string

必需。 支付方式的类型。支持的值包括 stripe、ethereum 以及其他 EVM 兼容链，如 base。

settings

object

必需。 一个配置对象，包含特定于支付方式 type 的凭据和设置。详见下文。

logo

string

可选。支付方式的徽标 URL。如果未提供，将根据 type 使用默认徽标。

Stripe 设置对象属性

当 type 为 stripe 时，settings.stripe 对象必须包含以下属性：

Name

Type

Description

publishable_key

string

必需。 您的 Stripe 可发布 API 密钥。

secret_key

string

必需。 您的 Stripe 秘密 API 密钥。

EVM 链设置对象属性

当 type 是 EVM 链（例如 ethereum）时，settings.{type} 对象必须包含以下属性：

Name

Type

Description

api_host

string

必需。 区块链网络的 JSON-RPC API 端点。

explorer_host

string

必需。 区块链浏览器的基础 URL（例如 https://etherscan.io）。

native_symbol

string

必需。 链上原生货币的符号（例如，“ETH”）。

confirmation

number

可选。将交易视为最终交易所需要的区块确认数。默认为 1。

返回

返回新创建的 TPaymentMethodExpanded 对象，其中包含一个自动创建的关联 payment_currencies 数组。

Create a Stripe Payment Method

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

async function createStripeMethod() {
  try {
    const stripeMethod = await payment.paymentMethods.create({
      name: '信用卡',
      description: '使用 Visa、Mastercard 等支付。',
      type: 'stripe',
      settings: {
        stripe: {
          publishable_key: 'pk_test_YOUR_PUBLISHABLE_KEY',
          secret_key: 'sk_test_YOUR_SECRET_KEY',
        },
      },
    });
    console.log('Stripe 方法已创建：', stripeMethod);
  } catch (error) {
    console.error('创建 Stripe 方法时出错：', error.message);
  }
}

createStripeMethod();

Example Response

{
  "id": "pm_abc123",
  "name": "信用卡",
  "description": "使用 Visa、Mastercard 等支付。",
  "type": "stripe",
  "active": true,
  // ... 其他字段
  "payment_currencies": [
    {
      "id": "pc_xyz789",
      "name": "美元",
      "symbol": "USD",
      // ... 其他货币字段
    }
  ]
}

检索支付方式#

通过唯一 ID 检索现有支付方式的详细信息。

参数

Name

Type

Description

id

string

必需。 要检索的支付方式的唯一标识符。

返回

如果找到，则返回 TPaymentMethodExpanded 对象，否则返回 404 错误。

Retrieve a Payment Method

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_abc123'); // 替换为有效的支付方式 ID

更新支付方式#

通过设置传入参数的值来更新指定的支付方式。任何未提供的参数将保持不变。

参数

Name

Type

Description

id

string

必需。 要更新的支付方式的唯一标识符。

data

object

必需。 一个包含要更新字段的对象。请参见下面的属性。

更新数据对象属性

Name

Type

Description

name

string

可选。支付方式的新名称。

description

string

可选。支付方式的新描述。

logo

string

可选。支付方式的新徽标 URL。

settings

object

可选。新的设置对象。结构必须与该方式的 type 匹配。更新 Stripe 密钥时，webhook 签名密钥将被重置，必须重新配置。

返回

返回更新后的 TPaymentMethod 对象。

Update a Payment Method

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

async function updatePaymentMethod(methodId) {
  try {
    const updatedMethod = await payment.paymentMethods.update(methodId, {
      description: '接受所有主流信用卡和借记卡。',
    });
    console.log('支付方式已更新：', updatedMethod.description);
  } catch (error) {
    console.error(`更新支付方式 ${methodId} 时出错：`, error.message);
  }
}

updatePaymentMethod('pm_abc123'); // 替换为有效的支付方式 ID

列出支付方式#

返回您的支付方式列表。这些方式按创建日期排序，最新创建的方式排在最前面。

参数

Name

Type

Description

active

boolean

可选。一个布尔标志，用于按活动状态筛选支付方式。

livemode

boolean

可选。一个布尔标志，用于筛选生产模式或测试模式的支付方式。

page

number

可选。用于分页的页码，从 1 开始。

pageSize

number

可选。每页返回的项目数。默认为 20。

返回

返回一个 TPaymentMethodExpanded 对象数组。

List all active Payment Methods

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

async function listActiveMethods() {
  try {
    const methods = await payment.paymentMethods.list({
      active: true,
      livemode: false, // 筛选测试方法
    });
    console.log(`找到 ${methods.length} 个活动的测试支付方式：`);
    methods.forEach(method => {
      console.log(`- ${method.name} (类型: ${method.type})`);
    });
  } catch (error) {
    console.error('列出支付方式时出错：', error.message);
  }
}

listActiveMethods();

Example Response

[
  {
    "id": "pm_abc123",
    "name": "信用卡",
    "type": "stripe",
    "active": true,
    "livemode": false,
    // ... 其他字段
  },
  {
    "id": "pm_def456",
    "name": "Ethereum",
    "type": "ethereum",
    "active": true,
    "livemode": false,
    // ... 其他字段
  }
]
支付链接
价格