Online APIs

OverView

LINE Pay

LINE Pay支付系統提供LINE用戶在LINE Pay商家網站進行交易。

LINE Pay支付流程

註冊為LINE Pay的商家，可以吸引全球的LINE用戶作為自己的客戶。此外，通過LINE擴展商家的銷售管道，可以預見銷售額的迅速成長。只有註冊為LINE Pay的商家，才能為LINE Pay用戶提供線上付款服務。

LINE Pay商家註冊流程

完成LINE Pay商家註冊後，將會提供用於Sandbox和Production環境的“Channel Id”和“Channel SecretKey”。商家的註冊流程如下。

註冊流程

1. 進入申請頁面（https://pay.line.me）
2. 輸入基本資料並提交必要文件
3. 商家審核
4. 同意手續費與結算週期規則，並輸入驗證用的PIN
5. 商家註冊完成
6. 發送註冊成功電子郵件

一般付款

LINE Pay用戶可以在LINE Pay付款頁面選擇付款方式（一卡通MONEY，信用卡，LINE POINTS）後，使用密碼驗證付款資訊。透過"Request API"中商家系統帶入的"confirmUrl"，跳轉到該頁面讓商家系統呼叫"Confirm API"完成付款。

PC環境

PC付款頁面-付款完成

1. 在LINE App的付款頁面，LINE Pay用戶選擇付款方式並輸入密碼。
2. 在選擇付款方式後，點擊付款按鈕啟用付款
3. LINE Pay用戶在LINE App確認付款資訊。
4. 在PC環境的等待付款頁面一旦收到用戶付款狀態成功，將會轉導至商家系統的“confirmUrl”。
5. 商家系統透過呼叫Confirm API來完成交易。

行動裝置環境

行動裝置環境-付款完成

1. 在LINE App的付款頁面，LINE Pay用戶選擇付款方式並輸入密碼。
2. 在選擇付款方式後，點擊付款按鈕啟用付款
3. LINE Pay用戶在LINE App確認付款資訊。點擊確認按鈕，將會轉導至商家系統的“confirmUrl”，
4. 商家系統透過呼叫Confirm API來完成交易。

授權與請款分開

當使用Confirm API確認付款時，會完成付款但進入授權等待請款狀態。在授權過期以前，LINE Pay會一直保持在等待請款狀態。而在授權過期以前，商家系統可以透過"請款Capture API)"將付款狀態轉換為已請款狀態。

• 確認請款：呼叫Capture API請款，完成交易。
• 取消請款：呼叫Void API，取消授權交易。

confirmUrl的Server-to-Server

在一般付款中，ConfirmUrl將使商家得知用戶已經確認完成付款，並提供用戶轉導至付款完成頁面。但是，如果付款完成的流程不需要用戶做轉導頁面，可以將redirectUrls.confirmUrlType設為"SERVER"，以讓LINE Pay Server直接呼叫ConfirmUrl通知以完成付款確認，而用戶不會轉導頁面。在用戶確認付款後，商家系統Server與LINE Pay Server透過Confirm API來完成所有付款流程。 其流程如下。

Server-to-Server傳輸confirmUrl

1. 商家將Request API的redirectUrls.confirmUrlType設為"SERVER"。
2. 在LINE App的付款頁面，LINE Pay用戶選擇付款方式並輸入密碼。
3. 在用戶確認付款後，LINE Pay Server將儲存付款資訊並呼叫商家提供的ConfirmUrl。
4. 商家系統Server呼叫Confirm API完成交易。如果ConfirmUrl回應有錯誤，則將無法呼叫Confirm API。

[Merchant API] confirmUrl

相關API

• Request API
• Confirm API

Checkout (Only Japan)

使用LINE Pay提供的各種支付方式，如帳戶餘額，信用卡，銀行帳戶，LINE POINTS和LINE會員資訊，會員可以很方便的處理付款和訂單。

Checkout Flow

Checkout flow

1. 商家呼叫Request API，向LINE Pay發出支付請求。商家可以透過將“shipping.type”設定為SHIPPING，以及提供LINE Pay可查詢配送方式與運費的Inquiry ShippingMethods API來啟用Checkout服務。
2. 透過Request API回傳的paymentUrl，可以進入LINE Pay支付頁面。
3. LINE用戶在LINE App支付頁面，確認商品與支付訊息後，輸入配送地址。LINE Pay透過配送地址與訂單訊息（orderId，transactionId），查詢可選擇的配送方式供用戶選擇。
4. 在選擇配送方式及付款方法後，用戶可以透過既安全又簡單的LINE Pay認證去確認支付請求。
5. 用戶確認支付請求後，將運費和選定的送貨方式添加到商店提供的ConfirmUrl中，然後用戶設備轉導至ConfirmUrl。
6. 透過confirmUrl通知商家其用戶請求已確認支付請求。使用被轉導呼叫的ConfirmUrl而使商店請求Confirm API以完成付款。

Checkout類型

LINE Pay依照“shipping.type”選項提供checkout結帳和一般付款功能。 如要向用戶提供checkout結帳功能，請將結帳選項設置為SHIPPING。如要提供一般付款，請將選項設置為NO_SHIPPING，預設值為NO_SHIPPING。

Highly Recommended

配送方式

當LINE Pay會員輸入送貨地址時，必須向會員提供包含費用和預計送貨時間的配送方式列表。需要提供的API可以參考Inquiry ShippingMethods API。

當用戶在Checkout結帳頁面選擇送貨地址時，LINE Pay將向商店請求送貨地區的訊息。選定的配送方式和費用通過ConfirmUrl的Query String發送。有關更多詳細訊息，請參閱confirmUrl Spec。

一般的Checkout結帳會將"shipping.feeInquiryType"設置為CONDITION用以根據不同的送貨地址，提供不同的運費和配送訊息。如要固定運費或免運費的產品，您可以選擇設置為FIXED。使用免運費或固定運費時，即使會員更改送貨地址，LINE Pay也不會向商店請求配送方式訊息，包括送貨方式或運費標準費用。

Highly Recommended

收貨人

Only Japan

收貨人的firstName，lastName和firstNameOptional，lastNameOptional，必須分別用漢字和片假名寫入。

相關API

• Request API
• Confirm API

自動付款

自動付款是指無需經過LINE Pay使用者的再次確認，僅通過Preapproved Pay API，商家伺服器和LINE Pay伺服器進行交易的功能 通過LINE Pay使用者的首次付款（跟一般付款流程相同），商家可獲取regKey（自動付款金鑰） 商家對Confirm API回傳的regKey進行管理，以後無需LINE Pay App的確認過程，可以用Preapproved Pay API來完成付款和交易

1. 首次付款與regKey（自動付款金鑰）的建立
   1. 從商家伺服器呼叫Request API（請求資訊中的options.payment.payType為PREAPPROVED）
   2. 在LINE Pay付款頁面，確認付款方式和密碼後，跳轉到redirectUrls.confirmUrl（Request API參數）
   3. 商家伺服器對Confirm API回傳的regKey進行管理
   4. 交易完成

1. 自動付款
   1. 利用regKey呼叫Preapproved Pay API
   2. 交易完成

自動付款

1. 請求regKey作廢處理，停止自動付款
   1. 呼叫Expire regKey API
   2. regKey過期失效

相關API

• Request API
• Confirm API
• Check regKey API
• Preapproved Pay API
• Expire regKey API

Payment APIs

Infra and Tech Support

若您對技術支援、Internal Errors或Infra等方面有任何疑問，可以通過email（dl_lptw_tech@linecorp.com）聯繫我們。

Environment	URL	Description
Sandbox	https://sandbox-api-pay.line.me	整合測試用的測試環境。於web simulation page模擬LINE Pay App的付款交易
Production	https://api-pay.line.me	正式的服務環境

API Authentication

下面將介紹LINE Pay Payment API的用戶認證（Authentication）方式。 商家通過審核後，在商家中心(https://pay.line.me)可以查詢到認證所需要用到的"Channel ID"和"Channel SecretKey"等資訊。 LINE Pay也提供Sandbox環境，以幫助串接整合測試使用 Sandbox環境所需的Test Channel資訊（id，secretKey）及Production環境所需的實際Channel資訊（id，secretKey）都可以商家中心找到

Hmac Signature

• Algorithm : HMAC-SHA256
• Key : Channel Secret （LINE Pay商家中心提供"Channel Id"和"Channel SecretKey"）
• HTTP Method
  • GET : Channel Secret + URI + Query String + nonce
  • POST : Channel Secret + URI + Request Body + nonce

HTTP Method : GET

Signature = Base64(HMAC-SHA256(Your ChannelSecret, (Your ChannelSecret + URI + Query String + nonce))) Query String : 不包含 " 問號（?）" 的Query String（例如： Name1=Value1&Name2=Value2...）

HTTP Method : POST

Signature = Base64(HMAC-SHA256(Your ChannelSecret, (Your ChannelSecret + URI + RequestBody + nonce)))

Common HTTP Request Header

下面介紹用於LINE Pay APIs認證的通用標頭（Header）。下表是用於認證的HTTP請求標頭資訊。X-LINE-ChannelId是"Channel Id"，將用"Channel SecretKey"建立的簽章資訊設置在X-LINE-Authorization。為了避免相同簽章，需要建立一次性隨機數設置在X-LINE-Authorization-Nonce。

Key	Data type	Required	Description
Content-Type	String	Y	application/json
X-LINE-ChannelId	String	Y	金流整合資訊 - Channel ID
X-LINE-MerchantDeviceProfileId	String	N	實體商家支援 - Device Type
X-LINE-Authorization-Nonce	String	Y	UUID or timestamp(時間戳)
X-LINE-Authorization	String	Y	HMAC Base64 簽章

X-LINE-Authorization-Nonce

在建立HMAC簽章時， 使用一次性隨機數Nonce，可以避免相同簽名的生成，有效控制惡意請求。 一次性Nonce可以使用UUID 1 or 4和毫秒以下的時間戳（timestamp）。

建立Nonce

    String nonce = UUID.randomUUID().toString();

Sample

HMAC Sample Code

import java.util.UUID;

import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.digest.HmacUtils;

public final class HmacSignature {

    private HmacSignature(){}

    public static String encrypt(final String keys, final String data) {
        return toBase64String(HmacUtils.getHmacSha256(keys.getBytes()).doFinal(data.getBytes()));
    }

    public static String toBase64String(byte[] bytes) {
        byte[] byteArray = Base64.encodeBase64(bytes);
        return new String(byteArray);
    }

    public static void main(String[] args) {
        CheckoutPaymentRequestForm form = new CheckoutPaymentRequestForm();


        form.setAmount(new BigDecimal("100"));
        form.setCurrency("JPY");
        form.setOrderId("merchant_order_id");

        ProductPackageForm productPackageForm = new ProductPackageForm();
        productPackageForm.setId("package_id");
        productPackageForm.setName("shop_name");
        productPackageForm.setAmount(new BigDecimal("100"));

        ProductForm productForm = new ProductForm();
        productForm.setId("product_id");
        productForm.setName("product_name");
        productForm.setImageUrl("");
        productForm.setQuantity(new BigDecimal("10"));
        productForm.setPrice(new BigDecimal("10"));
        productPackageForm.setProducts(Lists.newArrayList(productForm));

        form.setPackages(Lists.newArrayList(productPackageForm));
        RedirectUrls redirectUrls = new RedirectUrls();
        redirectUrls.setAppPackageName("");
        redirectUrls.setConfirmUrl("");
        form.setRedirectUrls(redirectUrls);

        String ChannelSecret = "a917ab6a2367b536f8e5a6e2977e06f4";
        String requestUri = "/v3/payments/request";
        String nonce = UUID.randomUUID().toString();
        String signature = encrypt(ChannelSecret, ChannelSecret + requestUri + toJson(form) + nonce);
    }
}

Request API

本API向LINE Pay請求付款資訊。由此，可以設定使用者的交易資訊與付款方式。請求成功，將生成LINE Pay交易序號，可以進行付款與退款。

API Spec

POST /v3/payments/request

• Connection Timeout : 5秒
• Read Timeout : 20秒

Request

Request Body

Item	Data type	Length	Requirement	Description
amount	Number		Y	付款金額 = sum(packages[].amount) + sum(packages[].userFee) + options.shipping.feeAmount
currency	String	3	Y	貨幣（ISO 4217） 支援貨幣：USD、JPY、TWD、THB
orderId	String	100	Y	商家訂單編號 商家管理的唯一ID
packages[].id	String	50	Y	Package list的唯一ID
packages[].amount	Number		Y	一個Package中的商品總價 =sum(products[].quantity * products[].price)
packages[].userFee	Number		N	手續費：在付款金額中含手續費時設定
packages[].name	String	100	N	Package名稱 （or Shop Name）
packages[].products[].id	String	50	N	商家商品ID
packages[].products[].name	String	4000	Y	商品名
packages[].products[].imageUrl	String	500	N	商品圖示的URL
packages[].products[].quantity	Number		Y	商品數量
packages[].products[].price	Number		Y	各商品付款金額
packages[].products[].originalPrice	Number		N	各商品原金額
redirectUrls.appPackageName	String	4000	N	在Android環境切換應用時所需的資訊，用於防止網路釣魚攻擊（phishing）
redirectUrls.confirmUrl	String	500	Y	使用者授權付款後，跳轉到該商家URL
redirectUrls.confirmUrlType	String		N	使用者授權付款後，跳轉的confirmUrl類型
redirectUrls.cancelUrl	String	500	Y	使用者通過LINE付款頁，取消付款後跳轉到該URL
options.payment.capture	Boolean		N	是否自動請款 true(預設)：呼叫Confirm API，統一進行授權/請款處理 false：呼叫Confirm API只能完成授權，需要呼叫Capture API完成請款
options.payment.payType	String		N	付款類型 NORMAL PREAPPROVED
options.display.locale	String		N	等待付款頁的語言程式碼，預設為英文（en） 支援語言：en、ja、ko、th、zh_TW、zh_CN
options.display.checkConfirmUrlBrowser	Boolean		N	檢查將用於訪問confirmUrl的瀏覽器 true：如果跟請求付款的瀏覽器不同，引導使用LINE Pay請求付款的瀏覽器 false：無需檢查瀏覽器，直接訪問confirmUrl
options.shipping.type	String		N	收貨地選項 NO_SHIPPING FIXED_ADDRESS SHIPPING
options.shipping.feeAmount	String		N	運費
options.shipping.feeInquiryUrl	String	500	N	查詢配送方式的URL
options.shipping.feeInquiryType	String		N	運費查詢類型 CONDITION：收貨地發生變化，就查詢配送方式（運費） FIXED：作為固定值，收貨地發生變化，也不會查詢配送方式
options.shipping.address.country	String	2	N	收貨國家
options.shipping.address.postalCode	String	10	N	收貨地郵政編碼
options.shipping.address.state	String	100	N	收貨地區
options.shipping.address.city	String	100	N	收貨省市區
options.shipping.address.detail	String	1000	N	收貨地址
options.shipping.address.optional	String	1000	N	詳細地址資訊
options.shipping.address.recipient.firstName	String	200	N	收貨人名
options.shipping.address.recipient.lastName	String	200	N	收貨人姓
options.shipping.address.recipient.firstNameOptional	String	200	N	詳細名資訊
options.shipping.address.recipient.lastNameOptional	String	200	N	詳細姓資訊
options.shipping.address.recipient.email	String	100	N	收貨人電子郵件
options.shipping.address.recipient.phoneNo	String	100	N	收貨人電話號碼
options.familyService.addFriends[].type	String		N	新增好友的服務類型 lineAt
options.familyService.addFriends[].idList[]	List		N	各服務類型的ID list
options.extra.branchName	String	200	N	商店或分店名稱(僅會顯示前 100 字元)
options.extra.branchId	String	32	N	商店或分店代號，可支援英數字及特殊字元
options.extra.promotionRestriction	object		N	點數限制資訊 useLimit: 不可使用點數折抵的金額 rewardLimit: 不可回饋點數的金額 "promotionRestriction": {     "useLimit": 100,     "rewardLimit": 100 }

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息
info.transactionId	Number	19	交易序號
info.paymentAccessToken	String	12	該代碼在LINE Pay可以代替掃描器使用
info.paymentUrl.app	String	300	用來跳轉到付款頁的App URL 在應用程式發起付款請求時使用 在從商家應用跳轉到LINE Pay時使用
info.paymentUrl.web	String	300	用來跳轉到付款頁的Web URL 在網頁請求付款時使用 在跳轉到LINE Pay等待付款頁時使用 不經參數，直接跳轉到傳來的URL 在Desktop版，彈窗大小為Width：700px，Height：546px

Return Codes

Code	Description
0000	成功
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1124	金額有誤（scale）
1145	正在進行付款
1172	該訂單編號(orderId)的交易記錄已經存在
1178	商家不支援該貨幣
1183	付款金額不能小於 0
1194	此商家無法使用自動付款
2101	參數錯誤
2102	JSON資料格式錯誤
9000	內部錯誤

Request Details

Product

按Package或單項產品，可以提供更豐富的下單（付款）資訊。Package是與Shipping相關的，一個Package可以包含多項產品。

RedirectUrls.confirmUrl

使用者確認付款請求後，confirmUrl自動被呼叫。confirmUrl告訴商家，使用者確認完成，現在可以呼叫Confirm API完成交易。同時為已確認付款，但尚未完成交易的使用者顯示付款情況。

RedirectUrls.cancelUrl

如果付款過程中使用者取消付款，通過Request API中的cancelUrl，跳轉到付款取消頁。

confirmUrlType

使用者確認付款後，confirmUrl的作用如下。

• CLIENT

使用者的畫面跳轉到商家confirmUrl，完成付款流程

• SERVER

LINE Pay Server向Merchant Server請求confirmUrl

https protocol是必須的，並需要使用“可信任的憑證”

• NONE

使用者確認付款請求後，無需顯示付款完成頁的特殊情況下（如線下付款等），不用請求confirmUrl

商家通過Payment Status API，週期性檢查使用者是否確認付款請求

Options

LINE Pay提供各種各樣的付款方式與附加功能（Family Services），可使用Options下欄位設定，可以使用這些服務

Payment

設定付款選項

payType

• NORMAL , 一般付款

• PREAPPROVED , 自動付款

Display

使用者的付款頁和付款流程可以如下設定:

locale

使用者等待付款頁語言

• en 英語

• ja 日語

• ko 韓語

• th 泰國語

• zh_CN 中文（簡體）

• zh_TW 中文（繁體）

FamilyService

下面介紹LINE Family Service支援哪些功能。

addFriends

提供新增好友（LINE@）功能。

Example

{
    "options" : {
        "addFriends": [{
            "type": "lineAt",
            "idList": ["@linepay", "@checkout"]
        }]
    }
}

通過本功能，商家和LINE Pay使用者可以建立好友關係。

• Type
  • lineAt：支援LINE@新增好友服務

Sample

一般付款

{
    "amount" : 100,
    "currency" : "TWD",
    "orderId" : "MKSI_S_20180904_1000001",
    "packages" : [
        {
            "id" : "1",
            "amount": 100,
            "products" : [
                {
                    "id" : "PEN-B-001",
                    "name" : "Pen Brown",
                    "imageUrl" : "https://pay-store.line.com/images/pen_brown.jpg",
                    "quantity" : 2,
                    "price" : 50
                }
            ]
        }
    ],
    "redirectUrls" : {
        "confirmUrl" : "https://pay-store.line.com/order/payment/authorize",
        "cancelUrl" : "https://pay-store.line.com/order/payment/cancel"
    }
}

自動付款

{
    "amount" : 0,
    "currency" : "TWD",
    "orderId" : "MKSI_P_20181231_1000001",
    "packages" : [
        {
            "id" : "1",
            "amount": 0,
            "products" : [
                {
                    "id" : "1",
                    "name" : "Prime MemberShip",
                    "imageUrl" : "https://pay-store.line.com/images/pen_brown.jpg",
                    "quantity" : 1,
                    "price" : 0
                }
            ]
        }
    ],
    "redirectUrls" : {
        "confirmUrl" : "https://pay-store.line.com/order/payment/authorize",
        "cancelUrl" : "https://pay-store.line.com/order/payment/cancel"
    },
    "options" : {
        "payment" : {
            "payType" : "PREAPPROVED"
        }
    }
}

Checkout付款

{
    "amount" : 1000,
    "currency" : "JPY",
    "orderId" : "MKSI_M_20180904_1000001",
    "packages" : [
        {
            "id" : "1",
            "amount" : 1000,
            "products" : [
                {
                    "id" : "PEN-B-001",
                    "name" : "Pen Brown",
                    "imageUrl" : "http://pay-store.line.com/static/img/brown-head.jpg",
                    "quantity" : 2,
                    "price" : 50
                },
                {
                    "id" : "NT-W-001",
                    "name" : "White Note",
                    "imageUrl" : "http://pay-store.line.com/static/img/white-head.jpg",
                    "quantity" : 1,
                    "price" : 300
                },
                {
                    "id" : "NT-P-001",
                    "name" : "Gun mksi-edition",
                    "imageUrl" : "http://pay-store.line.com/static/img/mksi-shot.jpg",
                    "quantity" : 2,
                    "price" : 300
                }
            ]
        }
    ],
    "redirectUrls" : {
        "confirmUrl" : "http://pay-store.line.com/payment/redirect?type=confirm",
        "cancelUrl" : "http://pay-store.line.com/payment/redirect?type=cancel"
    },
    "options" : {
        "shipping" : {
            "type" : "SHIPPING",
            "feeInquiryUrl" : "https://pay-store.line.com/order/shipping/method",
            "feeInquiryType" : "CONDITION"
        }
    }
}

Confirm API

在用戶確認付款後，商家可透過confirmUrl或Check Payment Status API，來完成交易。 如果Request API中"options.payment.capture"被設置為false，意味著該交易的授權與請款分開。 在此情況下，付款完成後，狀態仍然會保持”待請款（授權）”。因此，需呼叫Capture API進行後續處理，才能完成交易的所有流程。

API Spec

POST /v3/payments/{transactionId}/confirm

• Connection Timeout ：5秒
• Read Timeout : 40秒

Request Body

Item	Data type	Length	Requirement	Description
amount	Number		Y	付款金額
currency	String	3	Y	貨幣(ISO 4217) 支援下列貨幣： USD JPY TWD THB

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息
info.orderId	String	100	請求付款時，回應的商家唯一訂單編號
info.transactionId	Number		作為請求付款的結果，回應的交易序號（19個字符）
info.authorizationExpireDate	String	30	授權過期時間（ISO 8601） 僅限於完成授權（capture=false）的付款，進行回傳。
info.regKey	String	15	用於自動付款的密鑰（15個字符）
info.payInfo[].method	String	20	付款方式 信用卡：CREDIT_CARD 餘額：BALANCE 折扣：DISCOUNT (發票金額須扣除) LINE POINTS：POINT (預設不顯示)
info.payInfo[].amount	Number		付款金額
info.payInfo[].creditCardNickname	String	100	用於自動付款的信用卡別名 綁定在LINE Pay的信用卡名。一般在綁定信用卡時設置。 如果LINE Pay用戶沒有設置別名，會回傳空字符串。 用戶通過LINE Pay可以更改別名，更改內容不會分享到商家。
info.payInfo[].creditCardBrand	String	20	用於自動付款的信用卡品牌 VISA MASTER AMEX DINERS JCB
info.payInfo[].maskedCreditCardNumber	String	17	被遮罩（Masking）的信用卡號（僅限於台灣商家回應，若您需要，可以向商家中心管理者申請獲取。） Format: **** **** **** 1234
info.packages[].id	String	50	Package list的唯一ID
info.packages[].amount	Number		一個Package中的商品總價 =sum(products[].quantity * products[].price)
info.packages[].userFeeAmount	Number		手續費：在付款金額中含手續費時回應
info.merchantReference.affiliateCards[].cardType	string	N	交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認}
info.merchantReference.affiliateCards[].cardId	string	N	交易中若用戶符合商店支援的卡片類型所對應的內容值
info.shipping.methodId	String	50	用戶所選的配送方式ID
info.shipping.feeAmount	Number		運費
info.shipping.address.country	String	2	收貨國家
info.shipping.address.postalCode	String	10	收貨地郵政編碼
info.shipping.address.state	String	100	收貨地區
info.shipping.address.city	String	100	收貨省市區
info.shipping.address.detail	String	1000	收貨地址
info.shipping.address.optional	String	1000	詳細地址資訊
info.shipping.address.recipient.firstName	String	200	收貨人名
info.shipping.address.recipient.lastName	String	200	收貨人姓
info.shipping.address.recipient.firstNameOptional	String	200	詳細名資訊
info.shipping.address.recipient.lastNameOptional	String	200	詳細姓資訊
info.shipping.address.recipient.email	String	100	收貨人電子郵件
info.shipping.address.recipient.phoneNo	String	50	收貨人電話號碼

Return Codes

Code	Description
0000	成功
1101	買家不是LINE Pay用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用 LINE Pay
1106	標頭(Header)資訊錯誤
1110	無法使用的信用卡
1124	金額錯誤 (scale)
1141	付款帳戶狀態錯誤
1142	Balance餘額不足
1150	交易記錄不存在
1152	該transactionId的交易記錄已經存在
1153	付款request時的金額與申請時的金額不一致
1159	無付款申請資訊
1169	用來確認付款的資訊錯誤（請訪問LINE Pay設置付款方式與密碼認證）
1170	使用者帳戶的餘額有變動
1172	該訂單編號(orderId)的交易記錄已經存在
1180	付款時限已過
1198	API調用重覆
1199	內部請求錯誤
1264	一卡通MONEY通相關錯誤
1280	信用卡付款時候發生了臨時錯誤
1281	信用卡付款錯誤
1282	信用卡授權錯誤
1283	因有異常交易疑慮暫停交易，請洽 LINE Pay 客服確認
1284	暫時無法以信用卡付款
1285	信用卡資訊不完整
1286	信用卡付款資訊不正確
1287	信用卡已過期
1288	信用卡的額度不足
1289	超過信用卡付款金額上限
1290	超過一次性付款的額度
1291	此信用卡已被掛失
1292	此信用卡已被停卡
1293	信用卡驗證碼 (CVN) 無效
1294	此信用卡已被列入黑名單
1295	信用卡號無效
1296	無效的金額
1298	信用卡付款遭拒絕
9000	內部錯誤

Sample

Confirm API的請求範例

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}" \
    -H "X-LINE-Authorization-Nonce: 44453d45-768e-40e8-8349-748e797c450f" \
    -H "X-LINE-Authorization: {Hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
    -d '{ "amount": 1000, "currency":"TWD" }' \
    https://sandbox-api-pay.line.me/v3/payments/2018082512345678910/confirm

Response

在付款類型（payType）為NORMAL時，用BALANCE付款的範例

 {
     "returnCode": "0000",
     "returnMessage": "OK",
     "info": {
         "orderId": "MKSI_M_20180904_1000001",
         "transactionId": 2018082512345678910,
         "payInfo": [{
             "method": "BALANCE",
             "amount": 900
         }, {
             "method": "DISCOUNT",
             "amount": 100
         }],
     }
 }

Capture API

呼叫Request API發出付款請求時，把"options.payment.capture"設置為false的話，當Confirm API完成付款後，該交易轉換為“待請款狀態”。在此情況下，需呼叫Capture API進行後續請款處理，才能完成所有付款流程。

API Spec

POST /v3/payments/authorizations/{transactionId}/capture

• Connection Timeout：5秒
• Read Timeout：60秒

Request Body

Item	Data type	Requirement	Description
amount	number	Y	付款金額
currency	String(3byte)	Y	貨幣（ISO 4217） 支援下列貨幣: USD JPY TWD THB
Extra Fields
options.extra.promotionRestriction	object	N	點數限制資訊 useLimit: 不可使用點數折抵的金額 rewardLimit: 不可回饋點數的金額 "promotionRestriction": {     "useLimit": 100,     "rewardLimit": 100 }

Response Body

Item	Data type	Description
returnCode	String(4byte)	結果代碼
returnMessage	String	結果訊息或失敗原因。例如： 該商家無法交易 商家認證資訊錯誤
info.orderId	String	在請求付款時，商家回應的訂單編號
info.transactionId	Number	作為請求付款的結果，回應的交易序號（19個字符）
info[].payInfo[].method	String	付款方式 信用卡：CREDIT_CARD 餘額：BALANCE 折扣：DISCOUNT (發票金額須扣除) LINE POINTS：POINT (預設不顯示)
info.payInfo[].amount	Number	付款金額

Return Codes

Code	Description
0000	成功
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1150	交易記錄不存在
1155	該交易序號有誤
1170	使用者帳戶的餘額有變動
1172	該訂單號(orderId)的交易記錄已經存在
1179	無法處理的狀態
1183	付款金額不能小於 0
1184	付款金額比付款申請時候的金額還大
1198	API重覆呼叫，或者授權更新過程中，呼叫了Capture API（請幾分鐘後重試一下）
1199	內部請求錯誤
1264	一卡通MONEY通相關錯誤
1280	信用卡付款時候發生了臨時錯誤
1281	信用卡付款錯誤
1282	信用卡授權錯誤
1283	因有異常交易疑慮暫停交易，請洽 LINE Pay 客服確認
1284	暫時無法以信用卡付款
1285	信用卡資訊不完整
1286	信用卡付款資訊不正確
1287	信用卡已過期
1288	信用卡的額度不足
1289	超過信用卡付款金額上限
1290	超過一次性付款的額度
1291	此信用卡已被掛失
1292	此信用卡已被停卡
1293	信用卡驗證碼 (CVN) 無效
1294	此信用卡已被列入黑名單
1295	信用卡號無效
1296	無效的金額
1298	信用卡付款遭拒絕
9000	內部錯誤

Sample

Request

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}" \
    -H "X-LINE-Authorization-Nonce: c3b3c9e5-701b-4df8-bcbc-e3ee86a1cef3" \
    -H "X-LINE-Authorization: {Hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
    -d '{ "amount": 1000, "currency": "TWD" }' https://sandbox-api-pay.line.me/v3/payments/authorizations/2018082512345678910/capture

Response

{
    "returnCode": "0000",
    "returnMessage": "OK",
    "info": {
        "transactionId": 2018082512345678910,
        "orderId": "order_210124213",
        "payInfo": [{
            "method": "BALANCE",
            "amount": 900
        }, {
            "method": "DISCOUNT",
            "amount": 100
        }]
    }
}

Void API

本API針對授權階段的交易資料進行無效處理。因此，透過Confirm API完成授權的交易，將會被取消授權 Void API僅對已授權的交易產生影響，如是已請款的交易，需使用Refund API進行退款

API Spec

POST /v3/payments/authorizations/{transactionId}/void

• Connection Timeout : 5秒
• Read Timeout : 20秒

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息或失敗原因。有如下例子。 該商家無法交易 商家認證資訊錯誤

Return Codes

Code	Description
0000	成功
1101	買家不是LINE Pay的用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1150	交易記錄不存在
1155	該交易序號有誤
1165	該交易已經被取消授權且無效
1170	使用者帳戶的餘額有變動
1198	API重覆呼叫，或者授權更新過程中，呼叫了CaptureAPI（請幾分鐘後重試一下）
1199	內部請求錯誤
1900	發生暫時錯誤，請稍後重試
1902	發生暫時錯誤，請稍後重試
1999	跟已發出的請求資訊不同
9000	內部錯誤

Sample

Request

curl -X POST \
-H "Content-Type: application/json" \
-H "X-LINE-ChannelId: {your channelId}" \
-H "X-LINE-Authorization-Nonce: 8335ce37-1386-4b0b-bd65-90d65abaedd6" \
-H "X-LINE-Authorization: {signature}" \
-H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
https://sandbox-api-pay.line.me/v3/payments/authorizations/2018082512345678910/void

Response

{
    "returnCode": "0000",
    "returnMessage": "OK"
}

Refund API

本 API 用以取消已付款(購買完成)的交易，並可支援部分退款。呼叫時需要帶入該筆付款的 LINE Pay 原始交易序號(transactionId)

API Spec

POST /v3/payments/{transactionId}/refund

• Connection Timeout : 5秒
• Read Timeout : 20秒

Request Body

Item	Data type	Requirement	Description
refundAmount	Number	N	退款金額 返回空值的話，進行全部退款
Extra Fields
options.extra.promotionRestriction	object	N	點數限制資訊 useLimit: 不可使用點數折抵的金額 rewardLimit: 不可回饋點數的金額 "promotionRestriction": {     "useLimit": 100,     "rewardLimit": 100 }

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息或失敗原因
info.refundTransactionId	Number	19	退款序號（該次退款產生的新序號, 19 digits）
info.refundTransactionDate	String	30	退款日期（ISO 8601）

Return Codes

Code	Description
0000	成功
1101	買家不是LINE Pay的用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1124	金額有誤（scale）
1150	交易記錄不存在
1155	交易編號不符合退款資格
1163	可退款期限已過無法退款
1164	退款金額超過限制金額
1165	已經退款而關閉的交易
1179	無法處理的狀態
1198	API呼叫重複
1199	內部請求錯誤
1264	一卡通MONEY通相關錯誤
9000	內部錯誤

Sample

Request

curl -X POST -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}"\
    -H "X-LINE-Authorization-Nonce: 57d03ebc-0c79-404c-82e5-bb8b3b30fe56" \
    -H "X-LINE-Authorization: {Hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}"\
    -d '{ "refundAmount": 1000 }'\
    https://sandbox-api-pay.line.me/v3/payments/2018082512345678910/refund

Response

{
    "returnCode": "0000",
    "returnMessage": "success",
    "info": {
        "refundTransactionId": 2018082512345678911,
        "refundTransactionDate": "2018-08-25T09:15:01Z"
    }
}

Payment Details API

本API查詢LINE Pay中的交易記錄。您可以查詢授權和購買完成狀態的交易。使用"fields"設定，可以按交易或訂單資訊，選擇查出交易記錄。

API Spec

GET /v3/payments

• Connection Timeout : 5秒
• Read Timeout : 20秒

Request Parameter

Item	Data type	Requirement	Description
transactionId[]	Number	N	由LINE Pay建立的交易序號或退款序號
orderId[]	String	N	商家訂單編號
fields	String	N	可以選擇查詢物件 transaction order 預設為所有

Response

Response Body

通用資訊

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	100	結果訊息或失敗原因

在查詢Transaction類型時回應如下：

Item	Data type	Length	Description
info[].transactionId	Number		交易序號（19個字元）
info[].transactionDate	String	20	交易日期（ISO-8601）
info[].transactionType	String		交易分類 PAYMENT：付款 PAYMENT_REFUND：退款 PARTIAL_REFUND：部分退款
info[].payStatus	String	20	付款狀態 CAPTURE：已請款 AUTHORIZATION：授權 VOIDED_AUTHORIZATION：授權無效（在呼叫"Void API"的狀態） EXPIRED_AUTHORIZATION：授權到期（LINE Pay所允許的商家授權有效期已過期）
info[].productName	String	4000	商品名稱
info[].merchantName	String		商家名稱
info[].currency	String	3	貨幣（ISO 4217）
info[].authorizationExpireDate	String	20	授權交易到期時間（ISO-8601）
info[].payInfo[].method	String		付款方式 信用卡：CREDIT_CARD 餘額：BALANCE 折扣：DISCOUNT (發票金額須扣除) LINE POINTS：POINT (預設不顯示)
info[].payInfo[].amount	Number		交易金額（建立交易序號時提供的金額） 在檢視原始交易時，最終交易金額的演算法如下： sum(info[].payInfo[].amount) – sum(refundList[].refundAmount)
info[].merchantReference.affiliateCards[].cardType	string		交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認}
info[].merchantReference.affiliateCards[].cardId	string		交易中若用戶符合商店支援的卡片類型所對應的內容值

在查詢Transaction類型時，對原始交易與退款交易的回應如下：

Item	Data type	Description
info[].refundList[].refundTransactionId	Number	退款序號（19個字元）
info[].refundList[].transactionType	String	交易分類 PAYMENT_REFUND：退款 PARTIAL_REFUND：部分退款
info[].refundList[].refundAmount	Number	退款
info[].refundList[].refundTransactionDate	String	退款日期 (ISO-8601)

在查詢Transaction類型時，對退款交易的應如下：

Item	Data type	Description
info[].originalTransactionId	Number	原始交易序號（19個字元）

在查詢Order類型時回應如下：

Item	Data type	Length	Description
info[].packages[].id	String	50	Package list的唯一ID
info[].packages[].amount	Number		一個Package中的商品總價 =sum(products[].quantity * products[].price)
info[].packages[].userFeeAmount	Number		手續費：在付款金額中含手續費時回應
info[].packages[].name	String	100	配送單位 or （內部Shop Name）
info[].packages[].products[].id	String	50	商家商品ID
info[].packages[].products[].name	String	4000	商品名
info[].packages[].products[].imageUrl	String	500	商品Image Url
info[].packages[].products[].quantity	Number		商品數量
info[].packages[].products[].price	Number		各商品付款價格
info[].packages[].products[].originalPrice	Number		各商品原價格
info[].merchantReference.affiliateCards[].cardType	string		交易中若用戶符合商店支援的卡片類型 - 電子發票載具: MOBILE_CARRIER (功能預設不開啟) - 商家會員卡: {類別名稱需與LINE Pay洽談確認}
info[].merchantReference.affiliateCards[].cardId	string		交易中若用戶符合商店支援的卡片類型所對應的內容值
info[].shipping.methodId	String	50	使用者所選的配送方式ID
info[].shipping.feeAmount	Number		運費
info[].shipping.address.country	String	2	收貨國家
info[].shipping.address.postalCode	String	10	收貨地郵政編碼
info[].shipping.address.state	String	100	收貨地區
info[].shipping.address.city	String	100	收貨省市區
info[].shipping.address.detail	String	1000	收貨地址
info[].shipping.address.optional	String	1000	詳細地址資訊
info[].shipping.address.recipient.firstName	String	200	收貨人名
info[].shipping.address.recipient.lastName	String	200	收貨人姓
info[].shipping.address.recipient.firstNameOptional	String	200	詳細名資訊
info[].shipping.address.recipient.lastNameOptional	String	200	詳細姓資訊
info[].shipping.address.recipient.email	String	100	收貨人電子郵件
info[].shipping.address.recipient.phoneNo	String	50	收貨人電話號碼

在查詢events類型時回應如下：

Item	Data type	Length	Description
info[].events[].code	String	30	指定品項組合所符合的代碼
info[].events[].totalAmount	Number		指定品項組合所符合的銷售金額。
info[].events[].productQuantity	Number		指定品項組合所符合的組合數量。

Return Codes

Code	Description
0000	成功
1104	此商家不存在
1105	此商家無法使用 LINE Pay
1106	標頭(Header)資訊錯誤
1150	交易記錄不存在
1177	超過允許查詢的交易數目 (100筆)
9000	內部錯誤

Sample

Request

curl -X GET \
-H "Content-Type: application/json" \
-H "X-LINE-ChannelId: {your channelId}" \
-H "X-LINE-Authorization-Nonce: ef6934b8-b42f-48db-87b7-e18e1fb1832e" \
-H "X-LINE-Authorization: {Hmac signature}" \
-H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
https://sandbox-api-pay.line.me/v3/payments?transactionId=2019060112345678910&orderId=20190601ORD45678910

Response

在查詢付款交易時回應範例如下：

{
    "returnCode":"0000",
    "returnMessage":"success",
    "info":[{
       "transactionId":2019060112345678910,
       "transactionDate":"2019-06-01T09:00:00Z",
       "transactionType":"PAYMENT",
       "payInfo": [
           {"method":"BALANCE", "amount":100},
           {"method":"DISCOUNT", "amount":10}
         ],
       "productName":"tes production",
       "currency":"TWD",
       "orderId":"20190601ORD45678910",
       "refundList":[
          {
             "refundTransactionId":2019060112345678911,
             "transactionType":"PARTIAL_REFUND",
             "refundAmount":-1,
             "refundTransactionDate":"2019-06-06T09:00:00Z"
          },
          {
             "refundTransactionId":2019060112345678911,
             "transactionType":"PARTIAL_REFUND",
             "refundAmount":-1,
             "refundTransactionDate ":"2019-06-06T10:00:00Z"
          },
          {
             "refundTransactionId":2019060112345678911,
             "transactionType":"PARTIAL_REFUND",
             "refundAmount":-1,
             "refundTransactionDate ":"2019-06-06T11:00:00Z"
          }
         ],
         "packages": [
             {
                 "id": "1",
                 "amount": 85,
                 "userFeeAmount":0
             },
             {
                 "id": "3",
                 "amount": 5,
                 "userFeeAmount":0
             }
         ],
        /* shipping為使用到Checkout時的資訊，目前Checkout只限定日本可以使用 */  
         "shipping": {
             "methodId": "FB-001",
             "feeAmount": 20,
             "address": {
                 "country": "JP",
                 "postalCode": "1600022",
                 "state": "東京都",
                 "city": " 渋谷区渋谷",
                 "detail": "(〒)150-8510 東京都 渋谷区渋谷",
                 "optional": "123",
                 "recipient": {
                   "firstName":"絵里",
                   "lastName":"松澤",
                   "firstNameOptional": "エリ",
                   "lastNameOptional": "マツザワ",
                   "phoneNo": "01999991234",
                   "email": "mksi@test.linecorp.com"
                 }
             }
         }
    }]
 }

在查詢退款交易時回應範例如下：

{
    "returnCode":"0000",
    "returnMessage":"success",
    "info":[{
      "transactionId":2019060112345678912,
      "transactionDate":"2019-06-01T09:48:43Z",
      "transactionType":"PARTIAL_REFUND",
      "amount":-5,
      "productName":"Brown",
      "currency":"TWD",
      "orderId":"20190101123123123",
      "originalTransactionId":2019060112345678910
    }]
}

在查詢付款交易且符合指定品項組合時回應範例如下：

{
    "returnCode":"0000",
    "returnMessage":"success",
    "info":[{
       "transactionId":2019060112345678912,
       "transactionDate":"2019-06-01T09:48:43Z",
       "transactionType":"PARTIAL_REFUND",
       "amount":-5,
       "productName":"Brown",
       "currency":"JPY",
       "orderId":"20190101123123123",
       "originalTransactionId":2019060112345678910,
       "events": [
         {
           "code": "alphanumeric",
           "totalAmount": 500,
           "productQuantity": null
         },
         {
           "code": "alphanumeric2",
           "totalAmount": null,
           "productQuantity": 10
         }
       ]
    }]
 }

Check Payment Status API

本API查詢LINE Pay付款請求的狀態。商家應隔一段時間後直接檢查付款狀態，不透過confirmUrl查看用戶是否已經確認付款，最終判斷交易是否完成。

API Spec

GET /v3/payments/requests/{transactionId}/check

• Connection Timeout ：5秒
• Read Timeout : 20秒

Response

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	100	結果訊息或失敗原因
info.shipping.methodId	String	50	用戶所選的配送方式ID
info.shipping.feeAmount	Number		運費

Return Code

Code	Description
0000	授權尚未完成
0110	授權完成 - 現在可以呼叫Confirm API
0121	該交易已被用戶取消，或者超時取消（20分鐘）- 交易已經結束了
0122	付款失敗 - 交易已經結束了
0123	付款成功 - 交易已經結束了
1104	此商家不存在
1105	此商家處於無法使用LINE Pay的狀態
9000	內部錯誤

Sample

Request

curl -X GET \
-H "Content-Type: application/json" \
-H "X-LINE-ChannelId: {your channelId}" \
-H "X-LINE-Authorization-Nonce: e51779e1-5788-4884-9c3a-52f7bf8cb0fa" \
-H "X-LINE-Authorization: {Hmac signature}" \
-H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
https://sandbox-api-pay.line.me/v3/payments/requests/2018110112345678910/check

Response - 一般付款

{
   "returnCode":"0000",
   "returnMessage":"reserved transaction"
}

Response - Checkout付款

{
   "returnCode":"0123",
   "returnMessage":"success",
   "info": {
       "shipping": {
            "methodId": "FB-001",
            "feeAmount": 20
        }
   }
}

Check RegKey API

本API查詢已建立的RegKey狀態。

API Spec

GET /v3/payments/preapprovedPay/{regKey}/check

• Connection Timeout : 5秒
• Read Timeout : 20秒

Parameter

Item	Data type	Requirement	Description
creditCardAuth	Boolean	N	使用RegKey的信用卡，是否完成預授權 true : 通過LINE Pay驗證和信用卡預授權，查詢RegKey狀態。請注意，這必須經過LINE Pay管理人員的稽核進行。 false：通過LINE Pay驗證查詢RegKey狀態。

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息

Return Codes

Code	Description
0000	成功
1101	買家不是LINE Pay的用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用 LINE Pay
1106	標頭(Header)資訊錯誤
1141	付款帳戶狀態錯誤
1154	買家設定為自動付款的信用卡暫時無法使用
1190	regKey 不存在
1193	regKey 已過期

Sample

Pay Preapproved API的請求範例

curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}" \
    -H "X-LINE-Authorization-Nonce: df9c7e0e-e6c4-4d24-9847-b8f3cbe9bf58" \
    -H "X-LINE-Authorization: {Hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
    https://sandbox-api-pay.line.me/v3/payments/preapprovedPay/RK123asd213/check

Response

 {
    "returnCode": "0000",
    "returnMessage": "OK",
}

Pay Preapproved API

使用本API之前，您需要先使用Request API和Confirm API，設定自動付款。通過Confirm API回應的RegKey，不經使用者確認，可以直接進行付款。

API Spec

POST /v3/payments/preapprovedPay/{regKey}/payment

• Connection Timeout ：5秒
• Read Timeout : 40秒

Request Body

Item	Data type	Length	Requirement	Description
productName	String	4000	Y	商品名稱
amount	Number		Y	付款金額
currency	String	3	Y	貨幣(ISO 4217) 支援如下貨幣。 USD JPY TWD THB
orderId	String	100	Y	商家唯一訂單編號
capture	Boolean		N	購買是否完成 <br /> <ul><li> true : 授權/購買</li> <li>false : 只完成授權，需要呼叫Capture API進行購買</li><li>

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息
info.orderId	String	100	請求付款時，返回的商家唯一訂單編號
info.transactionId	Number		作為請求付款的結果，返回的交易序號（19個字元）
info.transactionDate	String	30	交易日期 (ISO 8601)
info.authorizationExpireDate	String	30	授權過期時間（ISO 8601）

Return Codes

Code	Description
0000	成功
1101	買家不是 LINE Pay的用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1110	無法使用的信用卡
1124	金額錯誤 (scale)
1141	付款帳戶狀態錯誤
1142	Balance餘額不足
1150	交易記錄不存在
1152	該transactionId的交易記錄已經存在
1153	付款request時的金額與申請的金額不一致
1159	無付款申請資訊
1169	用來確認付款的資訊錯誤（請訪問LINE Pay設置付款方式與密碼認證）
1170	使用者帳戶的餘額有變動
1172	該訂單編號(orderId)的交易記錄已經存在
1180	付款時限已過
1198	API重覆呼叫，或者授權更新過程中，呼叫了CaptureAPI（請幾分鐘後重試一下）
1199	內部請求錯誤
1280	信用卡暫時出錯
1280	信用卡付款時候發生了臨時錯誤
1281	信用卡付款錯誤
1282	信用卡授權錯誤
1283	因有異常交易疑慮暫停交易，請洽 LINE Pay 客服
1284	暫時無法以信用卡付款
1285	信用卡資訊不完整
1286	信用卡付款資訊不正確
1287	信用卡已過期
1288	信用卡的額度不足
1289	超過信用卡付款金額上限
1290	超過一次性付款的額度
1291	此信用卡已被掛失
1292	此信用卡已被停卡
1293	信用卡驗證碼 (CVN) 無效
1294	此信用卡已被列入黑名單
1295	信用卡號無效
1296	無效的金額
1298	信用卡付款遭拒絕
9000	內部錯誤

Sample

Pay Preapproved API的請求範例

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}" \
    -H "X-LINE-Authorize-Nonce: 6120489b-53f3-4c51-9d6f-b80be93e509a"\
    -H "X-LINE-Authorization: {hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
    -d '{ "productName":"Brown pen", "amount": 1000, "currency":"JPY", "orderId":"Ord2018123100000001" }' \
    https://sandbox-api-pay.line.me/v3/payments/preapprovedPay/RK123asd213/payment

Response

capture：true回應範例

 {
    "returnCode": "0000",
    "returnMessage": "OK",
    "info": {
        "transactionId": 2018123112345678910,
        "transactionDate": "2018-12-31T09:00:31Z"   
    }
}

capture : false回應範例

 {
    "returnCode": "0000",
    "returnMessage": "OK",
    "info": {
        "transactionId": 2018123112345678910,
        "transactionDate": "2018-12-31T09:00:31Z",
        "authorizationExpireDate": "2019-01-31T09:00:31Z",
    }
}

Expire RegKey API

本API對已建立的RegKey進行過期處理。

API Spec

POST /v3/payments/preapprovedPay/{regKey}/expire

• Connection Timeout : 5秒
• Read Timeout : 20秒 ​
  

Response Body

Item	Data type	Length	Description
returnCode	String	4	結果代碼
returnMessage	String	300	結果訊息

Return Codes

Code	Description
0000	成功
1104	此商家不存在
1105	此商家無法使用LINE Pay
1106	標頭(Header)資訊錯誤
1190	regKey 不存在
1193	regKey 已過期

Sample

Pay Preapproved API的請求範例

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-LINE-ChannelId: {your channelId}" \
    -H "X-LINE-Authorization-Nonce: 5c75efcc-9c5e-4a32-9fe3-5d55ce67b598" \
    -H "X-LINE-Authorization: {Hmac signature}" \
    -H "X-LINE-MerchantDeviceProfileId: {your device profile id}" \
    https://sandbox-api-pay.line.me/v3/payments/preapprovedPay/RK123asd213/expire

44453d45-768e-40e8-8349-748e797c450f

Response

 {
    "returnCode": "0000",
    "returnMessage": "OK",
}

Merchant provided API or Page

Merchant provided API or Page

本文闡述了商家需為LINE Pay需要提供哪些API（或 page url）。在正式環境，商家需要使用可信任的證書與HTTPS Protocol。 同時，由於安全考量，證書版本必須要是TLS 1.2及以上。

Access Control List

如果商家提供的API，通過IP限制訪問的話，對每個環境需要設定以下LINE Pay Server IP。

• Sandbox：125.209.235.102
• Real：211.249.40.1 ~ 211.249.40.30

confirmUrl Spec

商家必須按照confirmUrlType，以Page或API的形式提供confirmUrl Spec。 使用者在LINE Pay確認付款後，confirmUrl為使用者顯示付款進行的情況，並提醒商家已獲取使用者確認。 通過Confirm API付款完成後，在跳轉到交易完成頁的過程中，confirmUrl還能起到過渡頁的作用。 對無需此頁的特殊交易，直接返回HTTP status 200即可。

API詳情

Item	Description
Protocol	HTTP
Method	GET
Request timeout	Connection：5秒 Read：20秒

Request parameters

Parameters	requirement	Description
orderId	Y	在請求付款時，從商家端回應的訂單編號
transactionId	Y	在請求付款時，回應的交易序號
shippingFeeAmount	N	Checkout運費
shippingMethodId	N	商家配送方式中被選的方式ID

商家回傳的回應結果不含單獨資訊，LINE Pay僅通過HTTP回應代碼來判斷是否成功。如果HTTP回應代碼不是成功（200 OK），向LINE Pay使用者提示付款失敗。

Response

Sample

Request 假設商家提供'http://testmall.com/pay/result'的confirmUrl。

curl -X GET \
    http://testmall.com/pay/result?orderId=2018xxx1232132&trasactionId=201810281234567890&shippingFeeAmount=2100&shippingMethodId=1

Success Response

HTTP/1.1 200 OK
Accept-Charset: utf-8
Content-Type: text/html
Content-Length: 2
Date: Sat, 11 Oct 2018 02:45:48 GMT

Fail Response

HTTP/1.1 404 NOT_FOUND
Accept-Charset:utf-8
Content-Type:text/html
Content-Length:4
Date:Sat, 11 Oct 2018 02:45:48 GMT

cancelUrl

用戶如果在使用LINE Pay在進行付款的過程中取消付款時，通過Request API回應的cancelUrl，直接跳轉到商家頁面。

Inquiry ShippingMethods API

使用Checkout功能的商家，需要實現有關API Spec，並通過Request API提供給LINE Pay。使用者選擇收貨地後，商家通過API，按Postal Code（ZipCode）查詢配送範圍、配送方式及費用等資訊。通過confirmUrl，商家可以獲取使用者所選的配送方式與運費資訊。

API詳情

Item	Description
Protocol	HTTP
Method	POST
Request timeout	Connection：5秒 Read：20秒

Request

• HTTP Header

Key	Value	Description
Content-Type	application/json

• Body

Parameters	Data type	Length	requirement	Description
currency	String	3	Y	運費貨幣
orderId	String	100	Y	在請求付款時，商家回傳的訂單編號
transactionId	Number		Y	在請求付款時，回應的交易序號
shippingAddress.country	String	2	N	收貨國家
shippingAddress.postalCode	String	10	N	收貨地郵政編碼
shippingAddress.state	String	100	N	收貨地區
shippingAddress.city	String	300	N	收貨省市區

Response Body

Parameters	Data type	Length	requirement	Description
returnCode	String	3	Y	結果代碼
returnMessage	String	100	N	結果訊息
info.shippingMethods[].id	String		Y	商家的配送方式ID
info.shippingMethods[].name	String	100	Y	配送方式
info.shippingMethods[].amount	Number		Y	運費
info.shippingMethods[].toDeliveryYmd	String	8	Y	預計送達日期 (YYYYMMDD)
info.shippingMethods[].fromDeliveryHm	String	4	N	預計送達時間段 (起始時間，HHmm)
info.shippingMethods[].toDeliveryHm	String	4	N	預計送達時間段（結束時間，HHmm）

Return Codes

Code	Description
0000	成功
4001	該地區無法配送
4002	配送地址有誤
5001	內部伺服器錯誤（未知錯誤）
9999	系統正在維護中

Sample

Response

沒有預計送達時間的範例（只有預計送達日期）

{
    "returnCode": "0000",
    "returnMessage": "OK",
    "info": {
        "shippingMethods":[
            {
                "id": "1",
                "name": "FAST POST",
                "amount": 500,
                "toDeliveryYmd": "20181030"
            }
        ]
    }
}

使用者訊息範例

FAST POST - 500
2018/10/30 時間未設定

有預計送達日期和時間段的範例

{
    "returnCode": "0000",
    "returnMessage": "OK",
    "info": {
        "shippingMethods":[
            {
                "id": "1",
                "name": "FAST POST",
                "amount": 500,
                "toDeliveryYmd": "20181030",
                "fromDeliveryHm": "1000",
                "toDeliveryHm": "1200",
            }
        ]
    }
}

使用者訊息範例

FAST POST - 500
2018/10/30 10:00 ~ 12:00

Appendix

LINE Pay錯誤代碼

下面介紹LINE Pay中的錯誤代碼。錯誤代碼的 “returnMessage” 以英文呈現，如果沒有訊息，則顯示連字號 (-)。

Code	Description
1101	買家不是LINE Pay的用戶
1102	買方被停止交易
1104	此商家不存在
1105	此商家無法使用 LINE Pay
1106	標頭(Header)資訊錯誤
1110	無法使用的信用卡
1124	金額錯誤 (scale)
1141	付款帳戶狀態錯誤
1142	Balance餘額不足
1145	正在進行付款
1150	交易記錄不存在
1152	該transactionId的交易記錄已經存在
1153	付款request時的金額與申請confirm的金額不一致
1154	買家設定為自動付款的信用卡暫時無法使用
1155	交易編號不符合退款資格
1159	無付款申請資訊
1163	可退款日期已過無法退款
1164	超過退款額度
1165	已經退款而關閉的交易
1169	用來確認付款的資訊錯誤（請訪問LINE Pay設置付款方式與密碼認證）
1170	使用者帳戶的餘額有變動
1172	該訂單編號(orderId)的交易記錄已經存在
1177	超過允許查詢的交易數目 (100筆)
1178	商家不支援該貨幣
1179	無法處理的狀態
1180	付款時限已過
1183	付款金額不能小於 0
1184	付款金額比付款申請時候的金額還大
1190	regKey 不存在
1193	regKey 已過期
1194	此商家無法使用自動付款
1197	已在處理使用 regKey 進行的付款
1198	API重覆呼叫，或者授權更新過程中，呼叫了Capture API（請幾分鐘後重試一下）
1199	內部請求錯誤
1264	一卡通MONEY相關錯誤
1280	信用卡付款時候發生了臨時錯誤
1281	信用卡付款錯誤
1282	信用卡授權錯誤
1283	因有異常交易疑慮暫停交易，請洽LINE Pay客服確認
1284	暫時無法以信用卡付款
1285	信用卡資訊不完整
1286	信用卡付款資訊不正確
1287	信用卡已過期
1288	信用卡的額度不足
1289	超過信用卡付款金額上限
1290	超過一次性付款的額度
1291	此信用卡已被掛失
1292	此信用卡已被停卡
1293	信用卡驗證碼 (CVN) 無效
1294	此信用卡已被列入黑名單
1295	信用卡號無效
1296	無效的金額
1298	信用卡付款遭拒絕
2101	參數錯誤
2102	JSON 資料格式錯誤
9000	內部錯誤

PaymentUrl Guide

下面介紹商家應用申請付款後如何跳轉到LINE App。

Android Sample

通過以下範例程式碼，您可以檢視LINE App的安裝狀態與LINE Pay版本。確認LINE App的安裝與LINE Pay版本後，跳轉到LINE Pay的付款頁面。

Android

    int linePaySupportedVersion = 230;
    String paymentUrl = "..."; // This is "paymentUrl.app" URL String.
    Context context = getActivity();
    try {
        PackageManager pm = context.getPackageManager();
        PackageInfo packageInfo = pm.getPackageInfo("jp.naver.line.android", 0);
        int versionCode = packageInfo.versionCode;
        if (linePaySupportedVersion <= versionCode) {
        launchUri(paymentUrl);
        } else {
        confirmLineInstall(context);
        }
    } catch (NameNotFoundException e) {
        confirmLineInstall(context);
    }
    private void confirmLineInstall(Context context) {
        new AlertDialog.Builder(context)
        .setTitle("LINE Pay")
        .setMessage(getString(R.String.linepay_confirm))
        .setCancelable(false)
        .setPositiveButton(getString(R.String.linepay_install), new
    DialogInterface.OnClickListener() {
        @Override
        public void onClick(DialogInterface dialog, int which) {
        launchUri("market://details?id=jp.naver.line.android");
        }
        })
        .setNegativeButton(getString(R.String.linepay_cancel), new
    DialogInterface.OnClickListener() {
        @Override
        public void onClick(DialogInterface dialog, int which) {
        }
        })
        .show();
    }
    private void launchUri(String uriString) {
        Uri uri = Uri.parse(uriString);
        Intent intent = new Intent(Intent.ACTION_VIEW, uri);
        startActivity(intent);
    }

File : res/values/Strings.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
 ...
 <String name="linepay_confirm">Supported by Android/iPhone LINE versions 4.8.0
or higher.</String>
 <String name="linepay_install">Get it now</String>
 <String name="linepay_cancel">cancel</String>
 ...
</resources>

iPhone Sample

通過以下範例程式碼，您可以檢查LINE App是否安裝。在LINE App已安裝的情況下，跳轉到LINE Pay的付款頁面

iOS

    NSString* lineScheme = @"line://";
    BOOL installed = [[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:lineScheme]];
    if (installed) {    
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"LINE Pay"
    message:NSLocalizedString(@"linepay.confirm", nil)
            delegate:self
    cancelButtonTitle:NSLocalizedString(@"linepay.ok", nil) otherButtonTitles:nil];
            alert.tag = 1;
            [alert show];
    } else {
            UIAlertView \*alert =
            [[UIAlertView alloc] initWithTitle:@"LINE Pay"
    message:NSLocalizedString(@"linepay.confirm", nil)
            delegate:self
    cancelButtonTitle:NSLocalizedString(@"linepay.cancel", nil)
            otherButtonTitles:NSLocalizedString(@"linepay.install",
    nil), nil];
            alert.tag = 2;
            [alert show];
    }
    - (void)alertView:(UIAlertView\*)alertView
    clickedButtonAtIndex:(NSInteger)buttonIndex {
            if (alertView.tag == 1 && buttonIndex == 0) {
            NSString \*paymentUrl = ...; // This is "paymentUrl.app" URL String.
            [self launchUrl:paymentUrl];
            } else if (alertView.tag == 2 && buttonIndex == 1) {
            [self launchUrl:@"itmsapps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=443904275&mt=8"];
            }
    }
    - (void)launchUrl:(NSString\*)urlString {
            NSURL *url = [NSURL URLWithString:urlString];
            [[UIApplication sharedApplication] openURL:url];
    }

File : en.lproj/Localized.Strings

"linepay.confirm" = "Supported by Android/iPhone LINE versions 4.8.0 or higher.";
"linepay.ok" = "OK";
"linepay.cancel" = "Cancel";
"linepay.install" = "Get it now";

Sandbox

Sandbox簡介

LINE Pay提供Sandbox環境。在Sandbox環境進行測試時，利用本指南所支援的API Endpoint列表中，Sandbox專用EndPoint進行交易。 為此，需要付款頁面和用於confirmUrl的 Inquiry ShippingMethods API。 在Sandbox環境，付款流程如下進行。

Sandbox PC Payment

Sandbox Mobile Payment

注意事項

在Sandbox環境，無論是PC，還是Mobile都要用Channel進行登入。（在線上環境下，因為Mobile裝置直接使用LINE App，無需透過Channel登入）

Migration API Version 3

從Payment API v2升級v3的過程中，最大的變化是API的認證方式（HMAC Signature驗證）和Request API。

Authentication 認證

在Payment API v2上是透過ID和Password進行認證，而在v3是透過HMAC和訊息來進行認證。 X-LINE-ChannelSecret原用為v2的Password，在v3中則是建立HMAC Signature時，所需使用到的SecretKey。 當X-LINE-Authorization-Nonce使用隨機值的話，可以確保更高的Signature安全性。 請參閱API Authentication，瞭解詳情。

HTTP Request Headers

Header	Version 2	Version 3	Description
X-LINE-ChannelId	O	O	不變
X-LINE-ChannelSecret	O	X	刪除
X-LINE-MerchantDeviceProfileId	O	O	不變
X-LINE-Authorization-Nonce	X	O	新增
X-LINE-Authorization	X	O	新增

Request API

Request API v3所帶來的最大變化，就是為使用者提供豐富的產品和訂單資訊，並通過LINE使用者資訊支援更便捷的Checkout功能。 在v2中，productName和productImageUrl裡只能定義一個產品，而在v3中，因為採用package[]，為使用者能夠提供更詳細的產品交易資訊。 options.shipping可用於Checkout功能 請參閱Request API，瞭解詳情

Request Body Mapping

Version 2	Version 3	Description
amount	amount	不變
currency	currency	不變
orderId	orderId	不變
	packages[].id	new
	packages[].amount	new
	packages[].userFee	new
	packages[].name	new
	packages[].products[].id	單項產品 -> 多項產品
productName	packages[].products[].name	單項產品 -> 多項產品
productImageUrl	packages[].products[].imageUrl	單項產品 -> 多項產品
	packages[].products[].quantity	new
	packages[].products[].price	new
	packages[].products[].originalPrice	new
packageName	redirectUrls.appPackageName	修改名稱
confirmUrl	redirectUrls.confirmUrl
confirmUrlType	redirectUrls.confirmUrlType
cancelUrl	redirectUrls.cancelUrl
capture	options.payment.capture
payType	options.payment.payType
langCd	options.display.locale	修改名稱
checkConfirmUrlBrowser	options.display.checkConfirmUrlBrowser
extras.addFriends[].type	options.familyService.addFriends[].type
extras.addFriends[].idList[]	options.familyService.addFriends[].idList[]
	options.shipping.*	new