單次付款 | ArcBlock

PaymentKit 提供多種彈性方式來處理商品或服務的單次收費。本指南將引導您了解 Node.js SDK 中可用的三種主要方法，幫助您選擇最適合您特定需求的方法。

每種方法都適用於不同的使用情境，從完全託管的付款頁面到深度整合的自訂付款流程。

Checkout 工作階段

最快的入門方式。將使用者重新導向至由 PaymentKit 託管的安全、預先建置的付款頁面。

付款連結

建立一個可分享、可重複使用的付款頁面連結。非常適合社群媒體、電子郵件或簡單的購買按鈕。

付款意圖

付款的基礎物件。用於建立自訂付款使用者介面和管理收費生命週期。

Checkout 工作階段

Checkout 工作階段是接受付款最簡單的方式。它會建立一個安全的託管付款頁面，處理整個結帳流程。您只需建立一個工作階段，將您的顧客重新導向至提供的 URL，剩下的就由 PaymentKit 處理。

這種方法非常適合標準的電子商務流程、捐款按鈕，或任何您希望在不自行建置使用者介面的情況下，獲得快速、安全且功能齊全的結帳體驗的場景。

運作方式

建立工作階段
您的伺服器使用 SDK 建立一個工作階段，指定訂單項目、成功和取消的 URL 以及其他詳細資訊。
重新導向顧客
API 會傳回一個包含 url 的工作階段物件。您將顧客重新導向至此 URL。
顧客付款
顧客在託管頁面上完成付款。
重新導向回來
PaymentKit 將顧客重新導向回您的 success_url 或 cancel_url。

範例：建立 Checkout 工作階段

以下是如何為單次付款建立工作階段。

Create Checkout Session

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

async function createCheckoutSession() {
  try {
    const session = await payment.checkout.sessions.create({
      mode: 'payment', // 指定為單次付款
      success_url: 'https://your-site.com/payment-success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://your-site.com/payment-cancelled',
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // 請替換為您的價格 ID
          quantity: 1,
        },
      ],
      expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // 工作階段將在 30 分鐘後過期
    });

    console.log('Checkout Session URL:', session.url);
    // 現在，將您的使用者重新導向至 session.url
  } catch (error) {
    console.error('Error creating session:', error.message);
  }
}

createCheckoutSession();

建立工作階段後，應使用 session.url 將顧客重新導向至付款頁面。有關參數和選項的完整列表，請參閱 Checkout Sessions API 參考。

付款連結

付款連結提供了一種為特定產品建立可重複使用的結帳頁面連結的方法。建立後，您可以透過電子郵件、社群媒體等多個管道分享此連結，或將其嵌入您網站上的簡單「立即購買」按鈕中。它們非常適合銷售單一商品或服務，而無需完整的購物車整合。

運作方式

建立連結
使用 SDK 建立一個付款連結，指定一個或多個訂單項目。
分享 URL
API 會傳回該連結的永久 url。
顧客付款
任何造訪該 URL 的顧客都可以完成付款。

範例：建立付款連結

Create Payment Link

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

async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // 請替換為您的價格 ID
          quantity: 1,
        },
      ],
      metadata: {
        campaign: 'summer_sale_2024'
      }
    });

    console.log('Shareable Payment Link:', paymentLink.url);
  } catch (error) {
    console.error('Error creating payment link:', error.message);
  }
}

createPaymentLink();

您也可以更新付款連結，例如，在不再需要時使用 payment.paymentLinks.archive(id) 將其封存。更多詳細資訊，請造訪 Payment Links API 參考。

付款意圖

Payment Intent 物件是 PaymentKit 中任何交易的核心。它追蹤付款從建立到完成的整個生命週期，處理過程中的各種驗證步驟和狀態變更。雖然 Checkout 工作階段和付款連結會自動為您建立和管理 Payment Intent，但您可以直接與它們互動以實現更進階的應用，例如建立自訂付款表單或處理付款後的操作。

直接與 Payment Intent 互動通常用於管理現有付款，例如處理退款。

範例：退款

在付款成功後（例如，透過 Checkout 工作階段），您可以擷取相關的 Payment Intent ID 並用它來處理退款。

Refund a Payment

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

// Payment Intent ID 通常從已完成的 Checkout 工作階段取得
// 或透過 webhook 事件取得。
const paymentIntentId = 'pi_xxxxxxxxxxxxxx';

async function refundPayment(pi_id) {
  try {
    const refund = await payment.paymentIntents.refund(pi_id, {
      amount: '10.00', // 要退款的金額
      reason: 'requested_by_customer',
      description: '顧客對產品不滿意。',
    });

    console.log('Refund processed successfully:', refund.id);
  } catch (error) {
    console.error(`Error refunding payment ${pi_id}:`, error.message);
  }
}

refundPayment(paymentIntentId);

這讓您在初始收費完成後，能夠對付款生命週期進行精細的控制。有關完整的管理功能列表，請參閱 Payment Intents API 參考。

現在您已了解如何建立單次收費，您可能想學習如何實現訂閱以進行週期性計費，或設定 Webhooks 以接收有關付款事件的即時通知。