Online API

LINE Pay Online API是為處理線上付款操作的web API，並透過HTTPS通訊。無論營運系統或服務執行語言為何，如果支援 HTTPS，就可以從任何地方呼叫API。呼叫API時需要提前準備。

若要提供LINE Pay線上付款，不僅要使用LINE Pay提供的Online API，亦需要執行提供給LINE Pay伺服器的介面重定向頁面。

端點

API的端點格式如下。

https://{host}/{apiPath}?{queryString}

host是API伺服器的主機。
- Sandbox伺服器（用於測試）：sandbox-api-pay.line.me
- 正式伺服器（用於實際服務）：api-pay.line.me
apiPath是要呼叫的API的路徑。可以在每個端點的詳細描述中進行檢查。API版本也包含在apiPath中。
queryString是一組查詢參數。每個參數都是一個key=value對，並用&區分。

端點如下。

請求

API請求遵循以下規則。

所有API請求均透過HTTPS傳送。
參數可以作為路徑(path)、查詢(query)或JSON格式的request body傳遞。

請求標頭

API請求通常需要以下共同標頭。

標頭名稱(key)	資料型別	描述	是否必需
`Content-Type`	String	設定`application/json`。	必填
`X-LINE-Authorization`	String	HMAC SHA256 演算法生成的credentials	必填
`X-LINE-Authorization-Nonce`	String	隨機生成的UUID。版本1或版本4，或請求時提供時間戳記	必填
`X-LINE-ChannelId`	String	通訊管道ID	必填
`X-LINE-MerchantDeviceProfileId`	String	設備配置文檔 ID。以後，可以在LINE Pay提供的報告書中確認不同裝置的統計。主要輸入合作商店終端機的序號，必要時可使用。請與`X-LINE-MerchantDeviceType`標頭一同輸入。	選填
`X-LINE-MerchantDeviceType`	String	設備類型。請指定合作商店用於區分指定的設備類型。請與`X-LINE-MerchantDeviceProfileId`標頭一同指定。	選填

有關如何準備API credentials，請參閱準備API credentials。

Request body

不同端點可以在request body中傳遞參數。Request body採用JSON格式。

以下為request body的範例。

{
  "productName": "Brown pen",
  "amount": 1000,
  "currency": "TWD",
  "orderId": "Ord2018123100000001"
}

回應

API回應始終傳回HTTP狀態碼200 OK，並傳遞由回應標頭和response body組成的請求結果。

回應標頭

API回應通常需要以下共同標頭。

標頭名稱(key)	資料型別	描述	是否包含
`Content-Type`	String	`application/json`	始終

Response body

Response body是一個包含詳細請求結果的JSON對象，包含以下欄位。

欄位名稱	資料型別	描述	是否包含
`info`	Object	API 請求結果數據。只有當API呼叫成功時，才會包含在回應中。	有條件
`returnCode`	String	結果程式碼	始終
`returnMessage`	String	`returnCode`相應的消息	始終

成功回應

如果API請求處理沒有問題，則response body將returnCode設為0000，並且任何結果資料都會在info欄位中傳遞。

以下是成功API請求的response body範例。

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

錯誤回應

如果API請求出現錯誤，伺服器會認為失敗，並傳回與錯誤原因對應的結果碼。失敗的API請求的response body中傳遞錯誤訊息，不傳回info欄位。

以下是失敗的API請求的response body範例。

{
  "resultCode": 1104,
  "statusMessage": "Merchant not found."
}

交易ID

交易為LINE Pay伺服器處理付款流程時，區分處理的操作概念，付款請求、付款授權、請款、退款等操作均屬於交易。交易ID使用19位整數辨識這些作業。LINE Pay伺服器處理任務時，會傳回交易ID，可以使用該交易檢索訊息或要求處理相關任務。

交易ID必須處理為64位長整數(long integer)。如果將其作為64位長整數類型處理時出現問題，請將其轉換為字串(string)並進行處理。例如，即使LINE Pay伺服器發送值2023010112345678910，如果另一個無法處理 64 位長整數值的系統將其視為長整數資料類型，則可能會被識別為2023010112345678800。

以下是為了避免上述問題的 JavaScript 程式碼範例。這是將LINE Pay API 回應處理為純文本後，使用 JSON 客體解析(parse)前，在JavaScript中可用安全整數值(2^53 - 1)，將範圍之外的值處理為字串的範例。如果回應值出現 16 位以上連續數字，下面的程式碼會將回應值變更為字串。

function handleBigInteger(text) {
  const largeNumberRegex = /:\s*(\d{16,})\b/g;
  const processedText = text.replace(largeNumberRegex, ': "$1"');

  const data = JSON.parse(processedText);

  return data;
}

async function requestLINEPayAPI({
  method = "GET",
  baseUrl = "https://sandbox-api-pay.line.me",
  apiPath,
  queryString = "",
  data = {},
}) {
  // ...

  const response = await fetch(
    `${baseUrl}${apiPath}${queryString !== "" ? "&" + queryString : ""}`,
    {
      // ...
    }
  );

  const processedResponse = handleBigInteger(await response.text());

  return processedResponse;
}

結果程式碼

API呼叫結果以結果程式碼(returnCode)和結果訊息(returnMessage)的形式提供，如下所示。請參考下表。

未提供單獨訊息的結果程式碼將作為帶有連字符(-)的訊息發送。

結果程式碼	Description
`0000`	是請求成功執行時傳遞的代碼。如果是查詢付款請求狀態的結果，則該狀態是顧客完成LINE Pay認證之前的狀態。
`0110`	顧客已完成LINE Pay認證，可以進行付款授權。
`0121`	顧客取消付款或超過LINE Pay認證等待時間。
`0122`	付款失敗。
`0123`	付款完成。
`1101`	該用戶不是LINE Pay用戶。
`1102`	該用戶目前無法使用LINE Pay交易。
`1104`	您的商店尚未在合作商店中心註冊成為合作商店。請確認輸入的credentials是否正確。
`1105`	該合作商店目前無法使用LINE Pay。
`1106`	請求標頭訊息有錯誤。
`1110`	該信用卡無法正常使用。
`1124`	金額訊息有誤。
`1141`	帳戶狀態有問題。
`1142`	餘額不足。
`1145`	付款進行中。
`1150`	無交易歷史。
`1152`	有相同交易歷史。
`1153`	付款請求金額和請款金額不同。
`1154`	無法使用設定為預先授權付款的付款方式。
`1155`	交易ID有誤。
`1159`	無付款請求訊息。
`1163`	無法退款。(超過可退款期限)
`1164`	超出可退款金額。
`1165`	已退款的交易。
`1169`	須在LINE Pay中選擇付款方式並驗證認證密碼。
`1170`	會員帳戶餘額發生變化。
`1172`	已存在相同訂單號碼的交易記錄。
`1177`	超出可查看的最多交易數量(100筆)。
`1178`	合作商店不支援該貨幣。
`1179`	無法處理該狀態。
`1180`	已超過付款期限。
`1183`	付款金額必須大於設定的最低金額。
`1184`	付款金額必須小於設定的最高金額。
`1190`	無預先授權付款密鑰。
`1193`	預先授權付款密鑰已逾期。
`1194`	合作商店不支援預先授權付款。
`1198`	API呼叫請求重複。
`1199`	內部請求發生錯誤。
`1280`	信用卡付款時發生臨時錯誤。
`1281`	信用卡付款時發生錯誤。
`1282`	信用卡授權時發生錯誤。
`1283`	有不當使用疑慮，付款被拒絕。
`1284`	信用卡付款暫時暫停。
`1285`	信用卡付款訊息缺失。
`1286`	信用卡付款訊息中有錯誤訊息。
`1287`	信用卡已過期。
`1288`	信用卡帳戶餘額不足。
`1289`	超出信用卡額度。
`1290`	超出信用卡單筆付款額度。
`1291`	該卡已被通報失竊。
`1292`	該卡已停用。
`1293`	CVN輸入錯誤。
`1294`	該卡已被列入黑名單。
`1295`	信用卡號碼錯誤。
`1296`	無法處理此金額。
`1298`	該卡被拒絕。
`190X`	發生臨時錯誤。請稍後再試一次。
`2101`	參數錯誤。
`2102`	JSON數據格式錯誤。
`9000`	發生了內部錯誤。

端點​

付款請求

查詢付款請求狀態

付款授權

請款

取消授權

查詢付款明細

退款

檢查預先授權付款密鑰狀態

預先授權付款請求

刪除預先授權付款密鑰

請求​

請求標頭​

Request body​

回應​

回應標頭​

Response body​

成功回應​

錯誤回應​

交易ID​

結果程式碼​

端點

請求