跳轉至主體

Offline API v4

LINE Pay Offline API是一種web API，用於使用合作商店終端機處理實體付款，並透過HTTPS進行通訊。無論營運系統或服務執行語言為何，如果支援HTTPS，就可以從任何地方呼叫API。呼叫API時需要提前準備。

端點​

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格式的請求傳遞至主體。

請求標頭​

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

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

有關如何準備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-TypeStringapplication/json始終

Response body​

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

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

成功回應​

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

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

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

錯誤回應​

如果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請求已成功完成。
1101該用戶不是LINE Pay用戶。
1102該用戶目前無法使用LINE Pay交易。
1104您的商店尚未在合作商店中心註冊成為合作商店。請確認輸入的credentials是否正確。
1105該合作商店目前無法使用LINE Pay。
1106請求標頭訊息有錯誤。
1110該信用卡無法正常使用。
1124金額訊息有誤。
1133無效的我的條碼(oneTimeKey)。
1141帳戶狀態有問題。如為EPI交易，商家有可能未開通EPI支付方式。
1142餘額不足。
1145付款進行中。
1150無交易歷史。
1152有相同交易歷史。
1153付款請求金額和請款金額不同。
1155交易ID有誤。
1159無付款請求訊息。
1163無法退款。(超過可退款期限)
1164超出可退款金額。
1165已退款的交易。
1169須在LINE Pay中選擇付款方式並驗證認證密碼。
1170會員帳戶餘額發生變化。
1172已存在相同訂單號碼的交易記錄。
1177超出可查看的最多交易數量。(100筆)
1178合作商店不支援該貨幣。
1179無法處理該狀態。
1183付款金額必須大於設定的最低金額。
1184付款金額必須小於設定的最高金額。
1198API呼叫請求重複。
1199內部請求發生錯誤。
1280信用卡付款時發生臨時錯誤。
1281信用卡付款時發生錯誤。
1282信用卡授權時發生錯誤。
1283有不當使用疑慮，付款被拒絕。
1284信用卡付款暫時暫停。
1285信用卡付款訊息缺失。
1286信用卡付款訊息中有錯誤訊息。
1287信用卡已過期。
1288信用卡帳戶餘額不足。
1289超出信用卡額度。
1290超出信用卡單筆付款額度。
1291該卡已被通報失竊。
1292該卡已停用。
1293CVN輸入錯誤。
1294該卡已被列入黑名單。
1295信用卡號碼錯誤。
1296無法處理此金額。
1298該卡被拒絕。
190X發生臨時錯誤。請稍後再試一次。
1999(重試請求時)與先前請求的訊息不同。
2020在電子支付機構（EPI）支付流程的預授權階段，未能預留支付金額的限額。
2021在EPI支付過程中，超出受限用戶（受處罰ID用戶，PID用戶）的支付限額。
2022在EPI支付過程中，超出使用者的支付限額。
2023在特定商戶處，超出個別使用者每筆交易、每日或每月允許的限額。
2024超出商戶每筆交易、每日或每月可收款的限額。
2042由於商戶的退款準備金不足，未能為EPI支付進行退款。
2101參數錯誤。
2102JSON數據格式錯誤。
2103輸入了不允許的參數。
2104無效的請求。請檢查結果訊息。
9000發生了內部錯誤。