Skip to main content

Implement pre-approved payment

Pre-approved payment is a feature that allows the merchant server to call the Pre-approved Payment API whenever necessary to process payments once payment confirmation is complete, without requiring any additional authentication or payment confirmation processes.

The workflow for pre-approved payment is as follows.

Based on the structure above, you can implement pre-approved payment separately as follows.

Issue pre-approved payment key​

To use pre-approved payment, you must first generate a pre-approved payment key. To do this, call the payment request API with the value of the payment type field (options.payment.payType) set to "PREAPPROVED". The following is an example of requesting pre-approved payment.

For information on obtaining the credentials needed to call the Online API, see Prepare API credentials. The code example described on this page uses the requestOnlineAPI() function defined in the Prepare API credentials code example.

try {
  let response = await requestOnlineAPI({
    method: "POST",
    baseUrl: targetAPIServer,
    apiPath: "/v3/payments/request",
    data: {
      amount: 1000,
      currency: "TWD",
      // ...
      options: {
        payment: {
          payType: "PREAPPROVED",
        },
      },
    },
  });

  console.log("Response: ", response);
} catch (error) {
  console.log(error);
}

If you request payment as above and then confirm payment, the LINE Pay server returns a response containing a pre-approved payment key (info.regKey) as shown below.

{
  "returnCode": "0000",
  "returnMessage": "OK",
  "info": {
    "payInfo": [
      {
        "method": "BALANCE",
        "amount": 100
      }
    ],
    "regKey": "RK2AE3519XTFXHM",
    "transactionId": 2023050301300251010,
    "orderId": "ORD_dfrlW5t0g8vDyf5lgsuvJTFTH"
  }
}

The following is a code to obtain the pre-approved payment key.

try {
  let confirmationResponse = await requestOnlineAPI({
    method: "POST",
    baseUrl: targetAPIServer,
    apiPath: `/v3/payments/${requestTransactionId}/confirm`,
    data: {
      amount: 1000,
      currency: "TWD",
    },
  });

  console.log("Confirmation response: ", confirmationResponse);

  // Pre-approved payment key
  let regKey = confirmationResponse.info.regKey;

  // Do something
} catch (error) {
  console.log(error);
}

Request pre-approved payment​

Before processing the pre-approved payment request, you can check the validity of the pre-approved payment key. If you check pre-approved payment key status before requesting pre-approved payment and the result code (resultCode) of the response is 0000, you can use the pre-approved payment key. The following is an example of checking the pre-approved payment key before requesting the pre-approved payment.

try {
  let regKeyStatusCheckResponse = await requestOnlineAPI({
    method: "GET",
    baseUrl: targetAPIServer,
    apiPath: `/v3/payments/preapprovedPay/${regKey}/check`,
  });

  console.log("Confirmation response: ", confirmationResponse);

  switch (regKeyStatusCheckResponse.resultCode) {
    case 0000:
      console.log("Valid key");
      // Pre-approved payment request processing
      break;

    // ...

    default:
      console.log("Invalid key or error occurred");
      // Do something
  }
} catch (error) {
  console.log(error);
}

When checking the pre-approved payment key status, you can also decide whether to authenticate the status by performing a minimum amount payment. To perform a minimum amount payment, set the query parameter creditCardAuth to true when calling API as follows.

https://sandbox-api-pay.line.me/v3/payments/preapprovedPay/${regKey}/check?creditCardAuth=true

To use this feature, contact a representative of LINE Pay. TW only

Call the pre-approved payment request API with the obtained pre-approved payment key. The following is an example of requesting a pre-approved payment.

try {
  let preapprovedPaymentResponse = await requestOnlineAPI({
    method: "POST",
    baseUrl: targetAPIServer,
    apiPath: `/v3/payments/preapprovedPay/${regKey}/payment`,
    data: {
      productName: "OTT Premium",
      amount: 999,
      currency: "TWD",
      orderId: "EXAMPLE_PREAPPROVED_ORDER_20230422_1000003",
    },
  });

  console.log("Pre-approved payment response: ", preapprovedPaymentResponse);
} catch (error) {
  console.log(error);
}

Unlike the basic payment method, pre-approved payment request omits LINE Pay authentication and payment confirmation, and you will receive the following response.

{
  "returnCode": "0000",
  "returnMessage": "OK",
  "info": {
    "transactionId": 2018123112345678910,
    "transactionDate": "2018-12-31T09:00:31Z"
  }
}

If the result code 1141 or code from 1282 through 1287 is returned in the response after requesting the pre-approved payment, the pre-approved payment key used in the request is discarded. In such cases, you must have a new pre-approved payment key issued to use the pre-approved payment again.

You can separate capture for pre-approved payment as well. To separate capture, set the value of the field (capture) that sets whether to capture automatically at a pre-approved payment request to false.

try {
  let preapprovedPaymentResponse = await requestOnlineAPI({
    method: "POST",
    baseUrl: targetAPIServer,
    apiPath: `/v3/payments/preapprovedPay/${regKey}/payment`,
    data: {
      // ...
      capture: false,
    },
  });

  console.log("Pre-approved payment response: ", preapprovedPaymentResponse);
} catch (error) {
  console.log(error);
}

If you have requested pre-approved payment with separated capture, the response includes information about when the confirmation expires (info.authorizationExpireDate) as follows. For payment settlement, you must separately request a capture using the payment transaction ID (info.transactionId) before the confirmation expires.

{
  "returnCode": "0000",
  "returnMessage": "OK",
  "info": {
    "transactionId": 2018123112345678910,
    "transactionDate": "2018-12-31T09:00:31Z",
    "authorizationExpireDate": "2019-01-31T09:00:31Z"
  }
}

Depending on the service implementation language, you may need to process the transaction ID as a string when handling transaction ID information. For more information, see the Transaction ID.

Discard pre-approved payment key​

If a customer doesn't use pre-approved payment or if you can no longer provide products or services with pre-approved payment, you need to discard the issued pre-approved payment key. You can discard the pre-approved payment key as follows.

try {
  let discardRegKeyResponse = await requestOnlineAPI({
    method: "POST",
    baseUrl: targetAPIServer,
    apiPath: `/v3/payments/preapprovedPay/${regKey}/expire`,
  });

  console.log("Discarding key response: ", discardRegKeyResponse);
} catch (error) {
  console.log(error);
}