JS & Web Embedded Form

Step 1: SDK Initialization

Please ensure the SDK Initialization steps are completed before proceeding with the following steps. This is crucial for the proper functioning of the payment process.

Step 2: Initiate Payment with HTML Elements

On the client side, pass selector of HTML elements for credit card name, credit card number, credit card expiry year, credit card expiry month, and credit card CVV. This method will initiate the Payment object:

📘
The initPayment must be called at the beginning of the webpage after loading the credit card fields (card number, card name, etc..). For example,
window.addEventListener("load", async (event) => {
  try {
    await payment.initPayment(
      '#card-number',
      '#card-name',
      '#card-year',
      '#card-month',
      '#card-ccv'
    );
  } catch (error) {
  }
});

await payment.initPayment(
  '#card-number',
  '#card-name',
  '#card-year',
  '#card-month',
  '#card-ccv'
);

🚧
Important Notice
HTML elements for credit card name, credit card number, credit card expiry year, credit card expiry month, and credit card CVV must be marked as readonly as in the following example. Otherwise, they will be ignored.

<table>
  <tbody>
    <tr>
      <td>Card Number</td>
      <td>
        <input id="card-number" readonly type="text" />
        <!-- must be readonly -->
      </td>
    </tr>
    <tr>
      <td>Card Name</td>
      <td>
        <input id="card-name" readonly type="text" />
        <!-- must be readonly -->
      </td>
    </tr>
    <tr>
      <td>Card Year</td>
      <td>
        <input id="card-year" readonly type="text" />
        <!-- must be readonly -->
      </td>
    </tr>
    <tr>
      <td>Card Month</td>
      <td>
        <input id="card-month" readonly type="text" />
        <!-- must be readonly -->
      </td>
    </tr>
    <tr>
      <td>Card CVV</td>
      <td>
        <input id="card-ccv" readonly type="text" />
        <!-- must be readonly -->
      </td>
    </tr>
  </tbody>
</table>

The initPayment method is a JavaScript function that takes HTML elements representing credit card information as input parameters and returns a Promise object. Its purpose is to initiate the payment process by creating a new payment session and validating the credit card information provided by the user.

To use this method, a developer would call it with the appropriate HTML elements for credit card information, such as the credit card number, expiration date, and security code. The method will then validate the credit card information and return a Promise object that can be used to wait for the initiation process to complete.

It's important to note that initPayment only initiates the payment form and does not trigger the payment transaction. To send the Payment, the developer must call the "sendPayment" method, which takes the payment details and completes the transaction.

The Promise object returned by initPayment will resolve once the payment initiation process is complete. To use the initPayment method, a developer would typically call it with the appropriate HTML elements for credit card information and then wait for the Promise object to resolve before proceeding with any further actions related to the payment process.

Overall, the "initPayment" method is a crucial step in the payment process that helps ensure the security and accuracy of user-provided credit card information.

Step 3: Submit the Invoice to Open the 3DS Window

Call the submitInvoice function to send the Paylink payment information to Paylink, and it will open the 3DS page for completing the payment process. It takes the generated "transactionNo" in the server-side (Step 1) .

payment.submitInvoice(transactionNo).then((response) => {
            console.log('send payment response', response);
            alert(response.reason);
        });

The submitInvoice method returns a Promise object, which handles the payment result. The then form of the Promise object takes a callback function that will be executed once the Payment is completed.

The callback function takes a single argument in the provided code: paymentError. This argument represents any error that occurred during the payment process. If the Payment was successful, paymentError will be null, and a 3DS (3-D Secure) page will be opened. 3-D Secure is a security protocol used to authenticate the buyer and reduce the risk of fraud. When 3-D Secure is opened, the buyer will be prompted to enter additional information (such as a one-time code sent via SMS) before the Payment is completed.

Parameters name	Description	value type
transactionNo	The transaction no of the created invoice in the backend server (Step 1).	string

Step 4: Handling Payment Process Response

Finally, from the server side, programmatically process the payment response sent by Paylink after the payment process finishes. This step is crucial for security reasons; carefully follow Get Invoice to handle the payment result from Paylink.

Sample Code

You can download a sample of the code written in PHP from here.

Example Code

This is an example of the code of how to use the JavaScript Library within Application frameworks like ReactJS and Angular.

import React, { useEffect } from 'react';
// Step 1: Referring to javascript SDK
import PaylinkPayments, { CardBrand } from 'paylink.src.js';

function MerchantDemo() {
  useEffect(() => {
    const fetchData = async () => {
      // Step 2: Getting transactionNo using a client call to server
      const transactionNo = await getTransactionNo();

      // Step 3: Creating Payment javascript object
      const payment = new PaylinkPayments({ mode: 'test' });

      try {
        // Step 4: Initiate Payment with HTML elements
        await payment.initPayment(
          '#card-number',
          '#card-name',
          '#card-year',
          '#card-month',
          '#card-ccv',
          (error: any) => {
            alert('payment error' + (error.reason ? error.reason : error));
          }
        );
        alert('payment loaded. You can pay now');
      } catch (error) {
        alert('payment error' + error);
      }

      // Step 5: Sending the Payment and open the 3DS window
      try {
        const response = await payment.submitInvoice(transactionNo);
        console.log('response of send payment is:', response);
        alert('response is: ' + JSON.stringify(response));
      } catch (error) {
        console.log('calling send payment caused error: ', error);
        alert(error.title);
      }
    };

    fetchData();
  }, []);

  const getTransactionNo = async () => {
    // Make an API call to the server to get the transactionNo
    const response = await fetch('/getTransactionNo');
    const data = await response.json();
    return data.transactionNo;
  };
  
  // Step 6: NOTE: After the payment is processed (either paid or declined), you must from the server side call
  // the endpoint https://restapi.paylink.sa/api/getInvoice/{transactionNo} for production or
  // the endpoint https://restpilot.paylink.sa/api/getInvoice/{transactionNo} for testing
  // to check the invoice status as appear in the processPayment.php example file.

  return (
    <div>
      <p>Welcome to Merchant Demo for Paylink Payment javascript SDK.</p>

      <table border="1">
        <tbody>
          <tr>
            <td>clientName</td>
            <td>Zaid Matooq</td>
          </tr>
          <tr>
            <td>clientMobile</td>
            <td>920022174</td>
          </tr>
          <tr>
            <td>amount</td>
            <td>5</td>
          </tr>
          <tr>
            <td>orderNumber</td>
            <td>12301230123</td>
          </tr>
          <tr>
            <td>clientEmail</td>
            <td>[email protected]</td>
          </tr>
          <tr>
            <td>products</td>
            <td>
              <table border="1">
                <tbody>
                  <tr>
                    <td>title</td>
                    <td>price</td>
                    <td>qty</td>
                  </tr>
                  <tr>
                    <td>Dress 1</td>
                    <td>120</td>
                    <td>2</td>
                  </tr>
                  <tr>
                    <td>Dress 2</td>
                    <td>120</td>
                    <td>2</td>
                  </tr>
                  <tr>
                    <td>Dress 3</td>
                    <td>70</td>
                    <td>1</td>
                  </tr>
                </tbody>
              </table>
            </td>
          </tr>
        </tbody>
      </table>

      <div id="paymentData"></div>

      <div style={{ margin: '15px' }}>
        <table>
          <tbody>
            <tr>
              <td>Card Number</td>
              <td>
                <input id="card-number" readOnly type="text" />
              </td>
            </tr>
            <tr>
              <td>Card Name</td>
              <td>
                <input id="card-name" readOnly type="text" />
              </td>
            </tr>
            <tr>
              <td>Card Year</td>
              <td>
                <input id="card-year" readOnly type="text" />
              </td>
            </tr>
            <tr>
              <td>Card Month</td>
              <td>
                <input id="card-month" readOnly type="text" />
              </td>
            </tr>
            <tr>
              <td>Card CVV</td>
              <td>
                <input id="card-ccv" readOnly type="text" />
              </td>
            </tr>
          </tbody>
        </table>
        <a href="javascript:payInvoiceNow()">Pay Now By VISA / MasterCard / MADA (By Transaction No)</a>
        <br />
        <br />
        <a href="javascript:applePayInvoice()">Pay Now By ApplePay (By Transaction No)</a>
        <br />
      </div>
    </div>
  );
}

export default MerchantDemo;

Step 1: SDK Initialization

Step 2: Initiate Payment with HTML Elements

📘

🚧Important Notice

Step 3: Submit the Invoice to Open the 3DS Window

Step 4: Handling Payment Process Response

Sample Code

Example Code

🚧
Important Notice