LINE Pay Offline API reference

# LINE Pay Offline API reference

# API specifications (payment)

Explains the APIs that are used, from reading "oneTimeKey" ("MyCode" in the LINE Pay Main menu) generated from LINE Pay User to complete payment.

  • Payment
  • Payment Status Check

# Payment

Processes payment by reading MyCode provided from the LINE Pay App on the Merchant's device.

Example request

# Table 1 Payment API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/oneTimeKeys/pay

Product: https://api-pay.line.me/v2/payments/oneTimeKeys/pay

Method

POST

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: serial no of the device

Timeout

Read: 20 seconds

# Table 2 Payment API Request Body

productName

String

Required

Product name.

Max length: 4,000

amount

Number

Required

Payment amount.

Max length: 38

currency

String

Required

Payment currency (ISO 4217 (opens new window)).

Max length: 3

orderId

String

Required

OrderId from the merchant device (unique on merchant-side).

Max length: 100

oneTimeKey

String

Required

Result of scanning and reading QR/Bar code information given by LINE Pay App.

oneTimeKey is valid for 5 minutes from the time when LINE Pay User confirms QR/Bar code after accessing the mycode screen.

The length differs by country:

  • JP: 19(from 2019.08.01)
  • TW: 18
  • TH, Global: 12

capture

Boolean

Whether to capture or not.

  • true (default): payment authorization and capture are handled at the same time.
  • false: payment is completed only after it's authorized, then separately captured by calling "Capture API".
# Extra fields

extras.addFriends

Object

Add friends List.

  • type: Service Type "LINE_AT": line@
  • idList: ID List (ID list registered at the LINE@/OA Management menu on Merchant Center)
"addFriends": [{
     "type": "LINE_AT",
     "idList": ["@aaa", "@bbb"]
}]

extras.branchName

String

Branch name from where the payment is requested. Only the first 100 letters will be displayed if it exceeds 100.

Max length: 200

extras.branchId

String

Branch ID where the payment is requested.

It supports alphanumerics and special characters.

Max length: 32

extras.promotionRestriction

Object

Promotion restriction info.

  • useLimit: amount NOT for use during Promotions
  • rewardLimit: amount NOT for rewards from Promotions
"promotionRestriction": {
    "useLimit": 100,
    "rewardLimit": 100
}

# Table 3 Payment API Response

returnCode

String

Required

Result code generated by LINE Pay.

  • 0000: API Request Success
  • You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

info.transactionId

Number

Required

LINE Pay's transaction ID.

Max length: 19

info.orderId

String

Required

OrderId from the merchant device (unique on merchant-side).

Max length: 100

info.transactionDate

String

Required

Transaction Date (ISO8601 UTC (opens new window)).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

Max length: 20

info.payInfo[].method

String

Required

Payment method used.

  • CREDIT_CARD
  • BALANCE
  • DISCOUNT
  • POINT (Default isn't displayed)

Max length: 20

info.payInfo[].amount

Number

Required

Payment amount.

Max length: 38

info.balance

Number

Remaining balance after payment.

Max length: 38

info.authorizationExpireDate

String

Authorization expiration date (ISO8601 UTC (opens new window)).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

When the payment status is "AUTHORIZATION"(capture=false).

Max length: 20

info.merchantReference.affiliateCodes[]

String

Merchant affiliated codes when corresponding to the affiliated transaction.

Max length: 20

info.merchantReference.affiliateCards[].cardType

String

Affiliated card type when corresponding to the affiliated transaction and user has an affiliate card.

Max length: 20

info.merchantReference.affiliateCards[].cardId

String

Affiliated card ID when corresponding to the affiliated transaction and user has an affiliate card.

Max length: 20

Warning

Once payment is complete, check to make sure that the total info.payInfo[].amount is the same as the request amount.

Note

To display LINE POINTS information, click on Merchant Center (opens new window), and then go to "Manage Basic Info" > "Other Information". In the section titled, "Providing the user's POINT usage information in the Payment API's response," select "Use" and pull it to the bottom to save it. However, test accounts don't include this function menu and you can only configure settings on the official merchant account.

Example response
Payment completion

Example response
Payment completion (when merchant affiliated cards exist)

# Payment status check

Used when you can't check the final payment status because of a read timeout.

  • You must check the status by calling the API at regular intervals, with 3-5 seconds being the recommended interval time.
  • The maximum valid time for a transaction is 20 minutes, which is calculated from the Payment API Response time. Accordingly, a merchant should check the payment status for up to 20 minutes. If the transaction exceeds 20 minutes, it will result in an incomplete payment.

Example request

# Table 4 Payment Status Check API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/check

Product: https://api-pay.line.me/v2/payments/orders/{orderId}/check

Method

GET

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: device’s serial no

Timeout

Read: 20 seconds

# Table 5 Payment Status Check API URI Parameters

orderId

String

Required

The order ID delivered when a merchant requests for payment. Needs to be delivered after encoding to the parameter that exists in URI path.

*Reference: Percent-encoding (opens new window)

Max length: 100

# Table 6 Payment Status Check API Response

returnCode

String

Required

Result code.

  • 0000: API Request Success
  • You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages.

Max length: 100

info.status

String

Required

Payment status.

  • COMPLETE: payment completed. - terminated status
  • FAIL: payment failed. - terminated status
  • Note: Based on whether it's "COMPLETE" or "FAIL," there will be respective response information.

Max length: 20

# Case "info.status": "COMPLETE"

info.orderId

String

Required

Order ID given by the merchant device (unique on merchant-side).

Max length: 100

info.transactionDate

String

Required

Transaction Date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

info.payInfo[].method

String

Required

Payment method used.

  • CREDIT_CARD
  • BALANCE
  • DISCOUNT
  • POINT

Max length: 20

info.payInfo[].amount

Number

Required

Payment amount.

Max length: 38

info.balance

Number

Remaining balance after payment.

Max length: 38

info.authorizationExpireDate

String

Authorization Expire Date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

when the payment status is "AUTHORIZATION" (capture=false).

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

# Case "info.status": "FAIL"

info.failReturnCode

String

Required

Fail result code. For the response codes, check "Appendix - Response Code by API" in this document. The response codes are the same as the Payment API's response codes.

Max length: 4

info.failReturnMessage

String

Required

Fail result messages.

Max length: 100

Status = COMPLETE Example response

Status = FAIL Example response

Warning

Once payment is complete, check to make sure that the total info.payInfo[].amount is the same as the request amount.

# API specifications (after payment)

Explains the API for a payment refund or a payment history search, depending on the merchant order status after the payment is completed.

# Void

Voids the authorization.

Example request

# Table 7 Void API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/void

Product: https://api-pay.line.me/v2/payments/orders/{orderId}/void

Method

POST

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: the serial no of the device

Timeout

Read: 20 seconds

# Table 8 Void API URI Parameters

orderId

String

Required

The order ID delivered when a merchant requests for payment. Needs to be delivered after encoding to the parameter that exists in URI path.

*Reference: Percent-encoding (opens new window)

Max length: 100

# Table 9 Void API Response

returnCode

String

Required

Result code that LINE Pay generates.

  • 0000: Request Success

You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

Example response - Payment complete

Caution

If the merchant can't check the process status because of a read timeout, the merchant must check the status through the Authorization Details API.

# Capture

Captures the authorized transaction.

Example request

# Table 10 Capture API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/capture

Product: https://api-pay.line.me/v2/payments/orders/{orderId}/capture

Method

POST

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: device’s serial no

Timeout

Read: 20 seconds

# Table 11 Capture API URI Parameters

orderId

String

Required

The order ID delivered when a merchant requests for payment. Needs to be delivered after encoding to the parameter that exists in URI path.

*Reference: Percent-encoding (opens new window)

Max length: 100

# Table 12 Capture API Request Body

amount

Number

Required

Amount to capture.

Max length: 38

currency

String

Required

Currency to capture.

Max length: 3

extras.promotionRestriction

Object

Promotion Restriction info.

  • useLimit: amount NOT for use during Promotions.
  • rewardLimit: amount NOT for rewards from Promotions

"promotionRestriction": {"useLimit": 100, "rewardLimit": 100}

# Table 13 Capture API Response

returnCode

String

Required

Result code generated by LINE Pay.

  • 0000: API Request Success

You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

info.transactionId

Number

Required

LINE Pay's transaction ID.

Max length: 19

info.orderId

String

Required

Order ID from merchant device (unique on merchant-side).

Max length: 100

info.payInfo[].method

String

Required

Payment method used.

  • CREDIT_CARD
  • BALANCE
  • DISCOUNT
  • POINT (Not displayed by default).

Max length: 20

info.payInfo[].amount

Number

Required

Payment amount.

Max length: 38

Example response

# Refund

Refunds after the payment completion process (Captured data).

Example request

# Table 14 Refund API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/refund

Product: https://api-pay.line.me/v2/payments/orders/{orderId}/refund

Method

POST

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: device's serial no

Timeout

Read: 20 seconds

# Table 15 Refund API URI Parameters

orderId

String

Required

The order ID delivered when a merchant requests for payment.nNeeds to be delivered after encoding to the parameter that exists in URI path.

*Reference: Percent-encoding (opens new window)

Max length: 100

# Table 16 Refund API Request Body

refundAmount>

Number

Refund amount. Full refund if this parameter isn't passed.

Max length: 38

# Extra fields

extras.promotionRestriction

Object

Promotion Restriction info.

  • useLimit: amount NOT for use during promotions.
  • rewardLimit: amount NOT for rewards from promotions.

"promotionRestriction": {"useLimit": 100, "rewardLimit": 100}

# Table 17 Refund API Response

returnCode

String

Required

Result code that LINE Pay generates.

  • 0000: API Request Success
  • You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

info.refundTransactionId

Number

Required

LINE Pay's refund transaction ID.

Max length: 19

info.refundTransactionDate

String

Required

Refunded transaction date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: ISO 8601 (opens new window)

Max length: 20

Example response

# Authorization details

Searches for authorization details. You can only search for authorized or cancelled (Void or Expired) data. Thereafter, you can use the Payment Details API to search for captured data.

Example request

# Table 18 Authorizaiton Details API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments/authorizations

Product: https://api-pay.line.me/v2/payments/authorizations

Method

GET

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: device’s serial no

Timeout

Read: 20 seconds

# Table 19 Authorization Details API Query Parameters

orderId

String

The order ID delivered when a merchant requests for payment.

Max length: 100

transactionId

Number

LINE Pay's transaction ID.

Max length: 19

Warning

At least one orderId or transactionId must be delivered. You can search the details of a maximum of 100 transactions at a time.

# Table 20 Authorization Details API Response

returnCode

String

Required

Result code that LINE Pay generates.

  • 0000: Request Success

You can find other response codes in "Appendix - Response Code by API".

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

info.transactionId

Number

Required

LINE Pay's transaction ID.

Max length: 19

info.orderId

String

Required

Order ID from the merchant device (unique on merchant-side).

Max length: 100

info.transactionDate

String

Required

Transaction Date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

info.transactionType

String

Required

Transaction Type.

  • PAYMENT: Payment
  • PAYMENT_REFUND: Refund
  • PARTIAL_REFUND: Partial refund

Max length: 20

info.payInfo[].method

String

Required

Payment method used.

  • CREDIT_CARD
  • BALANCE
  • DISCOUNT
  • POINT (Not displayed by default).

Max length: 20

info.payInfo[].amount

Number

Required

Payment amount.

Max length: 38

info.currency

String

Required

Payment currency (ISO 4217 (opens new window)).

*Reference: https://en.wikipedia.org/wiki/ISO_4217

Max length: 3

info.productName

String

Required

Product name.

info.payStatus

String

Required

Payment status.

  • AUTHORIZATION: Authorization
  • VOIDED_AUTHORIZATION: Voided Authorization (Completed status by calling "void api")
  • EXPIRED_AUTHORIZATION: Expired Authorization (The status which allowed Authorization period for a merchant has passed.)

Max length: 30

info.authorizationExpireDate

String

Authorization Expire Date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

info.merchantReference.affiliateCodes[]

String

Merchant affiliated Codes when corresponding to the affiliated transaction.

Max length: 20

info.merchantReference.affiliateCards[].cardType

String

Affiliated card type when corresponding to the affiliated transaction and user has an affiliate card.

Max length: 20

info.merchantReference.affiliateCards[].cardId

String

Affiliated card id when corresponding to the affiliated transaction and user has an affiliate card.

Max length: 20

Example response

# Payment details

Searches for the transaction data after capturing.

Example request

# Table 21 Payment Details API Endpoint

Endpoint URL

Sandbox: https://sandbox-api-pay.line.me/v2/payments

Product: https://api-pay.line.me/v2/payments

Method

GET

Request Header

Required

Content-Type: application/json; charset=UTF-8

  • X-LINE-ChannelId:
  • X-LINE-ChannelSecret:

Set mandatory or optional in the merchant setting information.

  • X-LINE-MerchantDeviceType: device type
  • X-LINE-MerchantDeviceProfileId: device’s serial no

Timeout

Read: 20 seconds

# Table 22 Payment Details API Query Parameters

orderId

String

The order ID delivered when a merchant requests for payment.

Max length: 100

transactionId

Number

LINE Pay’s transaction ID.

Max length: 19

Warning

At least one orderId or transactionId must be delivered. You can search the details of a maximum of 100 transactions at a time.

# Table 23 Payment Details API Response

returnCode

String

Required

Result code that LINE Pay generates.

  • 0000: API Request Success
  • You can find other response codes in "Appendix - Response Code by API".

Max length: 4

returnMessage

String

Required

Result messages or reason for failure.

Max length: 100

info.transactionId

Number

Required

LINE Pay's transaction id.

Max length: 19

info.orderId

String

Required

OrderId from the merchant device (Unique on merchant-side).

Max length: 100

info.transactionDate

String

Required

Transaction Date(ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

info.transactionType

String

Required

Transaction Type.

  • PAYMENT: payment
  • PAYMENT_REFUND: refund
  • PARTIAL_REFUND: partial refund

Max length: 20

info.payInfo[].method

String

Required

Payment method used.

  • CREDIT_CARD
  • BALANCE
  • DISCOUNT
  • POINT (Not displayed by default)

Max length: 20

info.payInfo[].amount

Number

Required

Payment amount.

Max length: 38

info.currency

String

Required

Payment currency (ISO 4217 (opens new window)).

*Reference: https://en.wikipedia.org/wiki/ISO_4217

Max length: 3

info.productName

String

Required

Product name.

Max length: 4,000

# Retrieving original transactions & when there is a refund

info.refundList[].refundTransactionId

Number

Required

Refunded transaction ID.

Max length: 19

info.refundList[].transactionType

String

Required

Transaction type.

  • PAYMENT_REFUND: refund
  • PARTIAL_REFUND: partial refund

Max length: 20

info.refundList[].refundAmount

Number

Required

Refund amount.

Max length: 38

info.refundList[].refundTransactionDate

String

Required

Refunded transaction date (ISO8601 UTC).

  • Time Format: yyyy-MM-dd'T'HH:mm:ss'Z'

*Reference: https://en.wikipedia.org/wiki/ISO_8601

Max length: 20

# When retrieving a refund

info.originalTransactionId

Number

Required

Original payment transaction number.

Max length: 19

Note

To display LINE POINTS information, go to the LINE Pay site (opens new window), and then select "Manage Basic Info" > "Other Information". In the section titled "Providing the user's POINT usage information in the Payment API's response," select "Use" and pull it to the bottom to save it. However, test accounts don't include this function menu and you can only configure settings on the official merchant account.

Example response