Offline API v4

The LINE Pay Offline API is a web API for offline payments processed through a merchant's terminal and all communication occurs over HTTPS. APIs can be called from any environment that supports HTTPS, regardless of the operating system or programming language. Make sure to meet the prerequisites before calling the API.

Endpoint

The following is the API's endpoint format.

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

• host is the hostname of the API server.
  • Sandbox server (for testing): sandbox-api-pay.line.me
  • Production server (for actual service): api-pay.line.me
• apiPath is the specific path of the API being called. This includes the API version and can be found in the detailed documentation of each endpoint.
• queryString is a set of query parameters. Each parameter is a key=value pair, separated by &.

You can find the following endpoints.

• Request payment

  POST /v4/payments/oneTimeKeys/pay

• Check payment status

  GET /v4/payments/orders/{orderId}/check

• Retrieve confirmation information

  GET /v4/payments/authorizations

• Capture

  POST /v4/payments/orders/{orderId}/capture

• Void

  POST /v4/payments/orders/{orderId}/void

• Retrieve payment details

  GET /v4/payments

• Refund

  POST /v4/payments/orders/{orderId}/refund

Request

API requests follow the rules below.

• All API requests are sent over HTTPS.
• Parameters can be passed via path, query, or as a JSON-formatted request body.

Request header

API requests commonly require the following headers.

Header name (key)	Data type	Description	Required
Content-Type	String	Set to application/json.	Required
X-LINE-Authorization	String	Credentials generated by the HMAC SHA256 algorithm	Required
X-LINE-Authorization-Nonce	String	A randomly generated UUID. Version 1 or 4, or timestamp if requested	Required
X-LINE-ChannelId	String	Channel ID	Required
X-LINE-MerchantDeviceProfileId	String	Device profile ID. You can view device-specific statistics in reports provided by LINE Pay. The ID is typically the serial number of the merchant’s terminal and is used as needed. Include this header together with X-LINE-MerchantDeviceType.	Optional
X-LINE-MerchantDeviceType	String	Device type. Specify the device type as defined by the merchant for identification purposes. Use together with the X-LINE-MerchantDeviceProfileId header.	Optional

For information on preparing your API credentials, see Prequisites.

Request body

For specific endpoints, parameters can be delivered in a request body. The request body is in the form of a JSON object.

Below is an example of the request body.

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

Response

API responses always include an HTTP status code 200 OK and delivers the result of the request, which consists of a response header and a response body.

Response header

API responses commonly include the following headers.

Header name (key)	Data type	Description	Included
Content-Type	String	application/json	Always

Response body

The response body is a JSON object that contains detailed request results and includes the following fields.

Field name	Data type	Description	Included
info	Object	API request result data. The data is included in the response only when the API call is successful.	Conditional
returnCode	String	Result code	Always
returnMessage	String	Message corresponding to returnCode	Always

Success response

If the API request is processed successfully, the response body sets returnCode to 0000. If result data is available, it is returned in the info field.

Below is an example of the response body of a successful API request.

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

Error response

If there is an error in the API request, the server considers the error as a failure and returns a result code corresponding to the cause of the error. The response body of a failed API request delivers error information, and the info field isn't returned in such cases.

Below is an example of the response body of a failed API request.

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

Transaction ID

Transaction is a concept for the actions performed by the LINE Pay server during the payment process. Actions such as payment request, payment confirmation, capture, and refund are all considered transactions. Transaction ID is a 19-digit integer value used to identify these actions. LINE Pay server returns a transaction ID when an action is processed, and you can use the ID to retrieve information about that transaction or request an action for that transaction.

The transaction ID should be processed as a 64-bit long integer. If there are problems with processing the ID as a 64-bit long integer, convert the ID to string. For example, another system that cannot process a 64-bit long integer may process the ID as an integer data type and recognize the ID as 2023010112345678800 even if the LINE Pay server sends 2023010112345678910.

Below is an example of JavaScript code to avoid the said issue. The following is an example of processing values greater than the maximum safe integer (2^53 - 1) in JavaScript as strings after handling LINE Pay API responses as plain text and before parsing them into JSON objects. The code below converts any sequence of 16 or more consecutive digits in the response value into a string.

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;
}

Result code

The result of the API call consists of the result code (returnCode) and the result message (returnMessage) as shown below. See the following table.

If a result code isn't accompanied by a specific message, a hyphen symbol (-) is delivered as a message.

Result code	Description
0000	The request is successful.
1101	The customer isn't a LINE Pay user.
1102	The customer is currently unable to make transactions with LINE Pay.
1104	The merchant isn't registered on the merchant center. Check if the correct credentials are entered.
1105	LINE Pay is currently unavailable for the merchant.
1106	There is an error in the request header information.
1110	The credit card cannot be used.
1124	There is an error in the amount information.
1133	This is an invalid My Code (oneTimeKey).
1141	There is a problem with the account status. In case of EPI transaction, the merchant may not have enabled the EPI payment method.
1142	The balance is insufficient.
1145	Payment is in progress.
1150	There are no transaction details.
1152	There is a duplicate transaction.
1153	The payment request amount and the capture amount differ.
1155	This is an invalid transaction ID.
1159	There is no payment request information.
1163	Refund isn't available (refund period has expired).
1164	Exceeded the refundable amount.
1165	The transaction has already been refunded.
1169	LINE Pay requires payment method selection and password authentication.
1170	The balance in the member's account has changed.
1172	Transaction details with the same order ID already exist.
1177	Exceeded the maximum number of transactions that can be retrieved. (100)
1178	The currency isn't supported by the merchant.
1179	Cannot be processed at the moment.
1183	Payment amount must exceed the minimum amount set.
1184	Payment amount must not exceed the maximum amount set.
1198	API request is duplicated.
1199	Internal error occurred during the request.
1280	Temporary error occurred during credit card payment.
1281	Error occurred during credit card payment.
1282	Error occurred during credit card authorization.
1283	Payment was denied due to suspected fraudulent use.
1284	Credit card payment is temporarily suspended.
1285	Credit card payment information is missing.
1286	Credit card payment information is incorrect.
1287	Credit card expiration date has passed.
1288	Insufficient balance in the credit card account
1289	Exceeded the credit card limit.
1290	Exceeded the per-transaction limit for credit card payments.
1291	This card is reported stolen.
1292	Card usage is suspended.
1293	CVN input error occurred.
1294	This card is on the blacklist.
1295	The credit card number is incorrect.
1296	This amount cannot be processed.
1298	Card use was declined.
190X	Temporary error occurred. Please try again later.
1999	(On retry) The request information differs from the previous request.
2020	Failed to reserve the limit for the payment amount during the pre-authorization stage of the Electronic Payment Institution (EPI) payment process.
2021	Exceeded restricted user (Punished ID user, PID user) payment limit during an EPI payment.
2022	Exceeded the user's payment limit during an EPI payment.
2023	Exceeded an individual user's per-transaction, daily, or monthly limit allowed at a specific merchant.
2024	Exceeded the merchant's per-transaction, daily, or monthly limit for receiving payments.
2042	Failed to refund for an EPI payment, due to the merchant's insufficient refund reserve.
2101	Parameter error occurred.
2102	JSON data format error occurred.
2103	Unauthorized parameter has been entered.
2104	This is an invalid request. Please check the result message.
9000	Internal error occurred.