Online API

The LINE Pay Online API is a web API used for processing online payments, and all communication occurs over HTTPS. You can call APIs from anywhere as long as HTTPS is supported regardless of the operating system or the service implementation language used to develop the service. Prerequisites are required when calling the API.

To enable LINE Pay online payments, you must not only integrate the LINE Pay Online API but also implement redirection pages, which act as the interface between your service and the LINE Pay server.

Endpoint

The following is the API's endpoint format.

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

• host is the hostname of the API server.
  • Sandbox server (for tests): 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 /v3/payments/request

• Check payment request status

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

• Confirm payment

  POST /v3/payments/{transactionId}/confirm

• Capture

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

• Void

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

• Retrieve payment details

  GET /v3/payments

• Refund

  POST /v3/payments/{transactionId}/refund

• Check status of pre-approved payment key

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

• Request pre-approved payment

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

• Discard pre-approved payment key

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

Request

API requests follow the rules below.

• All API requests are sent over HTTPS.
• Parameters are 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. Specifies the device type as defined by the merchant for identification purposes. Specify with the X-LINE-MerchantDeviceProfileId header.	Optional

For information on preparing your API credentials, see Prepare API credentials.

Request body

Depending on the endpoint, 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 return an HTTP status code of 200 OK, along with the result of the request, consisting 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": "BALANCE",
        "amount": 1000
      }
    ]
  }
}

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	Returned when the request is successful. If this is the result of a payment request status check, the code indicates that The customer has not yet completed LINE Pay authentication.
0110	The customer has completed LINE Pay authentication, and you can proceed with payment confirmation.
0121	The customer canceled the payment, or the LINE Pay authentication waiting time expired.
0122	Payment failed.
0123	Payment completed.
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.
1141	There is a problem with the account status.
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.
1154	The selected payment method for pre-approved payment isn't available.
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.
1180	Payment time expired.
1183	Payment amount must exceed the minimum amount set.
1184	Payment amount must not exceed the maximum amount set.
1190	There is no pre-approved payment key.
1193	Pre-approved payment key has expired.
1194	Pre-approved payment isn't available for this merchant.
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.
2101	Parameter error occurred.
2102	JSON data format error occurred.
9000	Internal error occurred.