@latpay/latpay-react-component - npm Package Compare versions

Comparing version 4.1.0 to 4.1.1

package.json

 {
   "name": "@latpay/latpay-react-component",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "main": "dist/Latpaycomponent.js",
@@ -5,0 +5,0 @@ "scripts": {

README.md

@@ -1,135 +0,254 @@
-Installation:
-Step 1:
-Download the @latpay/latpay-react-component package from public repository (NPM) and install it.
+## Installation
+
+### Step 1: Install the package
+
+Download the `@latpay/latpay-react-component` package from NPM:
+
 Command to install the package:
+
+```bash
 npm i @latpay/latpay-react-component
+```
 
-Step 2:
+### Step 2: Import the component
 
-    import {LoadScripts} from @latpay/latpay-react-component
+```js
+import Latpaycomponent from "@latpay/latpay-react-component";
+```
 
-Authentication
-• Next, to authenticate the merchant account to enable binding of Checkout elements into the payment page. This is performed by calling the open() function inside the package
+## Authentication
 
-• 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.
+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
-                            status: (status) => {
-                            // status...
-                            },
-                        });
+```js
+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.
+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">
+```html
+<div id="latpay-element"></div>
+```
 
-                           </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:
+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
-                            status: (status) => {
-                            //status.....
-                            },
-                            });
+```js
+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
+<br/>
+<b>Card Payment:</b>
+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",
-                });
+```js
+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
-            • transactionkey - 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 reference in merchant system [use your unique value in reference]
-            • \_3dcheck - “Y” || “N”.
-            • datakey – will be issued by latpay and need to maintain secure.
+> **Note:** secure3DPayment transkey combination - which is a SHA-256 hash of the following parameters:
+>
 
-Callback :
-Call the call back function named as “OnPaymentCompleted”, once payment completed then response will be triggered inside the function automatically. The following fields will be received from the package
+> - currency – type of currency used for transaction.
+> - amount – total value of amount.
+> - reference - unique transaction
+> - \_3dcheck - “Y” || “N”.
+> - datakey – will be issued by latpay.
 
-                                    {
-                                    "responsekey": "b65f6af5d9f3ffc9a7792b2c45fcbeba2dbe83ef55cdd08faa3c14d606e4710d2a66f97103e07b49c45c7111ae950ea1ee85ecfa5abd4532e0854f923e5dfd60",
-                                    "amount": "0.01",
-                                    "reference": "lpstest123",
-                                    "description": "lpstest123",
-                                    "currency": "AUD",
-                                    "errorcode": "00",
-                                    "errordesc": "Success"
-                                    }
+## 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.
+
+```json
+{
+  "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:
+
+```json
+{
+  "type": "card",
+  "status": {
+    "responsetype": "1",
+    "statuscode": "0",
+    "statusdesc": "Card payment processing...",
+    "errorcode": "",
+    "errordesc": ""
+  }
+}
+```
+
+#### Card Failed:
+
+```json
+{
+  "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.
+
+```js
+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.
+
+```js
+{
+"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.
 
+```js
 window.LatpayCheckout.OnPaymentCompleted = (val) => {
-console.log("Payment completed:", 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,
-};
-console.log(authRequest);
+  
+  setResult(val);
 
-            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) => {
-                console.log(data);
-                setAuthStatusCheck(data);
-              })
-              .catch((err) => {
-                console.error("Error in Auth Status Check:", err);
-              });
-          };
-        }
+  if (val.responsekey !== "") {
+    const authRequest = {
+      merchantid: formData.Merchant_User_Id,
+      amount: formData.Amount,
+      currency: formData.Currency,
+      reference: formData.Reference,
+      transactionkey: formData.AuthStatusCheck,
+    };
 
-\*\* AuthStatusCheck transkey combination
+    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);
+      });
+  }
+};
+```
 
-· transactionkey - which is a SHA-256 hash of the following parameters.
+### AuthStatusCheck 
 
-• currency – type of currency used for transaction.
+> **Note:**  `transactionkey` combination - which is a SHA-256 hash of the following parameter:
 
-• amount – total value of amount.
+- 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.
 
-• reference - unique transaction reference in merchant system [use your unique value in reference]
+\*\*\*\* 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.
 
-• datakey – will be issued by latpay and need to maintain secure.
-
-\*\*\*\* 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 to 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

No alert changes

Improved metrics

Total package byte prevSize

13010

27.69%

Number of lines in readme file

255

87.5%

No dependency changes