綁卡/快捷/定期付款串接

場景介紹

綁卡/快速/定期付款串接主要支援特店為顧客開通 SHOPLINE Payments 付款會員及綁定信用卡，綁定後顧客可直接使用綁定信用卡發起快速付款或定期扣款，無須重複輸入信用卡資訊：

查看該模式支援的主要場景

1. 純綁卡（CardBind）: 主要在非付款場景下提供顧客預先綁定信用卡操作，用於快速付款及定期扣款操作
2. 付款並綁卡（CardBindPayment）: 主要在付款場景下提供顧客付款後直接綁定信用卡操作，用於快捷付款及定期扣款操作
3. 快捷付款（QuickPayment）: 顧客在場時，對綁定的信用卡透過付款工具 ID（paymentInstrumentId）直接進行付款，無需輸入卡資訊
4. 定期扣款（Recurring）: 顧客不在場時，對顧客授權綁定的信用卡透過付款工具 ID（paymentInstrumentId）扣款

提醒

同一個顧客重複綁定相同的卡片時， SHOPLINE Payments 不會產生重複的付款工具和 ID，會重複綁定第一次綁定的付款工具資訊

系統互動過程

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. 網站後台查看特店申請後 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 交易結果狀態及顧客付款資訊；

1. 會員通知介面，用於接收 SHOPLINE Payments 為顧客開通的付款會員資訊，特店需儲存付款會員 ID（paymentCustomerId）;
2. 付款工具通知介面，用於接收顧客在 SHOPLINE Payments 為付款會員下綁定的卡資訊，特店需儲存付款工具 ID（paymentInstrumentId）;

範例：

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"}'

6.（可選）根據業務需要，可串接【會員】和【付款工具】介面，用於維護顧客在 SHOPLINE Payments 的會員和綁定卡資訊；

會員API

1. 建立會員: 用於為顧客預先開通SHOPLINE Payments會員，獲取paymentCustomerId;
2. 更新會員:: 用於更新顧客在SHOPLINE Payments開通的會員訊息；
3. 註銷會員: 用於註銷顧客在SHOPLINE Payments的會員訊息；
4. 查詢會員: 查詢顧客在SHOPLINE Payments的會員訊息；
5. 會員授權: 用於快捷支付場景，通過paymentCustomerId獲取授權customerToken；

支付工具API

1. 建立支付工具: 用於為顧客預在SHOPLINE Payments開通的會員綁定信用卡，獲取paymentInstrumentId;
2. 解綁支付工具: 用於註銷顧客在SHOPLINE Payments會員綁定的信用卡；
3. 查詢支付工具: 查詢顧客在SHOPLINE Payments的會員下綁定的信用卡訊息；

3.引入 JS SDK

特店 Web 端需引進 JS SDK 進行 SHOPLINE Payments 收銀台呈現，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>

4.發起交易與付款

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

4.1 發起純綁卡或直接付款並綁卡

1. 初始化收銀台（此步驟需要傳入 merchantId 和 clientKey）

import ShoplinePayments from '@shoplinepayments/payment-web'

const { payment, error } = await ShoplinePayments({
   clientKey: '***YOUR**CLIENT**KEY***',
   merchantId: '***YOUR**MERCHANTID***',
   paymentMethod: 'CreditCard',
   currency: 'TWD',
   amount: 10000,
   // 提前建立的 HTMLElment
   element: '#paymentContainer',
   // 會員付款工具配置
   paymentInstrument: {
     // 綁卡配置
     bindCard: {
       // 是否開啟綁卡，必須為 true，才能開啟綁卡
       enable: true,
       // 綁卡協定配置
       protocol: {
         // 新增綁定卡號時，是否顯示接受綁卡協定勾選框
         switchVisible: true,
         // 新增綁定卡號時，接受綁卡協定勾選方塊是否預設勾選
         defaultSwitchStatus: true,
         // 新增綁定卡號時，使用者是否必須接受綁卡協議
         mustAccept: true,
         // 綁卡協定顯示
         textType: {
           // 新增綁定卡號時是否顯示"信用卡交易協議"相關文本，預設true
           paymentAgreement: true,
           // 是否顯示"定期購信用卡代扣協議"相關文本，預設true
           subscribeAgreement: true,
         },
       },
     },
   },
})
// 需判斷回應是否包含錯誤訊息，若無，才能進行下一步
if (error) {
   // 驗證錯誤碼和錯誤訊息，
   const { message, code } = error
} else {
   // 建立PaySession
}

2. 當顧客發起結帳動作時，參照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
} 
// 發起付款

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

相關欄位說明

1. 若顧客未開立透過建立 SLP 付款會員，SHOPLINE Payments 會根據介面中 customer.referenceCustomerId 建立付款會員 ID（paymentCustomerId）;
2. 綁卡場景下，介面 confirm.paymentBehavior 欄位填入 CardBind（純綁卡）或 CardBindPayment（付款綁卡），confirm.paymentInstrument.savePaymentInstrument 填入 true;

依據上述欄位設定後，進行以下動作:

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

範例：

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 電文結構'

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

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

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

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

4.2 已綁卡顧客發起快捷付款

1. 獲取顧客支付工具授權，初始化SDK

1. 如需 JS-SDK 呈現目前顧客歷史已綁定的卡片列表用於付款，在 SDK 初始化動作前，特店 Server 端需透過會員授權介面取得顧客臨時 customerToken ;
2. 初始化收銀台，完成 SDK 初始化動作 （此步驟需要傳入 merchantId 和 clientKey 和 customerToken）

import ShoplinePayments from '@shoplinepayments/payment-web'

const { payment, error } = await ShoplinePayments({
   clientKey: '***YOUR**CLIENT**KEY***',
   merchantId: '***YOUR**MERCHANTID***',
   paymentMethod: 'CreditCard',
   currency: 'TWD',
   amount: 10000,
   // 提前建立的 HTMLElment
   element: '#paymentContainer',
   // 從 API 取得的會員 token
   customerToken: '***GET**FROM**API***',
   // 會員付款工具配置
   paymentInstrument: {
     // 綁卡配置
     bindCard: {
       // 是否開啟綁定卡，必須為 true，才能使用 customerToken
       enable: true,
       // 綁卡協定配置
       protocol: {
         // 新增綁定卡號時，是否顯示接受綁卡協定勾選框
         switchVisible: true,
         // 新增綁定卡號時，接受綁卡協定勾選方塊是否預設勾選
         defaultSwitchStatus: true,
         // 新增綁定卡號時，使用者是否必須接受綁卡協議
         mustAccept: true,
         // 綁卡協定顯示
         textType: {
           // 新增綁定卡號時是否顯示"信用卡交易協議"相關文本，預設true
           paymentAgreement: true,
           // 是否顯示"定期購信用卡代扣協議"相關文本，預設true
           subscribeAgreement: true,
         },
       },
     },
   },
})
// 需判斷回應是否包含錯誤信息，若無，才能進行下一步
if (error) {
   // 驗證錯誤碼和錯誤信息，
   const { message, code } = error
} else {
   // 建立PaySession
}

2. 當顧客發起結帳動作時，參照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
} 
// 發起付款

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

相關欄位說明

1. 介面 confirm.paymentBehavior 欄位填入 QuickPayment;
2. 介面 confirm.paymentCustomerId 必填；

依據上述欄位設定後，進行以下動作:

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

範例：

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 電文結構'

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

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

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

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

4.3 特店對已綁卡顧客發起定期扣款

1. 使用【建立付款交易】介面，建立付款交易並付款；

相關欄位說明

1. 介面 confirm.paymentBehavior 欄位填入：Recurring;
2. 介面 confirm.paymentCustomerId 和 confirm.paymentInstrument.paymentInstrumentId 必填;
3. 介面 confirm.autoConfirm 與介面 confirm.autoCapture 參數皆填入：true;

範例：

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 電文結構'

5.取得交易結果

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

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

6.交易退款

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

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

7.付款工具維護

1. 如顧客需要解除 SHOPLINE Payments 綁定的卡，特店 Server 端透過解綁付款工具介面啟動解綁操作
2. 特店 Server 端可透過付款工具列表查詢介面，查詢會員下綁定的付款工具資訊；