付款意圖 | ArcBlock

付款意圖 (Payment Intent) 是一個物件，代表您向客戶收款的意圖，並追蹤付款流程的生命週期。它是 PaymentKit API 中的核心物件，控制著從客戶到您的資金流動。付款意圖可以與結帳階段關聯，用於面向使用者的付款流程，或直接用於伺服器端操作。

本文件詳細說明如何使用 SDK 管理付款意圖物件。

付款意圖物件

付款意圖物件包含有關交易的詳細資訊。展開後，它還可以包含相關物件。

物件屬性

Property	Type	Description
`id`	`string`	物件的唯一識別碼。
`status`	`string`	付款意圖的狀態。可能的值為 `requires_payment_method`、`requires_confirmation`、`requires_action`、`processing`、`requires_capture`、`canceled` 或 `succeeded`。
`amount`	`string`	預計收取的金額。
`amount_received`	`string`	目前已收到的金額。
`currency_id`	`string`	此次付款所用貨幣的 ID。
`customer_id`	`string`	此付款意圖對應的客戶 ID (如果存在)。
`invoice_id`	`string`	此付款意圖對應的發票 ID (如果存在)。
`payment_method_id`	`string`	此付款意圖使用的付款方式 ID。
`metadata`	`object`	一組您可以附加到物件上的鍵值對。
`created_at`	`string`	物件建立時的時間戳。

展開的物件

擷取時，付款意圖物件可以包含以下展開的物件：

customer：完整的 Customer 物件。
paymentCurrency：完整的 PaymentCurrency 物件。
paymentMethod：完整的 PaymentMethod 物件。
invoice：完整的 Invoice 物件 (如適用)。
subscription：完整的 Subscription 物件 (如適用)。
checkoutSession：建立此付款意圖的 CheckoutSession。

擷取付款意圖

擷取先前已建立的付款意圖的詳細資訊。當提供 client_secret 時，允許使用可發布金鑰進行客戶端擷取。

擷取付款意圖

const paymentIntent = await payment.paymentIntents.retrieve(
  'pi_123456789'
);

console.log(paymentIntent);

參數

Name	Type	Description
`id`	`string`	必要。要擷取的付款意圖 ID。

傳回值

如果提供了有效的 ID，則傳回一個 PaymentIntent 物件。否則會拋出錯誤。

回應範例

{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "amount_received": "1000",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "invoice_id": "in_xxxxxxxx",
  "payment_method_id": "pm_xxxxxxxx",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    /* ... 付款貨幣詳細資訊 ... */
  },
  "paymentMethod": {
    /* ... 付款方式詳細資訊 ... */
  },
  "customer": {
    /* ... 客戶詳細資訊 ... */
  },
  "invoice": {
    /* ... 發票詳細資訊 ... */
  },
  "subscription": null,
  "checkoutSession": {
    /* ... 結帳階段詳細資訊 ... */
  }
}

更新付款意圖

透過設定傳入參數的值來更新付款意圖物件。任何未提供的參數將保持不變。請注意，只有 metadata 可以透過此方法更新。

更新付款意圖

const paymentIntent = await payment.paymentIntents.update(
  'pi_123456789',
  {
    metadata: { order_id: '6735' }
  }
);

console.log(paymentIntent);

參數

Name	Type	Description
`id`	`string`	必要。要更新的付款意圖 ID。
`metadata`	`object`	一組儲存在物件上的鍵值對。

傳回值

傳回更新後的 PaymentIntent 物件。

回應範例

{
  "id": "pi_123456789",
  "status": "succeeded",
  "amount": "1000",
  "metadata": {
    "order_id": "6735"
  },
  // ... 其他屬性
}

列出所有付款意圖

傳回您的付款意圖列表。這些意圖按建立日期排序，最新的意圖會最先出現。

列出付款意圖

const paymentIntents = await payment.paymentIntents.list({
  limit: 5,
  status: 'succeeded'
});

console.log(paymentIntents);

參數

Name	Type	Description
`status`	`string`	可選。以逗號分隔的狀態字串，用於篩選 (例如：`'succeeded,processing'`)。
`invoice_id`	`string`	可選。僅傳回指定發票的付款意圖。
`customer_id`	`string`	可選。僅傳回指定客戶 ID 的付款意圖。
`customer_did`	`string`	可選。僅傳回指定客戶 DID 的付款意圖。
`metadata.{key}`	`string`	可選。按特定的元資料鍵值對進行篩選。
`page`	`number`	可選。分頁的頁碼，從 1 開始。預設為 `1`。
`pageSize`	`number`	可選。限制傳回物件的數量，介於 1 和 100 之間。預設為 `20`。

傳回值

一個分頁物件，其中包含 PaymentIntent 物件的 list 和分頁詳細資訊。

回應範例

{
  "count": 15,
  "list": [
    {
      "id": "pi_123456789",
      "status": "succeeded",
      // ... 其他屬性
    },
    {
      "id": "pi_987654321",
      "status": "succeeded",
      // ... 其他屬性
    }
    // ... 更多付款意圖
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

搜尋付款意圖

搜尋符合特定查詢的付款意圖。

搜尋付款意圖

const results = await payment.paymentIntents.search({
  query: 'cus_xxxxxxxx'
});

console.log(results);

參數

Name	Type	Description
`query`	`string`	必要。搜尋查詢字串。
`page`	`number`	可選。分頁的頁碼，從 1 開始。預設為 `1`。
`pageSize`	`number`	可選。每頁的項目數量。預設為 `20`。

傳回值

一個分頁物件，其中包含符合搜尋查詢的 PaymentIntent 物件的 list。

回應範例

{
  "count": 1,
  "list": [
    {
      "id": "pi_123456789",
      "customer_id": "cus_xxxxxxxx",
      // ... 其他屬性
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}

退款

當付款意圖成功時，您可以為該筆費用建立退款。這將建立一個 Refund 物件並嘗試沖銷該筆費用。

退款

const refund = await payment.paymentIntents.refund(
  'pi_123456789',
  {
    amount: '500',
    reason: 'requested_by_customer',
    description: 'Refund for item not received.'
  }
);

console.log(refund);

參數

Name	Type	Description
`id`	`string`	必要。要退款的付款意圖 ID。
`amount`	`string`	必要。一個正數字串，代表要退還此筆費用的金額。最多可退還原始費用的總金額。
`reason`	`string`	必要。指示退款原因的字串。有效值為：`duplicate`、`requested_by_customer`、`requested_by_admin`、`fraudulent`、`expired_uncaptured_charge`。
`description`	`string`	必要。對退款的說明。

傳回值

傳回一個新的 Refund 物件。

回應範例

{
  "id": "re_abcdef123",
  "type": "refund",
  "livemode": false,
  "amount": "500",
  "description": "Refund for item not received.",
  "status": "pending",
  "reason": "requested_by_customer",
  "currency_id": "cur_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_123456789",
  // ... 其他退款屬性
}