導轉式付款串接

場景介紹

導轉式付款串接主要支援特店整合常用的付款方式，而無需串接SDK即可為顧客提供付款服務，支援的付款方式如下：

信用卡、信用卡分期（CreditCard）（僅包含一般付款交易，綁卡/快捷/定期付款請使用內嵌式串接）
ATM 銀行轉帳（VirtualAccount）
街口支付（JKOPay）
Apple Pay（ApplePay）
LINE Pay（LinePay）
中租 zingla 銀角零卡（ChaileaseBNPL）

結帳交易與付款交易的關係

結帳交易 Session 是協助特店/平台建立付款交易 Trade 的服務。下面會說明結帳交易和付款交易之間的關係，理解後更加方便串接。

當特店/平台透過建立結帳交易API 建立一筆結帳交易 Session 時,特店/平台系統就會得到一個 Session URL，這個URL會需要特店/平台系統呈現給顧客查看。顧客就會看到下圖的 SHOPLINE Payments 金流付款頁面（畫面以中租 zingla 銀角零卡作為範例）。

當顧客選擇付款方式並填寫需要的資訊提交付款後，SHOPLINE Payments 就會協助建立所選擇的付款方式的一筆付款交易 Trade。後續的顧客的付款結果狀態會在付款交易 Trade 上更新，也會驅動結帳交易 Session 更新其結帳交易狀態。詳細可查看以下結帳交易和付款交易狀態的 Mapping 狀態機。

由於結帳交易 Session 是協助特店/平台建立付款交易 Trade 的服務，結帳交易本身並不具有處理退款的功能，若需要處理退款，需要透過建立退款交易對付款交易本身進行退款，無法直接對結帳交易進行退款。

注意

在極端特殊場景下，一筆結帳交易 Session 會對應多筆付款交易 Trade，特店/平台應留意。以下舉例說明：

在顧客已經選擇其中一個付款方式並點擊付款後，顧客改變主意，點擊瀏覽器的「回上一頁」Button，回到 SHOPLINE Payments 金流付款頁面選擇其他付款方式進行付款。
在顧客已經選擇其中一個付款方式並點擊付款後，顧客臨時離開，導致付款交易逾時，但此時結帳交易尚未逾時。顧客點擊瀏覽器的「回上一頁」Button，回到 SHOPLINE Payments 金流付款頁面再次選擇付款方式進行付款。

另外也有可能出現結帳交易已經逾時但付款交易成功的狀況：

在顧客選擇 ATM 銀行轉帳並點擊付款後，取得虛擬帳號前往實體商店進行付款過程中，結帳交易逾時，但因虛擬帳號逾時時間以天為單位，有可能出現此狀況。
在通道異常狀況下，顧客付款結果未能及時通知 SHOPLINE Payments 系統，但在等待後SHOPLINE Payments 系統收到通道付款結果，此時若結帳交易逾時，付款交易未逾時，付款交易仍然會變為成功狀態，但結帳交易不會因此變為成功狀態。

系統互動過程

顧客在特店購物結帳，提交給特店/平台 Server 處理；
特店/平台請求建立結帳交易；
特店/平台 Server 回覆結帳交易相應所需的資訊（如SessionURL，金額，訂單資訊等）；
特店/平台跳转 SessionURL 介面，即SHOPLINE Payments 付款頁面；
顧客选择支付方式并填寫付款資訊（譬如信用卡卡號、CVV、和可能的身份驗證資訊）；
顧客點擊結帳提交付款資訊；
交易資訊傳輸；
SHOPLINE Payments 系統同步回覆結帳交易結果，特店/平台可透過Webhook非同步取得後台結帳交易結果通知，或主动查询結帳交易结果；

技術串接過程

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

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

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

2.引入 Server-API

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

提醒

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

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

請求電文範例

curl --location 'https://api-sandbox.shoplinepayments.com/api/v1/trade/sessions/create' \
--header 'merchantId: Your merchantId' \
--header 'apiKey: Your apiKey' \
--header 'requestId: Your requestId' \
--header 'Content-Type: application/json' \
--data-raw '{
    "referenceId": "Your referenceId",
    "mode": "regular",
    "language": null,
    "amount": {
        "value": 100,
        "currency": "TWD"
    },
    "expireTime": null,
    "returnUrl": "Your returnUrl",
    "allowPaymentMethodList": [
        "CreditCard","ApplePay"
    ],
    "paymentMethodOptions": {
        "CreditCard": {
            "installmentCounts": [
                "3",
                "6"
            ]
        }
    },
    "order": {
        "products": [
            {
                "amount": {
                    "currency": "TWD",
                    "value": 100
                },
                "quantity": 1,
                "id": "10001",
                "name": "iPhone15"
            }
        ],
        "shipping": {
            "personalInfo": {
                "firstName": "Bernie",
                "lastName": "Pope",
                "email": "shipping@gmail.com"
            },
            "address": {
                "countryCode": "TW",
                "street":"敦化北路170號10樓 A室, 松山區台北市台灣 105"
            },
            "shippingMethod": "宅配",
            "carrier": "黑貓宅配"
        }
    },
    "customer": {
        "referenceCustomerId": "referenceCustomerId",
        "personalInfo": {
            "firstName": "Bernie",
            "lastName": "Pope",
            "email": "shipping@gmail.com"
        }
    },
    "client": {
        "ip": "127.0.0.1"
    },
    "billing": {
        "personalInfo": {
            "firstName": "Bernie",
            "lastName": "Pope",
            "email": "shipping@gmail.com"
        },
        "address": {
            "countryCode": "TW",
            "street":"敦化北路170號10樓 A室, 松山區台北市台灣 105"
        }
    }
}'

回應電文範例

{
    "amount": {
        "currency": "TWD",
        "value": 100
    },
    "sessionId": "se_01022502286885089464780754095",
    "referenceId": "1740711421",
    "status": "CREATED",
    "sessionUrl": "https://api-sandbox.shoplinepayments.com/checkout/session?sessionToken=xxxx",
    "createTime": "1740711420842"
}

如果出現問題，我們會回應錯誤：

{
   "code": "1018",
   "msg": "Business error"
}

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":"session.succeeded","created":1629169257000,"data":""}'

3. 串接【結帳交易查詢】介面，用於主動查詢結帳交易狀態;

請求電文範例

curl --location 'https://api-sandbox.shoplinepayments.com/api/v1/trade/sessions/query' \
--header 'merchantId: Your merchantId' \
--header 'apiKey: Your apiKey' \
--header 'requestId: Your requestId' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId":"se_01022502186870973498211737653"
}'

回應電文範例

{
    "amount": {
        "currency": "TWD",
        "value": 100
    },
    "sessionId": "se_01022502286885089464780754095",
    "referenceId": "1740711421",
    "status": "CREATED",
    "sessionUrl": "https://api-sandbox.shoplinepayments.com/checkout/session?sessionToken=xxxx",
    "createTime": "1740711420842"
}

3.特店/平台跳轉 SessionURL

參照【結帳交易查詢】電文結構,取得 sessionUrl 並跳轉至該連結。

請注意

我們強烈建議，不要將 sessionUrl 在 iFrame 元素中打開，或使用 window.open打開該連結，因為這有可能會導致不可預見的問題。

若開啟連結時顯示錯誤訊息「抱歉，當前訂單可能出現一些狀況，請確認付款情況並稍後重試」，通常是因直接存取頁面導致瀏覽器的 document.referrer 為空值所引發。此屬性用於記錄使用者是透過哪個網頁連結跳轉至當前頁面，若未經正常流程（例如直接輸入網址或透過書籤存取），該值會顯示為空字串，進而觸發系統驗證失敗。

詳情請參照 Web API。

請參照以下程式碼打開此連結：

window.location.href = sessionUrl 

4.取得交易結果

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

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

提醒

如果您需要接收詳細付款方式付款人資訊，如信用卡付款交易的卡號前六位和後四位，或虛擬帳號付款交易的付款人轉出帳號等，則需要額外訂閱付款交易通知介面，或主動使用從結帳交易介面回覆的 tradeOrderId 來查詢付款交易查詢介面，主動查詢結帳交易下的付款交易結果。

請留意，如果您同時訂閱了結帳交易通知介面和付款交易通知介面，若有顧客進行相應的付款動作，您會同時收到來自兩個介面的通知，請務必正確處理。

6.交易退款

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

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

導轉式付款串接

場景介紹​

結帳交易與付款交易的關係​

系統互動過程​

技術串接過程​

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

2.引入 Server-API​

3.特店/平台跳轉 SessionURL​

4.取得交易結果​

6.交易退款​