跳轉至主體

執行預先授權付款

預先授權付款指顧客完成一次付款授權，後續則無需LINE Pay認證或付款授權流程，合作商店伺服器可呼叫預先授權付款API完成付款的功能。

預先授權付款的操作流程如下。

根據上述結構，可以執行預先授權付款如下。

簽發預先授權付款密鑰​

欲進行預先授權付款，需要先生成預先授權付款密鑰。為生成預先授權付款密鑰，請呼叫付款請求API，並將付款類型欄位(options.payment.payType)的值設為"PREAPPROVED"。以下是請求預先授權付款的範例。

呼叫Online API時，取得必要credentials的方法請參考準備API credentials。本頁所述的程式碼範例使用準備API credentials程式碼範例中定義的requestOnlineAPI()函數。

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

依照上述方式請求付款，接著進行付款授權，LINE Pay伺服器將如下回傳包含預先授權付款密鑰(info.regKey)的回應。

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

以下是取得預先授權付款密鑰的程式碼。

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

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

  // 預先授權付款密鑰
  let regKey = confirmationResponse.info.regKey;

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

請求預先授權付款​

處理預先授權付款請求之前，有一種方法可以檢查簽發的預先授權付款密鑰是否有效。請求預先授權付款前，檢查預先授權付款密鑰狀態，如果回應的結果程式碼(resultCode)為0000，則可以使用預先授權付款密鑰。以下是在請求預先授權付款之前提前檢查預先授權付款密鑰狀態的範例。

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");
      // 處理預先授權付款請求
      break;

    // ...

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

檢查預先授權付款密鑰狀態時，還可以決定是否要透過最低付款來驗證狀態。若要執行最低金額付款，請在呼叫API時將creditCardAuth查詢參數設為true，如下所示。

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

欲使用此功能，請聯絡LINE Pay負責人。TW only

使用預先授權付款密鑰呼叫預先授權付款請求API。以下是請求預先授權付款的範例。

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

與基本付款方式不同，預先授權付款請求會跳過LINE Pay認證和付款授權，將收到以下回應。

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

如果請求預先授權付款後，回應中傳回1141或1282到1287之間的結果碼，則該請求中使用的預先授權付款密鑰將被銷毀。在這種情況下要再次執行預先授權付款，必須取得預先授權付款的新密鑰。

預先授權付款也可以進行分開請款。如要分開請款，請在請求預先授權付款時，將設定是否自動請款的欄位(capture)值設為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);
}

如要分開請款請求預先授權付款，則授權截止時間訊息(info.authorizationExpireDate)也將納入回應，如下所示。若要完成結算，必須在授權到期之前使用付款交易ID (transaction ID)(info.transactionId)來單獨請求請款。

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

處理交易ID訊息時，根據服務執行語言，可能需要將交易ID視為字串。詳細說明請參考交易ID (transaction ID)。

銷毀預先授權付款密鑰​

如果顧客不使用預先授權付款或無法再透過預先授權付款提供產品或服務，則必須銷毀已頒發的預先授權付款密鑰。可以按照以下方式銷毀預先授權付款密鑰。

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