使用說明

此 SDK 適用於前端 Web 場景，為特店提供在網店內進行交易的功能，在信用卡付款方式上無需跳轉。

1. 引入 JS SDK

提供 npm 和 cdn 兩種方式

NPM

npm
Yarn
pnpm

npm install @shoplinepayments/payment-web

yarn add @shoplinepayments/payment-web

pnpm add @shoplinepayments/payment-web

在項目中使用

import ShoplinePayments from '@shoplinepayments/payment-web'

CDN

複製以下代碼，通過 CDN 地址引入 ShoplinePayments JS-SDK

<script src="https://cdn.shoplinepayments.com/sdk/v1/payment-web.js"></script>

在項目中直接使用 window.ShoplinePayments

2. 準備容器

在呈現SDK 前，需要先準備一個內容為空的容器元素，如：元素 id 为 paymentContainer。代碼範例如下：在 HTML 中寫入：

<div id="paymentContainer"></div>

準備好容器元素後，通過下面步驟在容器中呈現收銀台。

3. 初始化

初始化時根據傳入的 merchantId 、paymentMethod 等參數在 SLP 內部校驗特店收款狀態是否正常，同時判斷當前瀏覽器環境是否支援該付款方式等。完成校驗後，SDK 在容器 paymentContainer 呈現收銀台介面。等呈現完成後，初始化也就完成了，之後才能進行後續步驟。建立了 payment 實例（下面也稱為 Payment 實例），並呈現出付款畫面。

const { payment, error } = await ShoplinePayments({
  clientKey: '***YOUR**CLIENT**KEY***',
  merchantId: '***YOUR**MERCHANTID***',
  // 指定付款方式
  paymentMethod: 'CreditCard',
  // 交易幣種，目前僅支援 TWD
  currency: 'TWD',
  // 此為真實付款金額，台幣傳金額*100，譬如1元傳入100
  amount: 10000,
  // 此處寫入已建立好的容器元素 selector
  element: '#paymentContainer',
  // 使用環境，預設為 production，若使用沙盒環境，請傳入 sandbox
  env: 'sandbox',
})
// 需判斷回應是否包含錯誤資訊，若無，才能進行下一步
if (error) {
  // 驗證錯誤碼和錯誤資訊，
  const { message, code } = error
  return
}
// 建立 PaySession

更多說明

關於初始化參數的更多說明請看：初始化參數說明

一旦在初始化過程中出錯，收銀台的位置會呈現出一個錯誤界面，並傳回相應的錯誤訊息。可以參照：SDK 錯誤碼，建議不要直接顯示錯誤訊息給顧客。

4. 建立 paySession

等顧客完成輸入後，點選結帳按鈕時，馬上呼叫 payment.createPayment() 介面取得 paySession ，用於透傳給SLP Server 端來建立交易單，該物件不可以解析。在特店 Server 端呼叫建立付款交易介面時，paySession 為必填欄位。建立付款交易介面請查閱：建立付款交易。

const { paySession, error } = await payment.createPayment()
// 需判斷回應是否包含錯誤資訊，若無，才能進行下一步
if (error) {
  // 驗證錯誤碼和錯誤資訊
  const { message, code } = error
  return
} 
//  Server 端呼叫建立付款交易介面
const { nextAction } = await createOrderFromServer(paySession)
// 需判斷回應是否包含 nextAction，若包含，才能進行下一步
if (!nextAction) {
  // 建立付款交易失敗，顯示錯誤資訊
  return
} 
// 發起付款

注意

SDK 內部會校驗顧客輸入是否正確，若輸入錯誤，會在 error 欄位回傳錯誤資訊。只有當顧客輸入正確後，才會回傳 paySession。 createPayment() 請務必在顧客點擊事件後呼叫，否則在付款方式 ApplePay 上可能導致建立 paySession 失敗。

5. 發起付款

呼叫 payment.pay() 發起付款。其中 nextAction 必填，該參數來自上文提到的建立付款交易 createOrder() 的回應。為明文資訊，注意不要解析、使用裡面的結構，數據類型隨時可發生變化。

const payResult = await payment.pay(nextAction)
// 付款成功時，payResult 為 undefined, 付款失敗時才有 error
if (payResult && payResult.error) {
  // 驗證錯誤碼和錯誤資訊
  const { message, code } = error
}

Note

請務必等待呼叫結束後，再做處理發起 pay() 之後，會出現以下 3 種情況：

正常回應，則介面跳到 return_url（該值在呼叫 SLP 建立付款交易介面時傳遞）制定的 url 上。
正常回應，SLP智慧風控系統要求 3D 驗證，這時需要跳轉到渠道製定的 3D 驗證頁面，完成驗證後，同樣跳轉到 return_url 中
錯誤回應，前面雖然有經過預校驗，但為了顧客體驗，該校驗並沒有請求到銀行（多一個遠端請求，訂單的建立會慢幾秒鐘，而且大部分通道並不提供這種校驗），但在付款時（如授權、請款等），必須請求到銀行，這時可能觸發錯誤，錯誤碼可以參照：SDK 錯誤碼。

以上就是一次付款的建立。你可以透過閱讀後續章節來了解其他付款方式的建立付款的流程。在充分測試後就可部署到正式環境。

Demo

下載 Node.js Demo

其他 API

更新

可透過呼叫 payment.update() 更新 SDK 顯示的多語言或付款金額，此時會保留顧客輸入。

const updateResult = await payment.update({
   language: 'en',//SDK顯示語言，此處指更新成英文
   amount: 300000,// 此為真實付款金額，台幣傳金額*100，譬如1元傳入100。此處指付款金額更新到 3000 台幣
})

// 更新失敗
// 更新成功時 updateResult 為 undefined, 更新失敗時才有 error
if (updateResult && updateResult.error) {
   // 驗證錯誤碼和錯誤資訊
   const { message, code } = error
}

注意

當更新的付款金額比較大，觸發大額交易驗證時，SDK 會補充渲染身份資訊的輸入框，並保留原有的已經輸入的資訊。
當更新的付款金額超出付款方式可以支援的金額，SDK 會變更為暫無法支援的樣式，此時不會保留之前顧客的輸入資訊。

銷毀

可透過呼叫 payment.destroy() 銷毀實例和所有 SDK 所建立的元素。

payment.destroy()

注意

第二步建立的容器并不会被销毁，根據業務需要判斷是否需要銷毀該容器。

使用說明

1. 引入 JS SDK​

NPM​

CDN​

2. 準備容器​

3. 初始化​

4. 建立 paySession​

5. 發起付款​

Demo​

其他 API​

更新​

銷毀​