Installation

Step 1: Install the package

Download the @latpay/latpay-react-component package from NPM:

Command to install the package:

npm i @latpay/latpay-react-component

Step 2: Import the component

import Latpaycomponent from "@latpay/latpay-react-component";

Authentication

To authenticate the merchant account and bind the Checkout elements to your payment page, call the window.LatpayCheckout.open() function. The following sample can be used as a template. The function provides an option to handle authentication failure for e.g. To alert website admins or write to log etc.

window.LatpayCheckout.open({
  merchantuserid: formData.Merchant_User_Id, // issued by latpay
  publickey: formData.PublicKey, //issued by latpay
  currency: formData.Currency, // transaction currency
  amount: formData.Amount, //transaction amount
  reference: formData.Reference, // transaction reference
  description: formData.Description, // transaction description (optional)
  status: (status) => {
    // Handle the status response
    // "success" means authentication was successful and the card form loaded.
    // Possible error values:
    // - errorcode_1001: Authentication failed (check credentials)
    // - errorcode_9001: Parameter validation failed
  },
});

Once Checkout elements to be binded, it is necessary to create an empty DOM container (div tag) with the unique id latpay-element. This should be placed in location where you would like to have the card elements to be displayed.

<div id="latpay-element"></div>

Separate Card Element Initialization

If you specifically want to handle the card section separately, replace the LatpayCheckout.open call with LatpayCheckout.open_card when initializing the card input fields. Here’s how to do it:

latpayCheckout.open_card({
  merchantuserid: formData.Merchant_User_Id, // issued by latpay
  publickey: formData.PublicKey, //issued by latpay
  currency: formData.Currency, // transaction currency
  amount: formData.Amount, //transaction amount
  reference: formData.Reference, // transaction reference
  description: formData.Description, // transaction description (optional)
  status: (status) => {
    // Handle status
    //"success" indicates function executed correctly and card form loaded.
    //If not "success", then handle the status result and send callback to backend to raise alert for investigation.
    //Possible error values:
    //errorcode_1001 -- Authentication failed (check account credentials)
    //errorcode_9001 -- Parameter field validation failed (Check parameter data)
  },
});

Process Transaction

Once authentication is successful, the Latpay Card Element would be embedded in the merchant page. If the customer selects the Wallet option (either Gpay or ApplePay), then the transaction flow will complete based on the wallet popup and customer completing the necessary authentication. Card Payment: When the customer selects the card option and fills in the card detail, on clicking the Submit button on merchant side, should trigger the secure3dPayment() function, the function call specification as shown below.

window.LatpayCheckout.secure3DPayment({
  amount: formData.Amount,
  currency: formData.Currency,
  reference: formData.Reference,
  description: formData.Description,
  firstname: formData.Firstname,
  lastname: formData.Lastname,
  email: formData.Email,
  datakey: formData.DataKey,
  transkey: formData.TransKey,
  is3dcheck: "N",
});

Note: secure3DPayment transkey combination - which is a SHA-256 hash of the following parameters:

• currency – type of currency used for transaction.
• amount – total value of amount.
• reference - unique transaction
• _3dcheck - “Y” || “N”.
• datakey – will be issued by latpay.

Callback: onPaymentAction(response)

To ensure customer do not initiate any other actions whilst a transaction is ongoing, and also to provide processing updates to customer, Latpay payment script offers callback hook onPaymentAction(response), which merchant can implement to show progress (for e.g. loader animations). This callback will be triggered when customer clicks “submit” button for a card checkout, or if they click “GooglePay” or “ApplePay” wallet buttons.

Wallet (GooglePay or ApplePay)

The response will be a JSON structure-indicating what the action initiated by the customer. The following fields will be received from the callback.

{
  "type": "googlepay",
  "status": {
    "responsetype": "1",
    "statuscode": "0",
    "statusdesc": "Googlepay payment processing...",
    "errorcode": "",
    "errordesc": ""
  }
}

Card

In the case of card checkout, depending on the data validation of form fields, either a success response or a failed response will be sent in the callback. Merchants can implement this callback and if failed response received, allow customer to edit the data and resubmit. If success response received, then merchant can show a loader progress to ensure customer is aware of payment process initiation.

Card Success:

{
  "type": "card",
  "status": {
    "responsetype": "1",
    "statuscode": "0",
    "statusdesc": "Card payment processing...",
    "errorcode": "",
    "errordesc": ""
  }
}

Card Failed:

{
  "type": "card",
  "status": {
    "responsetype": "1",
    "statuscode": "1",
    "statusdesc": "Card payment validation failed",
    "errorcode": "",
    "errordesc": "Please enter cardholdername | Please enter cardnumber | Please enter a valid expiry month and year | CVC is required."
  }
}

As a best practice, after receiving a success response from this callback, all buttons—including custom button, Google Pay, and Apple Pay buttons—should remain visible but be disabled to prevent unintended interactions.

onPaymentAction = (data) => {
  // merchant can implement to show progress (for e.g. loader animations)
  //All buttons are disabled to prevent any unintended user interactions.

  const gpayButton = document.querySelector("#latpay-gp-element button"); //googlepay button
  if (gpayButton) {
    gpayButton.disabled = true;
    gpayButton.style.pointerEvents = "none"; // Prevent clicks
    gpayButton.style.opacity = "0.6"; // Optional: visually indicate disabled
    gpayButton.style.cursor = "not-allowed";
  }
  const apayButton = document.querySelector("#latpay-applepayButtonId"); //applepay button
  if (apayButton) {
    apayButton.disabled = true;
    apayButton.style.pointerEvents = "none"; // Prevent clicks
    apayButton.style.cursor = "not-allowed";
    apayButton.style.opacity = "0.6"; // Optional: visually indicate disabled
  }
  const customButton = document.querySelector("#btnSubmit"); //your custom button
  if (customButton) {
    customButton.disabled = true;
    customButton.style.pointerEvents = "none"; // Prevent clicks
    customButton.style.cursor = "not-allowed";
    customButton.style.opacity = "0.6"; // Optional: visually indicate disabled
  }
};

Callback: OnPaymentCompleted (response)

Once payment completed, then response will be triggered back to this callback function automatically. The following fields will be received from this callback.

{
"responsekey": "b65f6af5d9f3ffc9a7792b2c45fcbeba2dbe83ef55cdd08faa3c14d606e4710d2a66f97103e07b49c45c7111ae950ea1ee85ecfa5abd4532e0854f923e5dfd60",
"amount": "0.01",
"reference": "lpstest123",
"description": "lpstest123",
"currency": "AUD",
"errorcode": "00",
"errordesc": "Success"
}

Clients can write custom logic to make a call to their backend and initiate a server-to-server API to Latpay Payment AuthStatus Check API to validate the payment, before displaying the results to customers.

window.LatpayCheckout.OnPaymentCompleted = (val) => {
  
  setResult(val);

  if (val.responsekey !== "") {
    const authRequest = {
      merchantid: formData.Merchant_User_Id,
      amount: formData.Amount,
      currency: formData.Currency,
      reference: formData.Reference,
      transactionkey: formData.AuthStatusCheck,
    };

    fetch(
      "https://lateralpayments.com/checkout-staging/authorise/authstatuscheck",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json; charset=utf-8",
        },
        body: JSON.stringify(authRequest),
      }
    )
      .then((response) => response.json())
      .then((data) => {
        
        setAuthStatusCheck(data);
      })
      .catch((err) => {
        console.error("Error in Auth Status Check:", err);
      });
  }
};

AuthStatusCheck

Note: transactionkey combination - which is a SHA-256 hash of the following parameter:

• currency – type of currency used for transaction.
• amount – total value of amount.
• reference - unique transaction reference in merchant system [use your unique value in reference]
• datakey – will be issued by latpay.

**** PS. The above sample implementation shows the authstatuscheck being called from front end script, however, it is recommended to make this call from merchant server for added security.

If all buttons are disabled based on the OnPaymentAction, then upon receiving a failed response in OnPaymentCompleted, all buttons—including the custom button, Google Pay, and Apple Pay buttons—should be re-enabled to allow further user interaction