@astralweb/nova-ctbc-payment 模組使用指南

⚠️ 內部使用套件 - 此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。

概覽

CTBC Payment 整合模組為 Nuxt 應用程式提供完整的中國信託支付功能，包括支付請求、回調處理等功能。模組設計簡潔易用，支援 Vue Storefront 中介層整合，並提供完整的 TypeScript 型別支援。

安裝與設定

1. 安裝套件

在 apps/web 和 apps/server 安裝

yarn add @astralweb/nova-ctbc-payment

2. 註冊模組

在 nuxt.config.ts 中註冊模組

// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@astralweb/nova-ctbc-payment',
  ],
});

3. Middleware 擴充

將 CTBC Payment API 方法擴充到 Vue Storefront middleware

// apps/server/extendApiMethods/index.ts

// ... 略
export { createCtbcPaymentRequest, processCtbcPaymentResponse, createCtbcRepayRequest } from '@astralweb/nova-ctbc-payment/api';

基本使用

在結帳流程中使用

<!-- CheckoutPageContent.vue -->
<script setup lang="ts">
const { requestCTBCPayment } = useCTBCPayment();
const handleCTBCPayment = async () => {
  const data = await placeOrderMutateAsync();
  if (!data?.number || !data?.id) throw new Error('Order not found');

  localStorage.setItem('lastOrderNumber', data?.number);

  await requestCTBCPayment(atob(data.id));
};
</script>

重新付款

<!-- OrderDetailPageContent.vue -->
<script setup lang="ts">
const { requestCTBCPaymentRepay } = useCTBCPayment();
const handleCTBCPaymentRepay = async () => {
  await requestCTBCPaymentRepay(id.value, paymentMethodType.value);
  localStorage.setItem('lastOrderNumber', number.value);
};
</script>

Composables API

useCTBCPayment

CTBC Payment 支付的主要 composable，自動註冊可直接使用。

const { requestCTBCPayment, processCTBCPaymentResponse, requestCTBCPaymentRepay } = useCTBCPayment();

返回值

| 名稱 | 類型 | 說明 | | --- | --- | --- | | requestCTBCPayment | Function | 請求 CTBC 支付的非同步函數| | processCTBCPaymentResponse | Function | 處理 CTBC 支付回應的非同步函數 | | requestCTBCPaymentRepay | Function | 請求 CTBC 重新付款的非同步函數 |

requestCTBCPayment

請求 CTBC 支付。此函數會呼叫 createCtbcPaymentRequest 取得支付資料，建立隱藏表單並自動提交，將使用者導向至 CTBC 支付頁面。

await requestCTBCPayment('ORDER_ID');

參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | order_id | string | Yes | 訂單 ID（'123'） |

錯誤處理：

• 當 GraphQL 回應包含錯誤時拋出錯誤
• 當支付資料不存在時拋出錯誤
• 當 success 為 false 時拋出錯誤並包含 error_message

processCTBCPaymentResponse

處理 CTBC 支付回應，並回傳付款狀態。

const response = await processCTBCPaymentResponse(merID, URLResEnc);

參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | merID | string | Yes | 商店代號 | | URLResEnc | string | Yes | 加密回應資料 |

返回值：

{
  success: boolean;          // 請求是否成功
  order_status: string;      // 訂單狀態
  message: string;           // 訊息
  error_message: string;     // 錯誤訊息（如果有）
  payment_details: {
    status: string;          // 支付狀態（'0' 表示成功）
    errcode: string;         // 錯誤代碼
  };
}

錯誤處理：

• 當 GraphQL 回應包含錯誤時拋出錯誤
• 當回應資料不存在時拋出錯誤
• 當 success 為 false 時拋出錯誤並包含 error_message
• 當 payment_details.status 不為 '0' 時拋出錯誤

requestCTBCPaymentRepay

請求 CTBC 重新付款。此函數會呼叫 createCtbcRepayRequest 取得支付資料，建立隱藏表單並自動提交，將使用者導向至 CTBC 支付頁面。

await requestCTBCPaymentRepay('ORDER_ID');
// 或指定支付方式
await requestCTBCPaymentRepay('ORDER_ID', 'PAYMENT_METHOD');

參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | order_id | string | Yes | 訂單 ID（'123'） | | payment_method | string | No | 支付方式（'ctbc_only'） |

錯誤處理：

• 當 GraphQL 回應包含錯誤時拋出錯誤
• 當支付資料不存在時拋出錯誤
• 當 success 為 false 時拋出錯誤並包含 error_message

Server Routes

模組會自動註冊以下服務端路由：

POST /ctbc/payment/callback

處理 CTBC 支付完成後的 Server-to-Server 回調。

行為：

• 接收 CTBC 回傳的資料，跳轉到 verification 頁面，並攜帶拿到的參數 /ctbc/payment/verification?merID=&URLEnc=。

Pages

模組會自動註冊以下頁面：

/ctbc/payment/verification

支付驗證頁面，用於跟後端獲取支付後的結果，並跳轉至結果頁。

類型定義

CreateCtbcPaymentRequestInput

支付請求輸入參數

interface CreateCtbcPaymentRequestInput {
  order_id: string;      // 訂單 ID
  auth_res_url: string;  // callback URL
}

CreateCtbcPaymentRequestOutput

支付請求回應

interface CreateCtbcPaymentRequestOutput {
  createCtbcPaymentRequest: {
    success: boolean;
    error_message: string;
    payment_data: {
      merID: string;
      URLEnc: string;
      auth_url: string;
    };
  };
}

ProcessCtbcPaymentResponseInput

支付回應處理輸入參數

interface ProcessCtbcPaymentResponseInput {
  merID: string;      // 商店代號
  URLResEnc: string;  // 加密回應資料
}

ProcessCtbcPaymentResponseOutput

支付回應處理輸出

interface ProcessCtbcPaymentResponseOutput {
  processCtbcPaymentResponse: {
    success: boolean;
    order_status: string;
    message: string;
    error_message: string;
    payment_details: {
      status: string;
      errcode: string;
    };
  };
}

CreateCtbcRepayRequestInput

重新付款請求輸入參數

interface CreateCtbcRepayRequestInput {
  order_id: string;         // 訂單 ID
  auth_res_url: string;     // callback URL
  payment_method?: string;  // 支付方式（選填）
}

CreateCtbcRepayRequestOutput

重新付款請求回應

interface CreateCtbcRepayRequestOutput {
  createCtbcRepayRequest: {
    success: boolean;
    error_message: string;
    payment_data: {
      merID: string;
      URLEnc: string;
      auth_url: string;
    };
  };
}

授權聲明

此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。