LINE Pay 整合模組使用指南

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

概覽

LINE Pay 整合模組為 Nuxt 應用程式提供完整的 LINE Pay 支付功能，包括支付請求、確認支付、取消支付及回調處理等功能。模組設計簡潔易用，支援 Vue Storefront 中介層整合，並提供完整的 TypeScript 型別支援。

系統需求

• Node.js >= 20.0.0
• Nuxt >= 3.0.0 或 4.0.0
• Vue Storefront SDK >= 3.2.0
• pnpm >= 10.0.0

安裝與設定

1. 安裝套件

在 apps/web 和 apps/server 安裝

yarn add @astralweb/nova-line-pay

2. 註冊模組

在 nuxt.config.ts 中註冊模組

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

3. Middleware 擴充

將 LINE Pay API 方法擴充到 Vue Storefront middleware

// apps/server/extendApiMethods/index.ts

// ... 略
export {
  requestLinePayPayment,
  confirmLinePayPayment,
  cancelLinePayPayment,
} from '@astralweb/nova-line-pay/api';

基本使用

在結帳流程中使用

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

  const linePayData = await requestLinePay({ order_id: data.number });
  localStorage.setItem('lastOrderNumber', data?.number);
  location.href = linePayData.payment_url;
};
</script>

重新付款

<!-- OrderDetailPageContent.vue -->
<script setup lang="ts">
const { requestLinePay } = useLinePay();
const handleLinePayRepay = async () => {
  const linePayData = await requestLinePay({ order_id: number.vue });
  localStorage.setItem('lastOrderNumber', number.vue);
  location.href = linePayData.payment_url;
}
</script>

Composables API

useLinePay

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

const { requestLinePay, confirmLinePay, cancelLinePay } = useLinePay();

返回值

| 名稱 | 類型 | 說明 | | --- | --- | --- | | requestLinePay | Function | 請求 LINE Pay 支付的非同步函數 | | confirmLinePay | Function | 確認 LINE Pay 支付的非同步函數 (Server-side) | | cancelLinePay | Function | 取消 LINE Pay 支付的非同步函數 (Server-side) |

requestLinePay

請求 LINE Pay 支付

const linePayData = await requestLinePay({ order_id: 'ORDER_ID' });

參數：

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

返回值：

{
  success: boolean;        // 請求是否成功
  payment_url: string;     // LINE Pay 支付頁面 URL
  error_message: string;   // 錯誤訊息（如果有）
}

錯誤處理：

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

confirmLinePay

確認 LINE Pay 支付（僅用於 Server-side）

⚠️ 注意： 此方法僅能在伺服器端使用，因為需要存取 RuntimeConfig 和 H3Event。

const { confirmLinePay } = useLinePay();

// 在 server route 中使用
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);
  
  await confirmLinePay(config, event, {
    transaction_id: 'TRANSACTION_ID',
    order_id: 'ORDER_ID'
  });
});

參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | config | RuntimeConfig | Yes | Nuxt Runtime Config | | event | H3Event | Yes | H3 Event 物件 | | input | ConfirmLinePayPaymentInput | Yes | 確認支付輸入參數 | | input.transaction_id | string | Yes | LINE Pay 交易 ID | | input.order_id | string | Yes | 訂單 ID |

返回值：

{
  errors?: Array<{
    message: string;  // 錯誤訊息
    code: string;     // 錯誤代碼
  }>;
}

錯誤處理：

• 當 GraphQL 回應包含錯誤時拋出錯誤
• 當 errors 陣列不為空時拋出錯誤並包含錯誤訊息

cancelLinePay

取消 LINE Pay 支付（僅用於 Server-side）

⚠️ 注意： 此方法僅能在伺服器端使用，因為需要存取 RuntimeConfig 和 H3Event。

const { cancelLinePay } = useLinePay();

// 在 server route 中使用
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event);
  
  await cancelLinePay(config, event, {
    order_id: 'ORDER_ID'
  });
});

參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | config | RuntimeConfig | Yes | Nuxt Runtime Config | | event | H3Event | Yes | H3 Event 物件 | | input | CancelLinePayPaymentInput | Yes | 取消支付輸入參數 | | input.order_id | string | Yes | 訂單 ID |

返回值：

{
  errors?: Array<{
    message: string;  // 錯誤訊息
    code: string;     // 錯誤代碼
  }>;
}

錯誤處理：

• 當 GraphQL 回應包含錯誤時拋出錯誤
• 當 errors 陣列不為空時拋出錯誤並包含錯誤訊息

Server Routes

模組會自動註冊以下服務端路由來處理 LINE Pay 的回調：

GET /line_pay/payment/confirm

處理 LINE Pay 支付成功的回調

Query 參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | transactionId | string | Yes | LINE Pay 交易 ID | | orderId | string | Yes | 訂單 ID |

行為：

1. 接收 LINE Pay 回調參數
2. 調用 confirmLinePay 方法通知後端確認支付
3. 重定向到成功頁面
   • 預設路徑：/order/success
   • 多語系支援：/{locale}/order/success（需要 multiLocales 設定）

錯誤處理：

• 即使確認失敗，仍會重定向到成功頁面
• 錯誤會記錄在 console

自訂回調邏輯：

如需自訂回調處理邏輯，可在專案中創建同名路由檔案來覆蓋預設行為：

// apps/web/server/routes/line_pay/payment/confirm.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const { transactionId, orderId } = query;
  
  // 自訂邏輯
  console.log('LINE Pay confirmed:', { transactionId, orderId });
  
  // 自訂重定向
  return sendRedirect(event, '/custom-success-page');
});

GET /line_pay/payment/cancel

處理 LINE Pay 支付取消的回調

Query 參數：

| 參數名稱 | 類型 | Required | 說明 | | --- | --- | --- | --- | | orderId | string | Yes | 訂單 ID |

行為：

1. 接收 LINE Pay 回調參數
2. 調用 cancelLinePay 方法通知後端支付失敗
3. 重定向到失敗頁面
   • 預設路徑：/order/failed
   • 多語系支援：/{locale}/order/failed（需要 multiLocales 設定）

錯誤處理：

• 即使取消失敗，仍會重定向到失敗頁面
• 錯誤會記錄在 console

自訂回調邏輯：

如需自訂回調處理邏輯，可在專案中創建同名路由檔案來覆蓋預設行為：

// apps/web/server/routes/line_pay/payment/cancel.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event);
  const { orderId } = query;
  
  // 自訂邏輯
  console.log('LINE Pay cancelled:', { orderId });
  
  // 自訂重定向
  return sendRedirect(event, '/custom-failed-page');
});

類型定義

模組提供完整的 TypeScript 型別定義，可從 @astralweb/nova-line-pay/types 匯入：

import type {
  RequestLinePayPaymentInput,
  RequestLinePayPaymentOutput,
  ConfirmLinePayPaymentInput,
  ConfirmLinePayPaymentOutput,
  CancelLinePayPaymentInput,
  CancelLinePayPaymentOutput,
  LinePayPaymentMutationError,
} from '@astralweb/nova-line-pay/types';

RequestLinePayPaymentInput

請求支付的輸入參數

interface RequestLinePayPaymentInput {
  order_id: string;  // 訂單 ID
}

RequestLinePayPaymentOutput

請求支付的回應

interface RequestLinePayPaymentOutput {
  requestLinePayPayment: {
    success: boolean;          // 請求是否成功
    payment_url: string;        // LINE Pay 支付頁面 URL
    error_message: string;      // 錯誤訊息（如果有）
  };
}

ConfirmLinePayPaymentInput

確認支付的輸入參數

interface ConfirmLinePayPaymentInput {
  transaction_id: string;  // LINE Pay 交易 ID
  order_id: string;        // 訂單 ID
}

ConfirmLinePayPaymentOutput

確認支付的回應

interface ConfirmLinePayPaymentOutput {
  confirmLinePayPayment: {
    errors: LinePayPaymentMutationError[];  // 錯誤陣列（如果有）
  };
}

CancelLinePayPaymentInput

取消支付的輸入參數

interface CancelLinePayPaymentInput {
  order_id: string;  // 訂單 ID
}

CancelLinePayPaymentOutput

取消支付的回應

interface CancelLinePayPaymentOutput {
  cancelLinePayPayment: {
    errors: LinePayPaymentMutationError[];  // 錯誤陣列（如果有）
  };
}

LinePayPaymentMutationError

LINE Pay 支付錯誤物件

interface LinePayPaymentMutationError {
  message: string;  // 錯誤訊息
  code: string;     // 錯誤代碼
}

注意事項

多語系支援

模組會自動檢測 multiLocales 設定和 i18n_redirected cookie 來決定重定向路徑：

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      multiLocales: true,  // 啟用多語系路徑支援
    }
  }
});

當啟用多語系時，回調重定向路徑會包含語系前綴：

• 成功：/{locale}/order/success
• 失敗：/{locale}/order/failed

Middleware URL 映射

模組會自動根據當前請求的來源來決定 middleware URL：

1. 從 middlewareApiUrlMapping 設定中查找對應的 URL
2. 如果找不到，使用預設值 http://localhost:4000

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      middlewareApiUrlMapping: {
        'https://example.com': 'https://middleware.example.com',
        'https://staging.example.com': 'https://middleware-staging.example.com',
      }
    }
  }
});

授權聲明

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