Introduction
This chapter explains the basic concept of using LINE Pay.
About LINE Pay
LINE Pay is a payment system that LINE users can use on LINE Pay Merchant’s websites
Figure 1 LINE Pay Payment Process
If a merchant is registered as a LINE Pay Merchant, it can attract LINE users around the world as its customers. Also, the merchant's revenue is expected to grow when its marketing channels are expanded through LINE. For LINE Pay users to make payments using LINE Pay, the website must be registered as a LINE Pay Merchant.
LINE Pay Merchant Registration Process
Once a merchant is registered as a LINE Pay Merchant, an integration key and test key are issued. Merchant registration process is as follows.
Figure 2 Merchant Registration Process
- Access the Registration Page (http://pay.line.me)
- Fill out basic information and submit required documents.
- Merchant registration review.
- Consent to fees and settlement cycles and enter identity verification PIN.
- Merchant registration completed.
- Email sent upon completion of registration.
LINE PAY Features
The following features are provided.
Normal Payment
Normal payment is a payment type where a payment is made after LINE Pay users access LINE Pay, select a payment method and enter their payment password. The payment is completed when captured. When Merchants want to separate the authorization of payment from the capture of the authorized payment, they should call "Capture API" Depending on the payment method selected when the password is confirmed, the amount of money to be paid is deducted from the buyers' balance or credit card limit.
- The Merchant server calls "Reserve Payment API".
- The buyer selects a payment method and enters the payment password on the LINE Pay payment screen.
- The Merchant server calls "Confirm Payment API”.
- The payment transaction is completed.
Preapproved Payment
Preapproved payment is made between Merchant server and LINE Pay server, without LINE Pay user intervention. When a LINE Pay user first makes a payment, LINE Pay issues a regKey for preapproved payment, to the Merchant, which goes through payment reservation and confirmation process, like the normal payment. Since then, the Merchant can use the issued regKey to complete following transactions by calling the Preapproved Payment API, without using the LINE app.
- First payment and regKey (for preapproved payment) issuance
a.The Merchant server calls the Reserve Payment API ("payType" : "PREAPPROVED")
b. The LINE Pay user is redirected to the confirmUrl (a parameter of the Reserve Payment API) after selecting a payment method and entering the payment password on the LINE Pay payment screen.
c.The Merchant server calls the Confirm Payment API and saves a regKey returned as response information.
d. The payment transaction is completed - Preapproved payment
a. The Merchant uses the regKey to call the preapproved payment API.
b. The payment transaction is completed. - Expire regKey Request to expire preapproved payment
a. Call API to expire the regKey
b. Expire preapproved payment
Common Features
- Get Payment details
- Refund Request
- Get Authorization details
- Void Authorization Request
LINE Pay Payment Status
This chapter explains about status from payment request to payment completion.
- RESERVE : Calling Payment Reserve API, First Time Status
- AUTH : Select a Payment Method from LINE Pay app and an Authorization for a Payment Password from LINE Pay app succeeded
- CANCEL : Cancelling a Payment from LINE Pay app
- CAPTURE_WAIT : Capture Status shows Wait (When a “Capture” parameter of Reserve API is delivered as a “False”.)
- CAPTURE : Capture
- VOID : Cancelling a Capture in Wait Status of a Capture.
- REFUND : Refund After a Capture
LINE Pay Integration Flow
Normal Payment
Request Payment – Payment Screen
The payment reservation process, which differs depending on LINE Pay users' access environment, is shown below:
- For PC
Figure 3 Payment reservation process for PC - Payment screen
- The LINE Pay user selects a payment method from the Merchant's purchase order.
- The Merchant calls LINE Pay's "Payment Reserve API" to create payment reservation information and gets a transaction Id, which is required information for payment confirmation and must be kept by the Merchant, and "paymentUrl."
- The Merchant calls the paymentUrl (provided by LINE Pay) received in step b.
- The LINE Pay user goes through channel web login1 that checks if the user is a LINE user.
4.1. This is a process of verifying if the user is a LINE user before using LINE services. The channel web login process is skipped if the Merchant can access the LINE user information and forward mid when reserving payment. - The LINE Pay server pushes a payment request to LINE after the user successfully logs in to LINE.
- The LINE user gets notified of the payment request on the LINE app and moves to the payment screen.
- For mobile
Figure 4 Payment reservation for mobile - payment screen
- The LINE Pay user selects a payment method from the Merchant's purchase order.
- The Merchant calls LINE Pay's "Reserve Payment API" to create payment reservation information and gets a transaction Id, which is required information for payment confirmation and must be kept by the Merchant, and "paymentUrl."
- The Merchant calls the paymentUrl (provided by LINE Pay) received in step b.
- Using the paymentUrl, the Merchant redirects the LINE Pay user to the payment screen in the LINE app.
The paymentUrl is divided into web and app, depending on the integration environment.
• web: A web screen provided by LINE Pay. The Merchant checks whether the LINE app is installed before redirecting the user to the LINE Pay payment screen.
• app: An app scheme URL to directly move to the LINE Pay payment screen. For how to check whether the LINE app is installed and available versions of LINE Pay (for Android only), please refer to How to use PaymentUrl App Guide
Payment Screen - Payment Completion
After selecting a payment method (credit card or balance) to process the payment, the LINE Pay user moves to the "confirmUrl" (added by transactionId in LINE Pay) received from the Merchant when the payment is reserved. Then, the Merchant calls the "Payment confirm API " to complete the payment.
- For PC
Figure 5 Payment screen for PC –Payment completion
- The LINE Pay user selects a payment method on the LINE Pay payment screen and enters the password.
- LINE Pay stores the payment method information and sets the payment status to ‘authorized’.
- The LINE Pay user checks the payment information screen.
- When the transaction becomes payable on the Awaiting Payment screen, the user is redirected to the "confirmUrl" received from the Merchant when the payment is reserved.
- The Merchant calls the Confirm Payment API to complete the payment.
- For Mobile
Figure 6 Payment screen for mobile – Payment completion
- The LINE Pay user selects a payment method on the LINE Pay payment screen and enters the password.
- LINE Pay stores the payment method information and sets the payment status to ‘authorized’.
- After checking the payment information screen on the LINE app, the LINE Pay user clicks ‘OK’ on the bottom to move to the "confirmUrl" received when the payment is reserved.
- The Merchant calls the Confirm Payment API to complete the payment.
When the authorization of payment is separated from the capture of the authorized payment
The overall process is similar to those above, but the Merchant should set "capture" as "false" when calling the
Reserve Payment API.
When the Merchant calls the Confirm Payment API, the payment status is saved as AUTHORIZATION
When capturing the payment,
- To capture the payment: Call the Capture API to complete the payment.
- Not to capture the payment: Call the Void Authorization API to cancel the authorization of payment.
When Calling confirmUrl from Server to Server
The payment can be made by only the communication between the Merchant server and the LINE Pay server, with delivering confirmUrl.
Figure 7 Calling ConfirmUrl from server to server
- When reserving the payment, the Merchant should pass confirmUrlType : "SERVER".
- The LINE Pay user selects a payment method and enters the password after entering the LINE Pay payment screen.
- The LINE Pay server saves the payment information and calls the confirmUrl received from the Merchant when the payment is reserved. [Appendix] “Please refer to the case of Calling Confirm Url from Server-to-Server”
- The Merchant server calls the Confirm Payment API to complete the payment. Please note that the Merchant server can call the Confirm Payment API only after the response for the ConfirmUrl is successfully sent.
Preapproved Payment
Payment Request - Payment Screen
The overall flow is the same as the normal payment, except that "payType" should be set as "PREAPPROVED."
Payment Screen - Payment Completion and regKey (for preapproved payment) Issuance
A regKey is delivered with the response information of payment confirmation additionally. The Merchant must save this key to use preapproved payment later.
Preapproved Payment
Figure 9 Preapproved Payment
When the payment is confirmed, the Merchant server calls "Preapproved Payment API " by using the regKey to make a payment. The LINE Pay user does not intervene during the payment process, but can be notified when the payment is completed.
regKey (for Preapproved Payment) Expiration
You can call the Expire regKey API so that unnecessary regKeys expire. For more information, refer to “Expire regKey”
How to Use LINE Pay APIs
This chapter details how to implement payments using LINE Pay. Before using LINE Pay APIs, Merchant's verification information can be viewed at Merchant Center2 (http://pay.line.me) after evaluation process is complete.
Common Features
LINE Pay Authentication
Required authentication information for LINE Pay integration is as below.
- channel id
- channel secret key
Above information is sent by Header script and you can find them in each API specification.
Request Header
| Item | Data Type | Required? | Description |
|---|---|---|---|
| Content-Type | String | Y | application/json |
| X-LINE-ChannelId | String(10) | Y | Payment Integration Information - Channel ID |
| X-LINE-ChannelSecret | String(32) | Y | Payment Integration Information - Channel Secret Key |
| X-LINE-MerchantDeviceProfileId | String(32) | N | Offline Support - Device Type |
Infra and Tech Support
If you have questions for infra condition, technical support or facing internal error, please contact us via email (pay_tech@linecorp.com).
| Env. | URL | Description |
|---|---|---|
| Sandbox | https://sandbox-api-pay.line.me | Environment for integration testing You can process the payment by Sandbox’s web simulation payment page instead of LINE Pay app. Please refer to the appendix(Sandbox usage Guide) |
| Real | https://api-pay.line.me | Real Service Environment |
Contact for Tech Support
If you have questions for integration process or internal error, please contact LINE Pay Tech Support team by sending Email. Please see contact information below.
| Department | Contact | Applied Country |
|---|---|---|
| LINE Pay Japan | dl_tech_support_jp@linecorp.com | Japan |
| LINE Pay Thailand | dl_tech_support_th@linecorp.com | Thailand |
| LINE Pay Taiwan | dl_tech_support_tw@linecorp.com | Taiwan |
| LINE Pay Global | dl_tech_support_global@linecorp.com | Other countries |
Get Payment Details API
Gets the details of payments made with LINE Pay. This API only gets the payments that have been captured.
Get Payment Details Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Table 1 Get Payment Details API Request Parameter
| Item | Data Type | Required | Description |
|---|---|---|---|
| transactionId[] | number | N | A transaction ID issued by LINE Pay, for payment or refund. |
| orderId[] | String | N | Merchant Transaction Order ID |
- When the API is called, more than one parameter needs to be passed. You can check details of up to 100 transactions.
Get Payment Details API Response
Table 2 Get Payment Details API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result code
|
| returnMessage | String | Result messages or reason for failure |
| info[].transactionId | number | Transaction number (19 digits) |
| info[].transactionDate | String | Transaction date & time(ISO-8601) |
| info[].transactionType | String | Transaction types
|
| info[].productName | String | Merchant's order number |
| info[].merchantName | String | Merchant Name |
| info[].currency | String | Currency(ISO 4217) |
| info[].authorizationExpireDate | String | Expiration Date of Authorization (ISO-8601) |
| info[].payInfo[].method | String | Payment method used ( Credit card: CREDIT_CARD, Balance: BALANCE, Discount: DISCOUNT ) |
| info[].payInfo[].amount | number | Transaction amount (Amount transacted when the transaction Id was generated) The final transaction amount when retrieving the original transaction is sum(info[].payInfo[].amount) – sum(refundList[].refundAmount) |
| info[].merchantReference.affiliateCodes[] | String | Merchant affiliated Codes when belonged to the affiliated transaction |
| info[].merchantReference.affiliateCodes[].cardType | String | Affiliated card type when belonged to the affiliated transaction and user has an affiliate card. |
| info[].merchantReference.affiliateCodes[].cardId | String | Affiliated card id when belonged to the affiliated transaction and user has an affiliate card. |
| Retrieving original transactions & When there is a refund | ||
| info[].refundList[].refundTransactionId | number | Refunded transaction number (19 digits) |
| info[].refundList[].transactionType | String | Transaction types
|
| info[].refundList[].refundAmount | number | Refund Amount |
| info[].refundList[].refundTransactionDate | String | Refunded transaction date & time (ISO-8601) |
| When retrieving a refund | ||
| info[].originalTransactionId | number | Original payment transaction number (19 digits) |
| info[].events[].code | String(30) | Unique event code which allows only alphanumeric. |
| info[].events[].totalAmount | Number | Amount to be applied to rate promotion. |
| info[].events[].productQuantity | Number | Amount to be applied to fixed promotion. |
Examples of Using Get Payment Details API
Source 1 Get Payment Details API Request
GET https://sandbox-api-pay.line.me/v2/payments?transactionId=2019060112345678910&orderId=20191002045572 HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Source 2 Get Payment Details API Response (When retrieving original transactions)
{
"returnCode":"0000",
"returnMessage":"success",
"info":[{
"transactionId":2019060112345678910,
"transactionDate":"2019-06-01T09:00:00Z",
"transactionType":"PAYMENT",
"payInfo": [
{"method":"BALANCE", "amount":10},
{"method":"DISCOUNT", "amount":10}
],
"productName":"tes production",
"currency":"USD",
"orderId":"20191002045572",
"refundList":[
{
"refundTransactionId":"2019060212345678912",
"transactionType":"PARTIAL_REFUND",
"refundAmount":-1,
"refundTransactionDate":"2019-06-02T09:48:52Z"
},
{
"refundTransactionId":"2019060312345678912",
"transactionType":"PARTIAL_REFUND",
"refundAmount":-1,
"refundTransactionDate ":"2019-06-02T09:49:28Z"
},
{
"refundTransactionId":"2019060412345678912",
"transactionType":"PARTIAL_REFUND",
"refundAmount":-1,
"refundTransactionDate ":"2019-06-02T09:53:18Z"
}
],
"events":[
{
"code": "alphanumeric",
"totalAmount": 500,
"productQuantity": null
},
{
"code": "alphanumeric2",
"totalAmount": null,
"productQuantity": 10
}
]
}]
}
Source 3 Get Payment Details API Response (When retrieving a refund)
{
"returnCode":"0000",
"returnMessage":"success",
"info":[{
"transactionId":2019060112345678912,
"transactionDate":"2019-06-01T09:48:43Z",
"transactionType":"PARTIAL_REFUND",
"amount":-5,
"productName":"",
"currency":"USD",
"orderId":"20190101123123123",
"originalTransactionId":2019060112345678910
}]
}
Source 4 Get Payment Details API Response (When merchant affiliated codes exist)
{
"returnCode":"0000",
"returnMessage":"success",
"info":[{
"transactionId":2019062812345678910,
"transactionDate":"2019-06-28T09:48:43Z",
"transactionType":"PAYMENT",
"payInfo": [
{"method":"BALANCE", "amount":10},
{"method":"DISCOUNT", "amount":10}
],
"productName":"tes production",
"currency":"USD",
"orderId":"20191128123123123",
"merchantReference" : {
"affiliateCodes" :["AFFL_18112001","AFFL_18112002"]
}
}]
}
Source 5 Get Payment Details API Response (When merchant affiliated cards exist)
{
"returnCode": "0000",
"returnMessage": "success",
"info": [{
"transactionId": 2019062812345678910,
"transactionDate": "2019-06-28T09:48:43Z",
"transactionType": "PAYMENT",
"payInfo": [
{"method": "BALANCE","amount": 10},
{"method": "DISCOUNT","amount": 10}
],
"productName": "tes production",
"currency": "USD",
"orderId": "20191128123123123",
"merchantReference": {
"affiliateCards": [
{"cardType": "POINT_CARD","cardId": "4822456212454"},
{"cardType": "LINESHOP_CARD","cardId": "LP822456212454"}
]
}
}]
}
Reserve Payment API
Prior to processing payments with LINE Pay, the Merchant is evaluated if it is a normal Merchant store then the information is reserved for payment. When a payment is successfully reserved, the Merchant gets a "transaction Id" that is a key value used until the payment is completed or refunded.
Reserve Payment Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Table 3 Reserve Payment API Request Parameter
| Item | Date Type | Required? | Description |
|---|---|---|---|
| productName | String(4000) | Y | Product Name(charset: UTF-8) |
| productImageUrl | String(500) | N | Product image URL Image URL to be displayed on the Payment screen
|
| amount | number | Y | Payment amount |
| currency | String(3) | Y | Payment currency(ISO 4217) Supported currencies are as follows.
|
| confirmUrl | String(500) | Y | Merchant's URL that the buyer is redirected to after selecting a payment method and entering the payment password in LINE Pay.
Reference Detailed Explanation and Exceptional Case of ConfirmUrl |
| confirmUrlType | String | N | confirmUrl Type Type of URL that the buyer is redirected to after selecting a payment method and entering the payment password in LINE Pay
|
| checkConfirmUrlBrowser | Boolean | N | When moved to confirmUrl, Check a browser
Refernce Detailed Explanation and Exceptional Case of ConfirmUrl |
| cancelUrl | String(500) | N | Payment Cancellation page URL
|
| packageName | String(4000) | N | Information to avoid phishing during transition between apps in Android. |
| orderId | String(100) | Y | Merchant's order number corresponding to the payment request
|
| deliveryPlacePhone | String(100) | N | Recipient contact (for Risk Management) |
| payType | String(12) | N | Payment types
|
| langCd | String | N | Language codes on the payment waiting screen (paymentUrl). Supports a total of six languages.
|
| capture | Boolean | N | Whether to capture or not
|
| ExtraFields | |||
| extras.addFriends | object[] | N | Add Friends List
|
| extras.branchName | String (2000) | N | Branch Name where the payment is requested from (Only 100 letters will be displayed if it's exceeded.) |
| extras.branchId | String (32) | N | Branch Id where the payment is requested. It can be support alphabets, numbers and special characters. |
| extras.promotionRestriction | object | N | Promotion Restriction info.
"promotionRestriction" : { |
Payment Reserve Response
Table 4 Payment Reserve Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result Code
|
| returnMessage | String | Result messages or reason for failure. Examples are as follows:
|
| info.transactionId | Number | Transaction number(19 digits) |
| info.paymentUrl.web | String | Web URL to go to after payment request
|
| info.paymentUrl.app | String | App URL to the Payment Screen
|
| info.paymentAccessToken | String | Code Value (12 digits) using for input a code instead of using a Scanner on LINE app. (Supports a Scanner of LINE Pay app above LINE 5.1 Version) |
Examples of Using Reserve Payment API
Source 4 Reserve Payment API Request
POST https://sandbox-api-pay.line.me/v2/payments/request HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"productName": "Test Product",
"orderId": "ORD_i0q1kW0yFrOp0fCAvctq7g6Y3",
"confirmUrlType": "CLIENT",
"currency": "JPY",
"amount": 100,
"capture": true,
"payType": "NORMAL",
"cancelUrl": "https://tools-merchant.com/payment/general/confirm?type=cancel",
"confirmUrl": "https://tools-merchant.com/payment/general/confirm?orderId=ORD_i0q1kW0yFrOp0fCAvctq7g6Y3",
"productImageUrl": "https://tools-merchant.com/cony-money-box-1.jpg",
"extras": {
"addFriends": [{
"type": "LINE_AT",
"idList": ["@aaa", "@bbb"]
}],
"branchName": "test_branch_1",
"branchId": "branch1"
}
Source 5 Reserve Payment API Response
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"paymentUrl": {
"web": "https://sandbox-web-pay.line.me/web/payment/wait?transactionReserveId=cFJFbUx5aU5NSGxZUmRnWmtQV1ZPT3pZb0c3Ym9NcGMvM0s3WGdHc2JGeGUyU09mNGRJRi83ZWxzL3l3OVEreg",
"app": "line://pay/payment/cFJFbUx5aU5NSGxZUmRnWmtQV1ZPT3pZb0c3Ym9NcGMvM0s3WGdHc2JGeGUyU09mNGRJRi83ZWxzL3l3OVEreg"
},
"transactionId": "2019061311372683710",
"paymentAccessToken": "113552948987"
}
}
Payment Confirm API
This API is used for a Merchant to complete its payment. The Merchant must call Confirm Payment API to actually complete the payment. However, when "capture" parameter is "false" on payment reservation, the payment status becomes AUTHORIZATION, and the payment is completed only after "Capture API" is called.
Payment confirm Request
- Connection Timeout : 5 seconds
- Read Timeout : 40 seconds
Table 5 Payment confirm API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| amount | number | Y | Payment amount |
| currency | String(3) | Y | Payment currency(ISO 4217) Supported currencies are as follow:
|
Payment ConfirmAPI Response
Table 6 Payment confirm API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result Code
|
| returnMessage | String | Result messages or reason for failure. Examples are as follows:
|
| info.orderId | String | Order number sent from Merchant upon reserving a payment |
| info.transactionId | number | Transaction number (19 digits) received as a result after reserving a payment |
| info.authorizationExpireDate | String | opt-authorization expiration date(ISO 8601)
|
| info.payInfo[].method | String | Payment method used
|
| info.payInfo[].amount | number | Payment amount |
| info.payInfo[].creditCardNickname | String | For opt-Preapproved Payment, Credit card nickname
|
| info.payInfo[].creditCardBrand | String | For opt-Preapproved Payment, Credit card brand
|
| info.regKey | String | opt-Key for preapproved payment (15 digits) |
| info.merchantReference.affiliateCodes[] | String | Merchant affiliated Codes when belonged to the affiliated transaction |
| info.merchantReference.affiliateCards[].cardType | String | Affiliated card type when belonged to the affiliated transaction and user has an affiliate card. |
| info.merchantReference.affiliateCards[].cardId | String | Affiliated card id when belonged to the affiliated transaction and user has an affiliate card. |
Examples of Payment confirm API
Source 6 Payment Confirm API Request
POST https://sandbox-api-pay.line.me/v2/payments/2019061211372655410/confirm HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"amount": 1000,
"currency": "JPY"
}
Source 7 Payment Confirm API Response (Balance payment when the payType is NORMAL)
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"transactionId": 2019061211372655410,
"orderId": "ORD_SMCD1JHbLLvdESnykyJjgGQ3Q",
"payInfo": [{
"method": "BALANCE",
"amount": 889
}, {
"method": "DISCOUNT",
"amount": 111
}]
}
}
Source 8 Payment Confirm API Response (Mixed Payment when the payType is NORMAL)
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"orderId": "ORD_SMCD1JHbLLvdESnykyJjgGQ3Q",
"transactionId": 2019061211372655410,
"payInfo": [{
"method": "BALANCE",
"amount": 10
}, {
"method": "POINT",
"amount": 5
}]
}
}
Source 9 Payment Confirm API Response (When the payType is PREAPPROVED)
{
"returnCode": "0000",
"returnMessage": "Success.",
"info": {
"orderId": "ORD_SMCD1JHbLLvdESnykyJjgGQ3Q",
"transactionId": 2019061211372655410,
"payInfo": [{
"method": "CREDIT_CARD",
"amount": 10,
"creditCardNickname": "test",
"creditCardBrand": "VISA"
}],
"regKey": "RKf930b19XTF1TX"
}
}
Source 10 Payment Confirm API Response (When merchant affiliated codes exist)
{
"returnCode":"0000",
"returnMessage":"Success.",
"info": {
"orderId": "ORD_SMCD1JHbLLvdESnykyJjgGQ3Q",
"transactionId": 2019061211372655410,
"payInfo": [
{
"method": "BALANCE",
"amount": 10
},
{
"method": "POINT",
"amount": 5
}
],
"merchantReference": {
"affiliateCodes" : ["AFFL_18112001","AFFL_18112002"]
}
Source 11 Payment Confirm API Response (When merchant affiliated cards exist)
{
"returnCode":"0000",
"returnMessage":"Success.",
"info": {
"orderId": "ORD_SMCD1JHbLLvdESnykyJjgGQ3Q",
"transactionId": 2019061211372655410,
"payInfo": [
{
"method": "BALANCE",
"amount": 10
},
{
"method": "POINT",
"amount": 5
}
],
"merchantReference": {
"affiliateCards": [
{
"cardType": "POINT_CARD",
"cardId": "4822456212454"
},
{
"cardType": "LINESHOP_CARD",
"cardId": "LP822456212454"
}
]
}
}
}
Refund Payment API
Requests refund of payments made with LINE Pay. To refund a payment, the LINE Pay user's payment transaction Id must be forwarded. A partial refund is also possible depending on the refund amount.
Refund Payment Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Table 7 Refund Payment API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| refundAmount | number | N | Refund amount
|
| Extra fields | |||
| extras.promotionRestriction | object | N | Promotion Restriction info.
"promotionRestriction" : { |
Refund Payment Response
Table 8 Refund Payment API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result Code
|
| returnMessage | String | Result messages or reason for failure |
| info.refundTransactionId | number | Refunded transaction number (newly issued number - 19 digits) |
| info.refundTransactionDate | String | Refunded transaction date & time (ISO 8601) |
Examples of Using Refund Payment API
Source 10 Refund Payment API Request
POST https://sandbox-api-pay.line.me/v2/payments/2019060112345678910/refund HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"refundAmount": 500,
"extras" : {
"promotionRestriction" : {
"useLimit" : 20,
"rewardLimit" : 20
}
}
}
Source 11 Refund Payment API Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"refundTransactionId": 2019060112345678911,
"refundTransactionDate": "2019-06-06T09:00:00Z"
}
}
Get Authorization Details API
Gets the details authorized with LINE Pay. This API only gets data that is authorized or whose authorization is voided; the one that is already captured can be viewed by using "Get Payment Details API”.
Get Authorization Details Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Table 9 Get Authorization Details API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| transactionId[] | number | N | Transaction number issued by LINE Pay |
| orderId[] | String | N | Order number of Merchant |
- When this API is called, more than one parameter needs to be passed. You can check details of up to 100 transactions.
Get Authorization Details Response
Table 10 Get Authorization Details API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Results code
|
| returnMessage | String | Result messages or reason for failure |
| info[].transactionId | number | Transaction number (19 digits) |
| info[].transactionDate | String | Transaction date(ISO 8601) |
| info[].transactionType | String | Transaction type
|
| info[].payStatus | String | Payment status
|
| info[].payInfo[].method | String | Payment method
|
| info[].payInfo[].amount | number | Transaction amount (when a transaction Id is created) The final transaction amount is sum(info[].payInfo[].amount) – sum(refundList[].refundAmount) |
| info[].productName | String | Product name |
| info[].currency | String | Currency(ISO 4217) |
| info[].orderId | String | Order number of Merchant |
| info[].authorizationExpireDate | String | Authorization expiration date and time(ISO 8601) |
| info[].events[].code | String(30) | Unique event code which allows only alphanumeric. |
| info[].events[].totalAmount | Number | Amount to be applied to rate promotion. |
| info[].events[].productQuantity | Number | Amount to be applied to fixed promotion. |
Examples of Using Get Authorization Details API
Source 12 Get Authorization Details API Request
GET https://sandbox-apipay.line.me/v2/payments/authorizations?transactionId=2019060112345678910 HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Get Authorization Details API Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": [{
"transactionId": 2019060112345678910,
"transactionDate": "2019-06-01T09:00:00Z",
"transactionType": "PAYMENT",
"payInfo": [{
"method": "BALANCE",
"amount": 10
}, {
"method": "DISCOUNT",
"amount": 10
}],
"productName": "tes production",
"currency": "USD",
"orderId": "20190601ORD45678910",
"payStatus": "AUTHORIZATION",
"authorizationExpireDate": "2019-06-30T09:00:00Z"
}]
}
Capture API
If "capture" is "false" when the Merchant calls the “Reserve Payment API” , the payment is completed only after the Capture API is called.
Capture Request
- Connection Timeout : 5 seconds
- Read Timeout : 60 seconds
Table 11 Captire API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| amount | number | Y | Payment amount |
| currency | String(3) | Y | Payment currency (ISO 4217) The following currencies are supported.
|
| Extra fields | |||
| extras.promotionRestriction | object | N | Promotion Restriction info.
"promotionRestriction" : { |
Capture Response
Table 12 Capture API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result code
|
| returnMessage | String | Result messages or reason for failure. Examples are as follows:
|
| info.orderId | String | Order number passed from the Merchant when a payment reservation is made. |
| info.transactionId | number | Transaction number (19 digits) |
| info[].payInfo[].method | String | Payment method
|
| info.payInfo[].amount | number | Payment amount |
Examples of Using Capture API
Source 14 Capture API Request
POST https://sandbox-api-pay.line.me/v2/payments/authorizations/2019060112345678910/capture HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"amount": 1000,
"currency": "JPY",
"extras" : {
"promotionRestriction" : {
"useLimit": 20,
"rewardLimit": 20
}
}
}
Source 15 Capture API Response
{
"returnCode": "0000",
"returnMessage": "OK",
"info": {
"transactionId": 20140101123123123,
"orderId": "order_210124213",
"payInfo": [{
"method": "BALANCE",
"amount": 10
}, {
"method": "DISCOUNT",
"amount": 10
}]
}
}
Void Authorization API
Voids a previously authorized payment. A payment that has been already captured can be refunded by using the “Refund Payment API”.
Void Authorization Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Void Authorization Response
Table 13 Void Authorization API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result code
|
| returnMessage | String | Result messages or reason for failure. Examples are as follows:
|
Examples of Using Void Authorization API
Source 16 Void Authorization API Request
POST https://sandbox-api-pay.line.me/v2/payments/authorizations/2019060112345678910/void HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Source 17 Void Authorization API Response
{
"returnCode": "0000",
"returnMessage": "Success"
}
Preapproved Payment API
When the payment type of the Reserve Payment API was set as PREAPPROVED, a regKey is returned with the payment result. Preapproved Payment API uses this regKey to directly complete a payment without using the LINE app.
Preapproved Payment Request
- Connection Timeout : 5 seconds
- Read Timeout : 40 seconds
Table 14 Preapproved Payment API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| productName | String(4000) | Y | Product name |
| amount | number | Y | Payment amount |
| currency | String(3) | Y | Payment currency (ISO 4217) Supported currencies are as follows:
|
| orderId | String(100) | Y | Merchant's order number corresponding to the payment request. A unique number managed by a Merchant. |
| capture | Boolean | N | Whether to be captured or not
|
Preapproved Payment Response
Table 15 Preapproved Payment API Response Body
| Data | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result code
|
| returnMessage | String | Result messages or reason for failure |
| info.transactionId | number | Transaction number (19 digits) |
| info.transactionDate | String | Transaction date and time(ISO 8601) |
| info.authorizationExpireDate | String | Expiration Date of Authorization(ISO 8601)
|
Examples of Using Preapproved Payment API
Source 18 Preapproved Payment API Request
POST https://sandbox-api-pay.line.me/v2/payments/preapprovedPay/RK123asd213/payment HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"productName": "Naver Music Monthly Pass",
"amount": 10000,
"currency": "JPY",
"orderId": "testOrd2019121200000001"
}
Source 19 Preapproved Payment API Response
{
"returnCode": "0000",
"returnMessage": "OK",
"info": {
"transactionId": 2019060112345678910,
"transactionDate": "2019-01-01T09:00:00Z"
}
}
Check regKey Status API
Checks if regKey is available before using the preapproved payment API.
Check regKey Status Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 second
Table 16 Check regkey Status API Request Parameter
| Item | Data Type | Required? | Description |
|---|---|---|---|
| creditCardAuth | Boolean | N | Check Authorization for Credit Card minimum amount saved in regKey
|
Check regKey Status Response
Table 17 Check regKey Status API Response Body
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result Code
|
| returnMessage | String | Result messages or reason for failure |
Examples of Using Check regKey Status API
Source 20 Check regKey Status API Request
GET https://sandbox-api-pay.line.me/v2/payments/preapprovedPay/RK7862119XTF1TT/check
HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
Source 21 Check regKey Status API Response
{
"returnCode": "0000",
"returnMessage": "Success"
}
Expire regKey API
Expires the regKey information registered for preapproved payment. Once the API is called, the regKey is no longer used for preapproved payments.
Expire regKey Request
- Connection Timeout : 5 seconds
- Read Timeout : 20 seconds
Expire regKey Response
Table 18 Expire regKey API Response
| Item | Data Type | Description |
|---|---|---|
| returnCode | String(4) | Result code
|
| returnMessage | String | Result messages or reason for failure |
Examples of Expire regKey API
Source 22 Expire regKey API Request
POST https://sandbox-api-pay.line.me/v2/payments/preapprovedPay/RK123asd213/expire HTTP/1.1
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
Source 23 Expire regKey API Response
{
"returnCode": "0000",
"returnMessage": "Success."
}
Appendix
LINE Pay Error Codes
This section defines error codes of LINE Pay. returnMessage for an error code is provided in English, and if there is no message, hyphen (-) is shown.
Table 19 LINE Pay Error Codes
| Code | Description |
|---|---|
| 1101 | This user is not a LINE Pay user. |
| 1102 | The purchasing user suspended for transaction. |
| 1104 | Merchant not found. |
| 1105 | This Merchant cannot use LINE Pay. |
| 1106 | Header information error |
| 1110 | Not available credit card. |
| 1124 | Error in Amount (scale). |
| 1141 | Account status error. |
| 1142 | Insufficient balance remains. |
| 1145 | Payment in progress. |
| 1150 | Transaction record not found. |
| 1152 | Transaction has already been made. |
| 1153 | Request amount is different from real amount. |
| 1154 | Preapproved payment account not available. |
| 1155 | The transaction Id not eligible for Refund. |
| 1159 | Omitted request payment information. |
| 1163 | Exceeded the expiration for Refund. |
| 1164 | Refund limit exceeded. |
| 1165 | The transaction has already been refunded. |
| 1169 | Payment method and password must be certificated by LINE Pay. |
| 1170 | User’s account remains have been changed. |
| 1172 | Existing same orderId. |
| 1177 | Exceeded max. number of transactions (100) allowed to be retrieved. |
| 1178 | Unsupported currency. |
| 1179 | Status can not be processed. |
| 1180 | Expired the payment date. |
| 1183 | Payment amount must be greater than 0. |
| 1184 | Payment amount exceeds amount requested. |
| 1190 | The regKey does not exist. |
| 1193 | The regKey expired. |
| 1194 | This Merchant cannot use Preapproved Payment. |
| 1197 | Already processing payment with regKey. |
| 1198 | Duplicated the request calling API. |
| 1199 | Internal request error. |
| 1280 | Temporary error while making a payment with Credit Card. |
| 1281 | Credit Card Payment Error |
| 1282 | Credit Card Authorization Error |
| 1283 | The payment has been declined due to suspected fraud. |
| 1284 | Payment amount must be greater than 0. |
| 1285 | Omitted credit card information |
| 1286 | Incorrect credit card payment information |
| 1287 | Credit card expiration date has passed. |
| 1288 | Credit card has insufficient funds. |
| 1289 | Maximum credit card limit exceeded. |
| 1290 | One-time payment limit exceeded. |
| 1291 | This card has been reported stolen. |
| 1292 | This card has been suspended. |
| 1293 | Invalid Card Verification Number (CVN) |
| 1294 | This card is blacklisted. |
| 1295 | Invalid credit card number. |
| 1296 | Invalid amount |
| 1298 | The credit card payment declined. |
| 2101 | Parameter error |
| 2102 | JSON data format error |
| 9000 | Internal error |
If an internal error, 1199, 9000 occurs, contact Technical Support at: (pay_tech@linecorp.com).
Table 20 Error code by API
| ErrorCode | reserve | confirm | Capture | Void | Refund | AuthorizationDetails | PaymentDetails | PreapprovedPayment | Check regKey | Expired regKey |
|---|---|---|---|---|---|---|---|---|---|---|
| 1101 | v | v | v | v | v | |||||
| 1102 | v | v | v | v | v | |||||
| 1104 | v | v | v | v | v | v | v | v | v | v |
| 1105 | v | v | v | v | v | v | v | v | v | v |
| 1106 | v | v | v | v | v | v | v | v | v | v |
| 1110 | v | v | ||||||||
| 1124 | v | v | v | v | ||||||
| 1141 | v | v | ||||||||
| 1142 | v | |||||||||
| 1145 | v | |||||||||
| 1150 | v | v | v | v | v | |||||
| 1152 | v | |||||||||
| 1153 | v | |||||||||
| 1154 | v | v | ||||||||
| 1155 | v | v | v | |||||||
| 1159 | v | |||||||||
| 1163 | v | |||||||||
| 1164 | v | |||||||||
| 1165 | v | |||||||||
| 1169 | v | |||||||||
| 1170 | v | v | v | |||||||
| 1172 | v | v | v | v | ||||||
| 1177 | v | v | ||||||||
| 1178 | v | |||||||||
| 1179 | v | v | v | |||||||
| 1180 | v | |||||||||
| 1183 | v | v | v | |||||||
| 1184 | v | |||||||||
| 1190 | v | v | v | |||||||
| 1193 | v | v | ||||||||
| 1194 | v | |||||||||
| 1198 | v | v | v | v | v | |||||
| 1199 | v | v | v | v | v | |||||
| 2101 | v | v | v | v | v | v | v | v | v | v |
| 2102 | v | v | v | v | v | v | v | v | v | v |
| 9000 | v | v | v | v | v | v | v | v | v | v |
Since the error codes from 1280 to 1298 are occurred from Credit Card company, they not necessarily mentioned in this document.
How to Use PaymentUrl App
This section provides instructions for redirecting to LINE App after the Merchant's app requests a payment.
For Android Applications
Use the following example code to check if the LINE app is installed and the available version of LINE Pay. If the LINE app is installed and the available version of LINE Pay is checked, the user is redirected to the LINE Pay payment screen.
Android Application example
int linePaySupportedVersion = 230;
String paymentUrl = "..."; // This is "paymentUrl.app" URL String.
Context context = getActivity();
try {
PackageManager pm = context.getPackageManager();
PackageInfo packageInfo = pm.getPackageInfo("jp.naver.line.android", 0);
int versionCode = packageInfo.versionCode;
if (linePaySupportedVersion <= versionCode) {
launchUri(paymentUrl);
} else {
confirmLineInstall(context);
}
} catch (NameNotFoundException e) {
confirmLineInstall(context);
}
private void confirmLineInstall(Context context) {
new AlertDialog.Builder(context)
.setTitle("LINE Pay")
.setMessage(getString(R.String.linepay_confirm))
.setCancelable(false)
.setPositiveButton(getString(R.String.linepay_install), new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
launchUri("market://details?id=jp.naver.line.android");
}
})
.setNegativeButton(getString(R.String.linepay_cancel), new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
}
})
.show();
}
private void launchUri(String uriString) {
Uri uri = Uri.parse(uriString);
Intent intent = new Intent(Intent.ACTION_VIEW, uri);
startActivity(intent);
}
File : res/values/Strings.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
...
<String name="linepay_confirm">Supported by Android/iPhone LINE versions 4.8.0 or higher.</String>
<String name="linepay_install">Get it now</String>
<String name="linepay_cancel">cancel</String>
...
</resources>
For iOS Applications
Use the following example code to check if the LINE app is installed. If the LINE app is installed, the user is redirected to the LINE Pay payment screen.
iPhone Application example
NSString* lineScheme = @"line://";
BOOL installed = [[UIApplication sharedApplication]
canOpenURL:[NSURL URLWithString:lineScheme]];
if (installed) {
UIAlertView *alert =
[[UIAlertView alloc] initWithTitle:@"LINE Pay" message:NSLocalizedString(@"linepay.confirm", nil)
delegate:self cancelButtonTitle:NSLocalizedString(@"linepay.ok", nil) otherButtonTitles:nil];
alert.tag = 1;
[alert show];
} else {
UIAlertView *alert =
[[UIAlertView alloc] initWithTitle:@"LINE Pay" message:NSLocalizedString(@"linepay.confirm", nil)
delegate:self cancelButtonTitle:NSLocalizedString(@"linepay.cancel", nil)
otherButtonTitles:NSLocalizedString(@"linepay.install", nil), nil];
alert.tag = 2;
[alert show];
}
- (void)alertView:(UIAlertView*)alertView clickedButtonAtIndex:(NSInteger)buttonIndex {
if (alertView.tag == 1 && buttonIndex == 0) {
NSString *paymentUrl = ...; // This is "paymentUrl.app" URL String.
[self launchUrl:paymentUrl];
} else if (alertView.tag == 2 && buttonIndex == 1) {
[self launchUrl:@"itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=443904275&mt=8"];
}
}
- (void)launchUrl:(NSString*)urlString {
NSURL *url = [NSURL URLWithString:urlString];
[[UIApplication sharedApplication] openURL:url];
}
File : en.lproj/Localized.Strings
"linepay.confirm" = "Supported by Android/iPhone LINE versions 4.8.0 or higher.";
"linepay.ok" = "OK";
"linepay.cancel" = "Cancel";
"linepay.install" = "Get it now";
Detailed Explanation and Exceptional Case of ConfirmUrl
Detailed Explanation of ConfirmUrl
Once user completes Payment Authorization process (Select a Payment method and confirm a Payment Password) in LINE Pay app, User is redirected to callback Url.The Url does not represent a Payment Process completion. It is the Url for Merchant page allowing to Call confirm API given by LINE Pay and it will be completed a Final Payment Process.
Exceptional Case of ConfirmUrl
When calling confirmUrl after user gets Payment Authorization from LINE Pay, the Browser requested payment and the Browser receiving ConfirmUrl may not be the same browser depending on the user’s type of Operating System (OS).
When “checkConfirmUrlBrowser” for Payment reserve API is “true”,
LINE Pay checks out and determines the Browsers whether or not the browser starting Payment process is the same as the browser redirecting automatically according to the result of the following criteria,
- For the Same Browser : Move user to ConfirmUrl
- For Different Browser : Move user to Browser requested Payment
When “checkConfirmUrlBrowser” for Payment reserve API is “false (basic value)”,
When the processing already occurred based upon session data(e.g. Log in session) is saved in the browser history of merchant User’s payment process can not be continued while calling ConfirmUrl. Therefore, to link to LINE Pay Payment ,Merchant should select the method below and implement it.
- ConfirmUrl,which already called,does not authorize based upon session data. It is completed a Payment Process based upon Information in confirmUrl
- Examples of Performing session data Process
- Confirmed session data, Display Browser for Payment Result of Existing Merchant.
- When Session data is unidentified, Merchant selects one of the 2 methods below and implements it.
- Display Browser for Payment Result After session data is re-produced (e.g. Log in).
- User is redirected to the Browser requested payment.
When Calling confirmUrl from Server to Server
This section describes specification and examples of confirmUrl called from the LINE Pay server to Merchant server.
When a merchant manages ACL(Access Control List)
A merchant should be registered/managed an IP from LINE Pay server. The following IP information is for each environment.
- Sandbox :147.92.159.209, 147.92.159.21, 147.92.159.68
- Real : 211.249.40.1~211.249.40.30, 147.92.220.5~147.92.220.8
ConfirmUrl Specification
Table 21 confirmUrl Endpoint Specification
| Item | Description |
|---|---|
| Protocol | HTTP |
| Method | GET |
| Request timeout | Connection: 5 seconds Read: 20 seconds |
Table 22 confirmURL Parameters
| Parameter | Description |
|---|---|
| orderId | Order number passed from the Merchant when a payment reservation is made. |
| transactionId | Transaction number returned as results when a payment reservation is made. |
Merchants do not respond to the confirmUrl call, so LINE Pay determines whether it is successful or not by checking HTTP request Code. If the status code is not "200 OK," inform the LINE Pay user that the payment is not successfully completed.
Examples of Using confirmUrl
Examples of using confirmUrl are as follows, where the confirmUrl provided by the Merchant is 'https://testmall.com/pay/result’.
Request(LINE Pay -> Merchant)
http://testmall.com/pay/result?orderId=2014xxx1232132&trasactionId=201408011234567890
Response
// When successful
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Accept-Charset: utf-8
Content-Type: text/html
Content-Length: 2
Date: Sat, 11 Oct 2014 02:45:48 GMT
// When failed
HTTP/1.1 404 NOT_FOUND
Server:Apache-Coyote/1.1
Accept-Charset:utf-8
Content-Type:text/html
Content-Length:4
Date:Sat, 11 Oct 2014 02:45:48 GMT
Using Sandbox Methods
For testing in the Sandbox of LINE Pay, the section, ‘API Endpoint Specification’,in this Integration Guide is stated that merchant should attempt to make a payment using sandbox only and merchant should create page for making a payment. For attempting to make a payment in Sandbox environment, the payment process should be followed as shown below.
※ Requirement
Log-into sandbox is required from all of the channels such PC and mobile.
(To link to Real on the smart phone, User MID received from LINE will be used. This case does not require the channel log-in.)
Sandbox PC Payment
Figure 10 Sample Screen of Sandbox PC Payment Process
Sandbox Mobile Payment
Figure 11 Example Browser of Sandbox Mobile Payment Process