付款方式 | ArcBlock

Payment Method 物件代表客戶可以支付的不同方式，例如使用 Stripe（信用卡、銀行帳戶）或透過各種加密貨幣網路。此 API 可讓您設定、管理和列出可供客戶使用的付款方式。

每種付款方式都連結到一個或多個付款貨幣，這些貨幣定義了透過該方式接受的特定貨幣。

Payment Method 物件

Payment Method 物件包含特定支付提供商或網路的所有設定詳細資訊。

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"
}

建立付款方式

建立一個新的 Payment Method 設定。所需的 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 擷取現有 Payment Method 的詳細資訊。

參數

Name	Type	Description
`id`	`string`	必要。要擷取的 Payment Method 的唯一識別碼。

傳回值

如果找到，則傳回 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'); // 請替換為有效的 Payment Method ID

更新付款方式

透過設定傳入參數的值來更新指定的 Payment Method。任何未提供的參數將保持不變。

參數

Name	Type	Description
`id`	`string`	必要。要更新的 Payment Method 的唯一識別碼。
`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'); // 請替換為有效的 Payment Method ID

列出付款方式

傳回您的 Payment Methods 列表。這些方式按建立日期排序，最新建立的方式會最先出現。

參數

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": "以太坊",
    "type": "ethereum",
    "active": true,
    "livemode": false,
    // ... 其他欄位
  }
]