支付方式 | ArcBlock

支付方式对象代表了客户可以使用的不同支付途径，例如通过 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": [
    {
      "id": "pc_456def",
      "livemode": false,
      "active": true,
      "locked": true,
      "is_base_currency": false,
      "payment_method_id": "pm_123abc",
      "type": "standard",
      "name": "美元",
      "description": "美元",
      "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"
}

创建支付方式

创建一个新的支付方式配置。所需的 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,
    // ... 其他字段
  }
]