一般付款串接

場景介紹

一般付款串接主要支援特店整合常用的付款方式為顧客提供付款服務，支援的付款方式如下：

1. 信用卡、信用卡分期（CreditCard）
2. ATM 銀行轉帳（VirtualAccount）
3. 街口支付（JKOPay）
4. Apple Pay（ApplePay）
5. LINE Pay（LinePay）
6. 中租 zingla 銀角零卡（ChaileaseBNPL）

系統互動過程

1. 顧客在特店購物結帳，提交給特店/平台 Server 處理；
2. 特店/平台 Server 回覆 SDK 所需的資訊（如金額，訂單資訊等）；
3. 特店/平台請求 SDK 初始化；
4. 特店/平台初始化並呈現 SDK 介面；
5. 顧客填寫付款資訊（譬如信用卡卡號、CVV、和可能的身份驗證資訊）；
6. 顧客點擊結帳提交付款資訊；
7. 交易資訊傳輸

   7.1. 如果是信用卡 3D 交易，還需要進行 3D 驗證，參照圖中信用卡 3D 流程；
   7.2. 如果是信用卡非 3D 交易，則直接回覆結果，參照圖中信用卡非 3D 流程；
   7.3. 如果是非信用卡的其他付款方式交易，則會跳轉到對應付款方式的頁面，進行付款動作，如掃碼或者付款資訊確認等。參照圖中其他付款方式流程；

8. 非同步獲取後台通知，或主动查询交易结果，收到非同步通知需要回覆收到給 SLP；

技術串接過程

1.取得特店 MerchantID 和產生金鑰

特店需在 SHOPLINE Payments 網站進行申請，取得技術串接資訊進行後續技術串接流程

1. Payment Center 後台查看特店申請後 SHOPLINE Payments 產生的唯一 MerchantId
2. 聯繫業務窗口取得串接金鑰 clientKey 及 apiKey

2.引入 Server-API

特店 Server 端需引進 Server-API 進行交易流程串接，當顧客在頁面啟動商品付款結帳時，配合 JS-SDK 作業完成付款流程串接 （此流程會使用 merchantId 和 apiKey）

提醒

此過程前需先閱讀 API 清單 規格，以了解 Server-API 串接機制

1. 串接【建立付款交易】介面，用於建立 SHOPLINE Payments 付款交易；

範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/create
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '參照 API 電文結構'

2. 串接【交易通知】介面，用於接收 SHOPLINE Payments 交易結果狀態及顧客付款資訊；

範例：

curl {callbackUrl}
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-H "timestamp: 1629169157000" 
-H "sign: : DSAJJK2JDKSJAKJKJK289812JKJDKSAJKJDSKAJ" 
-X POST -d '{"id":"100022738271872112212","type":"trade.succeeded","created":1629169257000,"data":""}'

3. 串接【建立退款交易】介面，用於對付款交易發起退款操作；

範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/refund/create
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '{"referenceOrderId":"10003211827187211","tradeOrderId":"10020092625074642033411092480","amount":{"value":10000,"currency":"TWD"}}'

4. 串接【付款交易查詢】和【退款交易查詢】介面，用於主動查詢付款交易和退款交易狀態;

付款交易查詢範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/get
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '{"tradeOrderId":"10020092625074642033411092480"}'

退款交易查詢範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/refund/get
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '{"refundOrderId":"10030092625074642033411092480"}'

5.（可選）依業務需要，可串接【交易請款】和【交易取消】介面，用於主動發起交易請款和取消交易；

交易請款範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/capture
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '{"tradeOrderId":"10020092625074642033411092480","amount":{"value":10000,"currency":"TWD"}}'

交易取消範例：

curl https://api-sandbox.shoplinepayments.com/api/v1/trade/payment/cancel
-H "Content-Type: application/json" 
-H "merchantId: 1000021" 
-H "apiKey: slp_test_4eC39HqLyjWDarjtT1zdp7dc" 
-H "requestId: 10002273827187211" 
-X POST -d '{"tradeOrderId":"10020092625074642033411092480"}'

3.引進 JS SDK

特店 Web 端需引進 JS SDK 進行 SHOPLINE Payments SDK 呈現，SHOPLINE Payments 收銀台會收集顧客付款資訊完成付款流程 （此流程會使用 merchantId 和 clientKey）

提醒

特店的結帳頁面一定要給 SDK 留出框架位置，即使有部分付款方式在正常情況下不需要顧客輸入資訊。 但在大額交易的情況下， 有可能會需要顧客輸入身份證資訊。如果沒有收集大額交易資訊，交易會無法建立。

1. 参照SDK 串接引入 SDK 及容器準備

提供 NPM 和 CDN 兩種方式引入 sdk

NPM

在項目中安裝 SHOPLINE Payments Node package

npm

npm install @shoplinepayments/payment-web

Yarn

yarn add @shoplinepayments/payment-web

pnpm

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

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

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

2. 根據實際流程選擇合適的時機初始化收銀台並呈現（此步驟需要傳入 merchantId和 clientKey）

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

4.發起交易與付款

當顧客在頁面啟動商品付款結帳時，配合 JS-SDK 作業完成付款流程串接 （此流程會使用 merchantId 和 clientKey、apiKey）

1. 當顧客發起結帳動作時，參照SDK 串接 取得 paySession

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

2. 使用【建立付款交易】介面，建立付款交易，獲取tradeOrderId和nextAction資訊；

1. 將 paySession 發送到特店 Server 端，參照建立付款交易介面，建立 SHOPLINE Payments 交易，獲取 tradeOrderId（SLP 交易訂單號）及 nextAction 資訊
2. 將 SHOPLINE Payments 傳回的 tradeOrderId 儲存，以便於後續接收 SHOPLINE Payments 的 event 通知或主動查詢訂單狀態

3. 參照SDK 串接，發起付款（需傳入建立交易介面回應的 nextAction 資訊）

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

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

3.1 綁卡場景需要顧客進行 3DS 驗證，SDK 會自動指引顧客完成 3DS 驗證流程，特店無體感

5.取得交易結果

特店 Server 端可透過 SHOPLINE Payments 的交易通知介面非同步接收顧客付款結果，也可透過付款交易查詢介面主動查詢交易結果

1. 特店 Server 端非同步接收交易通知介面所傳送的付款結果
2. 特店 Server 端主動透過付款交易查詢介面，主動查詢交易結果

6.交易退款

特店 Server 端可透過 SHOPLINE Payments 的交易退款介面發起退款操作，同時透過退款通知非同步接收退款結果，也可透過退款交易查詢介面主動查詢退款結果

1. 特店 Server 端透過建立退款交易介面發起交易退款
2. 特店 Server 端非同步接收退款交易通知介面發送的退款結果
3. 特店 Server 端主動透過退款交易查詢介面，主動查詢退款結果