退款 | ArcBlock

退款物件代表將先前費用的款項退還給顧客。您可以建立新的退款、擷取現有退款的詳細資訊，以及列出所有退款以供會計之用。建立退款時，其初始狀態為 pending，並將以非同步方式處理。

退款物件

一個典型的退款物件包含以下關鍵屬性：

id：退款物件的唯一識別碼。
amount：退款總金額，以最小貨幣單位表示（例如，分）。
currency_id：用於退款的貨幣識別碼。
status：退款的目前狀態。可以是 pending、succeeded、failed 或 canceled。
reason：退款原因。可能的值包括 duplicate、requested_by_customer、requested_by_admin、fraudulent 或 expired_uncaptured_charge。
payment_intent_id：被退款的 Payment Intent 的 ID。
customer_id：退款發放對象的 Customer 的 ID。
description：退款的描述。
metadata：一組您可以附加到物件上的鍵值對，供您自己參考。
created_at：退款建立時的時間戳。

建立退款

建立一個 Refund 物件，以退還先前已建立的費用。這可以是全額退款或部分退款。

建立退款

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

async function issueRefund() {
  try {
    const refund = await payment.refunds.create({
      payment_intent_id: 'pi_xxxxxxxxxxxx',
      amount: '50.00', // 注意：amount 是一個字串，表示以主要單位（例如，元）計算的值
      currency_id: 'usd_xxxxxxxx',
      customer_id: 'cus_xxxxxxxx',
      payment_method_id: 'pm_xxxxxxxx',
      reason: 'requested_by_customer',
      description: 'Refund for order #54321',
      metadata: { order_id: '54321' }
    });
    console.log('退款已啟動：', refund);
  } catch (error) {
    console.error('建立退款時發生錯誤：', error.message);
  }
}

issueRefund();

參數

Name	Type	Description
`amount`	`string`	必要。一個正數字串，表示要退款的金額。退款金額不能超過該筆費用的剩餘可退款金額。
`currency_id`	`string`	必要。退款貨幣的識別碼。
`customer_id`	`string`	必要。與退款相關的顧客識別碼。
`payment_method_id`	`string`	必要。用於原始費用的支付方式識別碼。
`payment_intent_id`	`string`	必要。要退款的 PaymentIntent 識別碼。
`reason`	`string`	必要。表示退款原因的字串。支援的值為 `duplicate`、`requested_by_customer`、`requested_by_admin`、`fraudulent`、`expired_uncaptured_charge`。
`description`	`string`	必要。附加到物件的任意字串。通常用於向使用者顯示。最多 200 個字元。
`metadata`	`object`	可選。一組您可以附加到退款物件的鍵值對。這對於以結構化格式儲存額外資訊很有用。
`invoice_id`	`string`	可選。與此退款相關的發票 ID。
`subscription_id`	`string`	可選。與此退款相關的訂閱 ID。

回傳

回傳建立的 Refund 物件。

回應範例

{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "pending",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z"
}

擷取退款

透過其唯一 ID 擷取現有退款的詳細資訊。

擷取退款

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

async function getRefundDetails(refundId) {
  try {
    const refund = await payment.refunds.retrieve(refundId);
    console.log('退款詳情：', refund);
  } catch (error) {
    console.error(`擷取退款 ${refundId} 時發生錯誤：`, error.message);
  }
}

getRefundDetails('ref_xxxxxxxxxxxx');

參數

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

回傳

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

回應範例

{
  "id": "ref_xxxxxxxxxxxx",
  "object": "refund",
  "amount": "5000",
  "currency_id": "usd_xxxxxxxx",
  "customer_id": "cus_xxxxxxxx",
  "payment_intent_id": "pi_xxxxxxxxxxxx",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "description": "Refund for order #54321",
  "metadata": {
    "order_id": "54321"
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "customer": { ... },
  "paymentCurrency": { ... },
  "paymentIntent": { ... },
  "paymentMethod": { ... }
}

列出所有退款

回傳所有退款的分頁列表。您可以根據各種條件過濾列表。

列出退款

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

async function listSuccessfulRefunds() {
  try {
    const response = await payment.refunds.list({
      status: 'succeeded',
      pageSize: 10
    });
    console.log(`找到 ${response.count} 筆成功的退款。`);
    response.list.forEach(refund => {
      console.log(`- 退款 ID: ${refund.id}, 金額: ${refund.amount}`);
    });
  } catch (error) {
    console.error('列出退款時發生錯誤：', error.message);
  }
}

listSuccessfulRefunds();

參數

Name	Type	Description
`page`	`number`	可選。用於分頁的頁碼，從 1 開始。預設為 `1`。
`pageSize`	`number`	可選。每頁回傳的物件數量。預設為 `20`。
`status`	`string`	可選。一個以逗號分隔的字串，用於按狀態過濾退款（例如，`'succeeded,pending'`）。
`invoice_id`	`string`	可選。僅回傳指定發票的退款。
`subscription_id`	`string`	可選。僅回傳指定訂閱的退款。
`currency_id`	`string`	可選。僅回傳指定貨幣的退款。
`customer_id`	`string`	可選。僅回傳指定顧客的退款。

回傳

回傳一個分頁物件，其中包含一個 Refund 物件的 list、總 count 和 paging 資訊。

回應範例

{
  "count": 15,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "status": "succeeded",
      // ... 其他退款欄位
    }
    // ... 更多退款物件
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

搜尋退款

對您的退款執行搜尋查詢。這對於建立自訂搜尋功能很有用。

搜尋退款

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

async function searchForRefund(query) {
  try {
    const response = await payment.refunds.search({ q: query });
    console.log(`關於 '${query}' 的搜尋結果：`);
    response.list.forEach(refund => {
      console.log(`- 退款 ID: ${refund.id}`);
    });
  } catch (error) {
    console.error('搜尋退款時發生錯誤：', error.message);
  }
}

searchForRefund('customer_id:cus_xxxxxxxx');

參數

Name	Type	Description
`q`	`string`	必要。搜尋查詢字串。支援鍵值過濾（例如，`status:succeeded`）。
`page`	`number`	可選。用於分頁的頁碼。預設為 `1`。
`pageSize`	`number`	可選。每頁回傳的物件數量。預設為 `20`。
`o`	`string`	可選。指定結果的順序。使用 `asc` 表示升序，或 `desc` 表示降序。預設根據 `created_at` 降序排列。

回傳

回傳一個分頁物件，其中包含一個符合條件的 Refund 物件的 list、總 count 和 paging 資訊。

回應範例

{
  "count": 1,
  "list": [
    {
      "id": "ref_xxxxxxxxxxxx",
      "object": "refund",
      "amount": "5000",
      "customer_id": "cus_xxxxxxxx",
      "status": "succeeded",
      // ... 其他退款欄位
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 20
  }
}