簡介
本章節將介紹LINE Pay商家功能。
LINE Pay簡介
本文件提供說明給欲整合LINE Pay功能的資訊軟體開發者。
- 圖1 LINE Pay Overview *
整合環境
本章節將介紹整合LINE Pay的環境需求及預先準備事項。
系統需求
LINE Pay的API通訊必須建構在LINE Pay伺服器與商家後端伺服器間。 因此商家端可能需另行架設付款伺服器來與LINE Pay API進行整合。
開始整合之前
在開始整合LINE Pay API之前,商家必須先註冊成為LINE Pay特約商店,並利用LINE Pay提供給特約商店的金鑰資訊整合LINE Pay付款API。
商家註冊
欲整合LINE Pay付款API必須先註冊成為LINE Pay特約商店。 如商家欲查詢註冊流程,可至LINE Pay商家網站下載註冊流程指南。 (下載位置: https://pay.line.me/developers/documentation/download/tech?locale=zh_TW - LINE Pay商家註冊指南)
整合環境準備
- 註冊商家付款伺服器IP至LINE Pay白名單 a. LINE Pay會限制頒發給每個LINE Pay特約商店Channel ID下的API通訊,只有註冊於白名單IP清單中的伺服器才允許與LINE Pay伺服器通訊。 b. 伺服器IP註冊可由以下位置完成註冊 - "登入LINE Pay商家中心(https://pay.line.me) - 管理付款連結 - 管理付款伺服器IP“。
- 確認Channel ID與Channel Secret a. Channel ID與Channel Secret是整合LINE Pay付款API的基本金鑰資訊,可在“登入LINE Pay商家中心(https://pay.line.me) - 管理付款連結 - 管理連結金鑰”終獲取。 b. 該金鑰資訊是LINE Pay單獨提供給特約商店具有獨特性的資訊,必須確保不會外洩於任何地方。
- 檢查可用於付款的貨幣 a. LINE Pay付款API整合時只能選擇一種貨幣,可用的貨幣如下,除此之外商家也可以在“登入LINE Pay商家中心(https://pay.line.me) - 管理基本資訊 - 管理商家資訊”中確認可付款的貨幣。
- JPY
- USD
- THB
- TWD
整合流程
Payment Sequence diagram
此圖敘述API付款訊息處理流程。
適用的API
- Payment API(sequence diagram - #4)
圖 2 Payment Sequence diagram
循序圖流程解釋
- LINE Pay用戶出示"我的條碼(一維/二維碼)"給商家掃描。
- 商店交易裝置讀取"我的條碼(一維/二維碼)"。
- 商店交易裝置傳送付款要求至商家付款伺服器。
- 商家付款伺服器傳送“線下付款API” Request至LINE Pay伺服器。
- 檢查API Response並確認付款是否已經完成。
- 商家付款伺服器回應付款結果至商店交易裝置。
- LINE Pay伺服器使用推播訊息或是LINE Pay官方帳號訊息通知LINE Pay用戶交易結果(成功/失敗)。
After Payment Sequence
付款程序完成後可執行的其他API程序只需傳送一次API Request即可完成。
適用的API
- VOID
- REFUND
- CAPTURE
- Authorization/Payment Details
API Specifications (Payment)
本章節將介紹使用LINE Pay用戶"oneTimeKey"進行線下付款的API功能(可由LINE Pay用戶主頁面"我的條碼"產生)。
- Payment
- Payment Status Check
Payment
此API為商店交易裝置讀取LINE Pay"我的條碼"後傳送付款要求所需的API。
Specification
表 1 Payment API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/oneTimeKeys/pay Product : https://api-pay.line.me/v2/payments/oneTimeKeys/pay |
Method | POST |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 2 Payment API Request Body
Name | Type | Mandatory | description |
---|---|---|---|
productName | string(4000) | Y | product name |
amount | number(38) | Y | amount to payment |
currency | string(3) | Y | currency to payment |
orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
oneTimeKey | string(19) | Y | Result of scanning and reading QR/Bar code information given by LINE Pay App. 12、18 or 19 digits oneTimeKey的有效時間為5分鐘,有效時間從LINE Pay用戶開啟"我的條碼"裡的QR/Bar code後開始計算。長度為12、18或19碼 |
capture | boolean | N | Whether to capture or not. A boolean value (true or false) default is true. true(default) : payment authorization and captrue are handled at once false : payment is completed only after it is authorized then separately capture by calling "Capture API" |
Extra Fields | |||
extras.addFriends | object[] | N | 加好友清單
"addFriends": [{ |
extras.branchName | string(200) | N | 需要付款的商店/分店名稱(僅會顯示前 100 字元) |
extras.branchId | String (32) | N | 需要付款的商店/分店ID。 支持字母,數字和特殊字符。 |
extras.promotionRestriction | object | N | 點數限制資訊
"promotionRestriction": { |
extras.events[] | object[] | N | 若訂單有符合與LINE Pay行銷合作的指定品項時帶入。 (目前一個訂單僅支援一組code) "events": [{ |
extras.events[].code | string(4-30) | N | 依照LINE Pay定義並提供之代碼,當商家訂單符合指定品項時帶入。 |
extras.events[].totalAmount | number | N | 定率合作:帶入此指定品項組合所符合的銷售金額 定額合作:帶入null |
extras.events[].productQuantity | number | N | 定率合作:帶入null 定額合作:帶入此指定品項組合所符合的組合數量 |
表 3 Payment API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay. - 0000 : API呼叫成功 -其他結果代碼可於 「附錄 - API Response代碼」 中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
info.transactionId | number(19) | Y | LINE Pay's transaction id |
info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT (發票金額須扣除) - POINT (預設不顯示) |
info.payInfo[].amount | number(38) | Y | payment amount |
info.balance | number(38) | N | remained balance after payment. |
info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' when the payment status is "AUTHORIZATION"(capture=false). * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.merchantReference.affiliateCards[].cardType | string | N | 交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認} |
info.merchantReference.affiliateCards[].cardId | string | N | 交易中若用戶符合商店支援的卡片類型所對應的內容值 |
Request
POST https://sandbox-api-pay.line.me/v2/payments/oneTimeKeys/pay HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
{
"productName": "test product",
"amount": 100,
"currency": "TWD",
"orderId": "merchant_test_order_1",
"oneTimeKey": "123456789012"
}
Response Body - 交易完成。
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"transactionId": "2016010112345678910",
"orderId": "test_order_#1",
"transactionDate": "2016-01-01T01:01:00Z",
"payInfo": [{
"method": "BALANCE",
"amount": 95
}, {
"method": "DISCOUNT",
"amount": 5
}],
"balance": 0
},
"events": [
{
"code": "alphanumeric",
"totalAmount": 500,
"productQuantity": null
},
{
"code": "alphanumeric2",
"totalAmount": null,
"productQuantity": 10
}
]
}
Payment Status Check
如果因為回應時間過長導致最終付款狀態無法確認時,請使用這支API
- 交易狀態應在固定的時間間隔中被檢查。
- 付款的有效期間為"線下付款API" Response時間後20分鐘內,因此商家最長應檢查交易狀態20分鐘。若超過20分鐘,該筆交易則被取消
Specification
表 4 Payment Status Check API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/check Product : https://api-pay.line.me/v2/payments/orders/{orderId}/check |
Method | GET |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 5 Payment Status Check API URI Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | Y | -商家進行交易時,傳遞的商家訂單編號。 - URI中的參數必須經過編碼才可傳送。 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
表 6 Payment Status Check API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | result code - 0000 : API呼叫成功 -其他結果代碼可於 「附錄 - API Response代碼」 中查看 |
returnMessage | string(100) | Y | result messages |
info.status | string(20) | Y | payment status - AUTH_READY : Wait for user confirmation. - COMPLETE : payment completed. - terminated status - FAIL : payment failed. - terminated status *注意:在狀態為「付款完成」或「付款失敗」時,將回應額外的資訊。 |
info.merchantReference.affiliateCards[].cardType | string | N | 交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認} |
info.merchantReference.affiliateCards[].cardId | string | N | 交易中若用戶符合商店支援的卡片類型所對應的內容值 |
case "info.status" : "COMPLETE" | |||
info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT (發票金額須扣除) - POINT |
info.payInfo[].amount | number(38) | Y | payment amount |
info.balance | number(38) | N | remained balance after payment. |
info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' when the payment status is "AUTHORIZATION"(capture=false). * reference : https://en.wikipedia.org/wiki/ISO_8601 |
case "info.status" : "FAIL" | |||
info.failReturnCode | string(4) | Y | Fail result code - 結果代碼可於 「附錄 - API Response代碼」 中查看 - 此結果代碼與「線下付款 API」的結果代碼相同 |
info.failReturnMessage | string(100) | Y | Fail result messages |
Request
- 如果「orderId」是「test_order_#1」
GET https://sandbox-api-pay.line.me/v2/payments/orders/test_order_%231/check HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
Response Body - 狀態為「付款完成」
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"status": "COMPLETE",
"transactionId": "2016010112345678910",
"orderId": "test_order_#1",
"transactionDate": "2016-01-01T01:01:00Z",
"payInfo": [{
"method": "BALANCE",
"amount": 95
}, {
"method": "DISCOUNT",
"amount": 5
}],
"authorizationExpireDate": "2016-01-01T01:01:00Z"
}
}
Response Body - 狀態為「付款失敗」
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"status": "FAIL",
"failReturnCode": "1142",
"failReturnMessage" : "Insufficient balance remains."
}
}
API Specifications (After Payment)
本章節將介紹用於付款完成後的退款及查詢交易紀錄等API,商家可根據交易歷史紀錄中的交易狀態來使用這些API。
- Void
- Capture
- Refund
- Authorization Details
- Payment Details
Void
此API用於進行授權作廢
Specification
表 7 Void API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/void Product : https://api-pay.line.me/v2/payments/orders/{orderId}/void |
Method | POST |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 8 Void API URI Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | Y | - 商家進行交易時,傳遞的商家訂單編號。 - URI中的參數必須經過編碼才可傳送 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
表 9 Void API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API呼叫成功 -其他結果代碼可於「附錄 - API Response代碼」中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
Request
- 如果「orderId」是「test_order_#1」
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_%231/void HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
Response - 交易完成
{
"returnCode": "0000",
"returnMessage": "Success."
}
Capture
此API用於對已取得授權的交易進行請款。
Specification
表 10 Capture API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/capture Product : https://api-pay.line.me/v2/payments/orders/{orderId}/capture |
Method | POST |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 11 Capture API URI Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | Y | - 商家進行交易時,傳遞的商家訂單編號。 - URI中的參數必須經過編碼才可傳送。 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
表 12 Capture API Request Body
Name | Type | Mandatory | description |
---|---|---|---|
amount | number(38) | Y | amount to capture |
currency | string(3) | Y | currency to capture |
Extra Fields | |||
extras.promotionRestriction | object | N | 點數限制資訊
"promotionRestriction": { |
表 13 Capture API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 呼叫成功 - 其他結果代碼可於「附錄 - API Response代碼」中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
info.transactionId | number(19) | Y | LINE Pay's transaction id |
info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT (發票金額須扣除) - POINT (預設不顯示) |
info.payInfo[].amount | number(38) | Y | payment amount |
Request
- 如果「orderId」是「test_order_#1」
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_%231/capture HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
{
"amount": 100,
"currency": "TWD"
}
Response
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"transactionId": "2016010112345678910",
"orderId": "test_order_#1",
"payInfo": [{
"method": "BALANCE",
"amount": 95
}, {
"method": "DISCOUNT",
"amount": 5
}]
}
}
Refund
此API對付款完成的項目進行退款。
Specification
表 14 Refund API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/refund Product : https://api-pay.line.me/v2/payments/orders/{orderId}/refund |
Method | POST |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 15 Refund API URI Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | Y | - 商家進行交易時,傳遞的商家訂單編號。 - URI中的參數必須經過編碼才可傳送。 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
表 16 Refund API Request Body
Name | Type | Mandatory | description |
---|---|---|---|
refundAmount | number(38) | N | amount to refund. - Full refund if this parameter is not passed |
Extra Fields | |||
extras.promotionRestriction | object | N | 點數限制資訊
"promotionRestriction": { |
表 17 Refund API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 呼叫成功 - 其他結果代碼可於 「附錄 - API Response代碼」 中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
info.refundTransactionId | number(19) | Y | LINE Pay's refund transaction id |
info.refundTransactionDate | string(20) | Y | Refunded Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
Request
- 如果「orderId」是「test_order_#1」
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_%231/refund HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
{
"refundAmount": 100
}
Response
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"refundTransactionId": "2016010112345678910",
"refundTransactionDate": "2016-01-01T01:01:00Z"
}
}
Authorization Details
此API用於查看已取得付款授權交易的交易記錄。只有授權或取消授權 (作廢或是過期) 的交易記錄才可使用此API查詢,已經請款的交易紀錄則需使用「查看付款紀錄 API」來查詢。
Specification
表 18 Authorizaiton Details API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/authrozations Product : https://api-pay.line.me/v2/payments/authorizations |
Method | GET |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 19 Authorization Details API Query Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | N | 商家進行交易時,傳遞的商家訂單編號 |
transactionId | number(19) | N | LINE Pay’s transaction id |
表 20 Authorization Details API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 呼叫成功 - 其他結果代碼可於 「附錄 - API Response代碼」 中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
info.transactionId | number(19) | Y | LINE Pay's transaction id |
info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.transactionType | String(20) | Y | Transaction Type - PAYMENT : payment - PAYMENT_REFUND : refund - PARTIAL_REFUND : partial refund |
info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT (發票金額須扣除) - POINT (預設不顯示) |
info.payInfo[].amount | number(38) | Y | Payment amount |
info.currency | string(3) | Y | Payment currency * reference : https://en.wikipedia.org/wiki/ISO_4217 |
info.productName | string( | Y | Product name |
info.payStatus | string(30) | Y | Payment status - AUTHORIZATION : 已授權 - VOIDED_AUTHORIZATION : 授權已作廢 (成功傳送「授權作廢 API)後的狀態) - EXPIRED_AUTHORIZATION : 授權已過期 (已超過允許的商家授權期限) |
info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
Request
GET https://sandbox-api-pay.line.me/v2/payments/authorizations?orderId=20160408003 HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
Response
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": [
{
"transactionId": 2016049910005498410,
"transactionDate": "2016-04-08T07:02:38Z",
"transactionType": "PAYMENT",
"productName": "test product",
"currency": "TWD",
"authorizationExpireDate": "2016-04-13T07:02:38Z",
"payInfo": [
{
"method": "BALANCE",
"amount": 100
}
],
"orderId": "20160408003",
"payStatus": "VOIDED_AUTHORIZATION"
}
]
}
Payment Details
此API用於查看已經請款的交易資料。
Specification
表 21 Payment Details API Endpoint
項目 | 說明 |
---|---|
Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments Product : https://api-pay.line.me/v2/payments |
Method | GET |
Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {Integration Information - channelId} - X-LINE-ChannelSecret: {Integration Information - channelSecretKey} 依照商家設定決定是否為必要的參數 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
Timeout | Read : 20秒 |
表 22 Payment Details API Query Parameters
Name | Type | Mandatory | description |
---|---|---|---|
orderId | string(100) | N | 商家進行交易時,傳遞的商家訂單編號 |
transactionId | number(19) | N | LINE Pay’s transaction id |
表 23 Payment Details API Response Body
Name | Type | Mandatory | description |
---|---|---|---|
returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 呼叫成功 -其他結果代碼可於「附錄 - API Response代碼」中查看 |
returnMessage | string(100) | Y | Result messages or reason for failure |
info.transactionId | number(19) | Y | LINE Pay's transaction id |
info.orderId | string(100) | Y | OrderId given by merchant device. - unique on merchant-side |
info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.transactionType | String(20) | Y | Transaction Type - PAYMENT : payment - PAYMENT_REFUND : refund - PARTIAL_REFUND : partial refund |
info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT (發票金額須扣除) - POINT (預設不顯示) |
info.payInfo[].amount | number(38) | Y | Payment amount |
info.currency | string(3) | Y | Payment currency * reference : https://en.wikipedia.org/wiki/ISO_4217 |
info.productName | string(4000) | Y | Product name |
Retrieving original transactions & When there is a refund | |||
info.refundList[].refundTransactionId | number(19) | Y | Refunded transaction id |
info.refundList[].transactionType | string(20) | Y | Transaction type - PAYMENT_REFUND : refund - PARTIAL_REFUND : partial refund |
info.refundList[].refundAmount | number(38) | Y | Refund amount |
info.refundList[].refundTransactionDate | String(20) | Y | Refunded transaction date (ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
info.merchantReference.affiliateCards[].cardType | string | N | 交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認} |
info.merchantReference.affiliateCards[].cardId | string | N | 交易中若用戶符合商店支援的卡片類型所對應的內容值 |
When retrieving a refund | |||
info.originalTransactionId | number(19) | Y | Original apymenttransaction number |
Request
GET https://sandbox-api-pay.line.me/v2/payments/?transactionId=2016049910005496810 HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceType: POS
X-LINE-MerchantDeviceProfileId: DUMMY
Response
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": [
{
"transactionId": 2016049910005496810,
"transactionDate": "2016-04-08T06:31:19Z",
"transactionType": "PAYMENT",
"productName": "test product",
"currency": "TWD",
"payInfo": [
{
"method": "BALANCE",
"amount": 100
}
],
"refundList": [
{
"refundTransactionId": 2016049910005497012,
"transactionType": "PARTIAL_REFUND",
"refundAmount": -1,
"refundTransactionDate": "2016-04-08T06:33:17Z"
}
],
"orderId": "20160408001"
}
]
}
附錄
Response代碼
本節定義了 LINE Pay 中的錯誤代碼。錯誤代碼的 returnMessage 以英文呈現,如果沒有訊息,則顯示連字號 (-)。
表 24 LINE Pay Response代碼
代碼(returnCode) | 說明(300byte) |
---|---|
0000 | 成功 |
1101 | 買家不是 LINE Pay 會員 |
1102 | 買方被停止交易 |
1104 | 找不到商家 |
1105 | 此商家無法使用 LINE Pay |
1106 | 標頭資訊錯誤 |
1110 | 無法使用的信用卡 |
1124 | 金額錯誤 (scale) |
1133 | 非有效之 oneTimeKey |
1141 | 付款帳戶狀態錯誤 |
1142 | 餘額不足 |
1145 | 正在進行付款 |
1150 | 找不到交易記錄 |
1152 | 已有既存付款 |
1153 | 付款reserve時的金額與申請的金額不一致 |
1155 | 交易編號不符合退款資格 |
1159 | 無付款申請資訊 |
1163 | 可退款日期已過無法退款 |
1164 | 超過退款額度 |
1165 | 交易已進行退款 |
1169 | 付款confirm所需要資訊錯誤(在LINE Pay) |
1170 | 使用者帳戶的餘額有變動 |
1172 | 已有同一訂單編號的交易履歷 |
1177 | 超過允許擷取的交易數目 (100) |
1178 | 不支援的貨幣 |
1179 | 無法處理狀態 |
1183 | 付款金額必須大於 0 |
1184 | 付款金額比付款申請時候的金額還大 |
1198 | 正在處理請求… |
1199 | 內部請求錯誤 |
1264 | 一卡通MONEY相關錯誤 |
1280 | 信用卡付款時候發生了臨時錯誤 |
1281 | 信用卡付款錯誤 |
1282 | 信用卡授權錯誤 |
1283 | 因疑似詐騙,拒絕付款 |
1284 | 暫時無法以信用卡付款 |
1285 | 信用卡資訊不完整 |
1286 | 信用卡付款資訊不正確 |
1287 | 信用卡已過期 |
1288 | 信用卡的額度不足 |
1289 | 超過信用卡付款金額上限 |
1290 | 超過一次性付款的額度 |
1291 | 此信用卡已被掛失 |
1292 | 此信用卡已被停卡 |
1293 | 信用卡驗證碼 (CVN) 無效 |
1294 | 此信用卡已被列入黑名單 |
1295 | 信用卡號無效 |
1296 | 無效的金額 |
1298 | 信用卡付款遭拒 |
1900 | 暫時錯誤,請稍候再試。 |
1901 | 暫時錯誤,請稍候再試。 |
1902 | 暫時錯誤,請稍候再試。 |
1903 | 暫時錯誤,請稍候再試。 |
1999 | 嘗試呼叫的資訊與前一次的資訊不符。 |
2101 | 參數錯誤 |
2102 | JSON 資料格式錯誤 |
2103 | 錯誤請求。請確認 returnMesage。 |
2104 | 錯誤請求。請確認 returnMesage。 |
9000 | 內部錯誤 |
各API Response代碼對照表
表 25 各API Response代碼對照表
錯誤代碼 | Payment | Payment status check | 請款 | 授權作廢 | 退款 | 授權履歷 | 付款紀錄 |
---|---|---|---|---|---|---|---|
1101 | v | v | v | ||||
1102 | v | v | v | ||||
1104 | v | v | v | v | v | v | v |
1105 | v | v | v | v | v | v | v |
1106 | v | v | v | v | v | v | v |
1110 | v | ||||||
1124 | v | v | |||||
1133 | v | ||||||
1141 | v | ||||||
1142 | v | ||||||
1145 | v | ||||||
1150 | v | v | v | v | v | v | |
1152 | v | ||||||
1153 | v | ||||||
1154 | |||||||
1155 | v | v | v | ||||
1159 | v | ||||||
1163 | v | ||||||
1164 | v | ||||||
1165 | v | ||||||
1170 | v | v | v | ||||
1172 | v | v | |||||
1177 | v | v | |||||
1178 | v | ||||||
1179 | v | v | v | ||||
1183 | v | v | |||||
1184 | v | v | |||||
1194 | v | ||||||
1198 | v | v | v | v | |||
1199 | v | v | v | v | |||
1264 | v | v | v | v | |||
1900 | v | v | v | ||||
1901 | v | ||||||
1902 | v | ||||||
1903 | v | ||||||
1999 | v | v | v | ||||
2101 | v | v | v | v | v | v | v |
2102 | v | v | v | v | v | v | v |
2103 | v | v | v | v | v | v | v |
2104 | v | v | v | v | v | v | v |
9000 | v | v | v | v | v | v | v |
Sandbox oneTimeKey 付款
Sandbox環境無法使用LINE Pay App的條碼付款
欲在Sandbox環境測試oneTimeKey,請使用以下網址產生的條碼
Sandbox MyCode url: https://sandbox-web-pay.line.me/web/sandbox/payment/oneTimeKey?countryCode=TW&paymentMethod=card&preset=1