NAV Navbar
  • Online APIs
  • OverView
  • Payment APIs
  • Merchant provided API or Page
  • Appendix
  • Online APIs

    OverView

    LINE Pay

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

    Payment process LINE Pay支付流程

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

    LINE Pay商家註冊流程

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

    Cn register merchant

    註冊流程

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

    一般付款

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

    PC環境

    Pc payment reserve complete

    PC付款頁面-付款完成

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

    行動裝置環境

    Mobile payment reserve complete

    行動裝置環境-付款完成

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

    授權與請款分開

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

    confirmUrl的Server-to-Server

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

    Send confirm url server to server

    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

    Checkout (Only Japan)

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

    Checkout Flow

    Cn 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

    收貨人的firstNamelastNamefirstNameOptionallastNameOptional,必須分別用漢字和片假名寫入。

    相關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. 交易完成

    Preapproved payment

    自動付款

    1. 請求regKey作廢處理,停止自動付款
      1. 呼叫Expire regKey API
      2. 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

    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

    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的作用如下。

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

    LINE Pay Server向Merchant Server請求confirmUrl

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

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

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

    Options

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

    Payment

    設定付款選項

    payType

    Display

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

    locale

    使用者等待付款頁語言

    FamilyService

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

    addFriends

    提供新增好友(LINE@)功能。

    Example

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

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

    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

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

    API Spec

    POST /v3/payments/{transactionId}/confirm

    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 LINE Pay一卡通相關錯誤
    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

    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 LINE Pay一卡通相關錯誤
    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

    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

    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 LINE Pay一卡通相關錯誤
    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

    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

    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

    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 APIConfirm API,設定自動付款。通過Confirm API回應的RegKey,不經使用者確認,可以直接進行付款。

    API Spec

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

    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

    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。

    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

    Key Value Description
    Content-Type application/json
    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 LINE Pay 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進行交易。 為此,需要付款頁面和用於confirmUrlInquiry ShippingMethods API。 在Sandbox環境,付款流程如下進行。

    Sandbox PC Payment

    Sandbox pc payment process

    Sandbox Mobile Payment

    Sandbox mobile payment process

    注意事項

    在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中,productNameproductImageUrl裡只能定義一個產品,而在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