Introduction

JS SDK - a library that will help you integrate with the SDK API. You just have to make your form and call the appropriate method in the JS SDK. You need to meet certain security requirements to use this method.

In order to use this mechanic, the merchant must install the script on their website. The script will collect website data and securely encrypt it. Then this data in the form of a token will be sent to the API. If this mechanic is not adequate, then you can use the SDK API for integration.

SDK for JavaScript

Initialization

To initialize the SDK, you need to add the following code to the head:


<script>
  (function (f, p, s, d, k) {
    d = f.createElement(p);
    k = f.getElementsByTagName(p)[0];
    d.src = 'https://cdn.freedompay.kz/sdk/js-sdk-1.0.0.js';
    k.parentNode.insertBefore(d, k);
  })(document, 'script');
</script>

Now the SDK object is available to you, set your publickey and token


FreedomPaySDK.setup('mypublickey', 'mytoken');

you can get publickey and token from your manager

Description of SDK Methods

Getting a token

To make a payment, the first step is to create a payment card token:


const JSTokenizeOptionsBankCard = {
  type: 'bank_card',
  options: {
    card_number: "11111111111111",
    card_holder_name: "test",
    card_exp_month: "01",
    card_exp_year: "25"
  }
};

try {
  const JSTokenResponse = await FreedomPaySDK.tokenize(JSTokenizeOptionsBankCard);
} catch(JSErrorObject) {}

JSTokenizeOptionsBankCard:

After receiving the token, you can use it to make a payment.

One-step payment


// Creation of a payment object
const JSPaymentOptions = {
  order_id: "my-order",
  auto_clearing: 0, 
  amount: 20, 
  currency: "KZT", 
  description: "Order description",
  test: 0,
  options: {
    custom_params: {},
    user: {
      email: "string",
      phone: "string"
    }
  },
};

JSPaymentOptions:


// Payment via pre-received token
const JSTransactionOptionsBankCardToken = {
  type: 'tokenized_card',
  options: {
    token: JSTokenResponse.token,
    card_cvv: 123
  }
};

// Creating a payment
try {
  let JSPayResult = await FreedomPaySDK.charge(
    JSPaymentOptions, JSTransactionOptionsBankCardToken
  );

  if (JSPayResult.payment_status === "need_confirm") {
    // FreedomPay does 3ds check processing
    JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
    // or
    // JSPayResult = await FreedomPaySDK.confirm3ds1(JSPayResult, JS3dsv1AcsOptions);
  }

} catch(JSErrorObject) {}

JSTransactionOptionsBankCardToken:

JS3dsv1AcsOptions:


// Payment via card data, without prior token generation
const JSTransactionOptionsBankCard = {
  type: 'bank_card',
  options: {
    card_number: "11111111111111",
    card_holder_name: "test",
    card_exp_month: "09",
    card_exp_year: "25",
    card_cvv: 123
  }
};

try {
  let JSPayResult = await FreedomPaySDK.charge(
    JSPaymentOptions, JSTransactionOptionsBankCard
  );

  if (JSPayResult.payment_status === "need_confirm") {
    // FreedomPay does 3ds check processing
    JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
    // or
    // JSPayResult = await FreedomPaySDK.confirm3ds1(JSPayResult, JS3dsv1AcsOptions);
  }
 
} catch(JSErrorObject) {}

JSTransactionOptionsBankCard:

Responses

JSPayResult:

JSTokenResponse:

JSErrorObject:

3DS

If came JSPayResult.payment_status = need_confirm

There are several 3DS passing mechanics:

On the SDK side:

The whole 3ds process takes place on the js sdk side, the only thing the merchant needs to do is create a DOM element with id="3dsForm", in which the payer will enter 3ds data. The recommended DOM element dimensions are 550px X 600px.

The id property can be changed when calling the function confirmInIframe(JSPayResult, "myCustom3dsElement").

At this point, the merchant must prepare the container (3dsForm) to properly render to the client. For example, open a pop-up window, remove the form and show the container, etc.

Request for confirmInIframe


const JSPayResult = await FreedomPaySDK.confirmInIframe (
  JSPayResult (from charge), "3dsForm"
);

2.Own implementation of 3ds form processing

When requesting a charge, if 3ds is installed on the card, you must make a request to the ACS server of the card issuer's bank.

If it is necessary to pass 3ds, the response to the charge method call will contain JSPayResult.payment_status = need_confirm and an additional 3ds object with JS3dsv1Object parameters:


<form name="3dsForm" action="JSPayResult['3ds'].acsurl" method="POST">
  <input type="hidden" name="PaReq" value="JSPayResult['3ds'].pareq">
  <input type="hidden" name="MD" value="JSPayResult['3ds'].md">
  <input type="hidden" name="TermUrl" value="https://mysite.com/myTermUrl">
</form>
<script>
    document.getElementById('3dsForm').submit();
</script>

If successful, TermUrl will receive a POST request with the following parameters:

After receiving these parameters, you need to make a request to confirm3dsv1:


try {
  const JSPayResult = await FreedomPaySDK.confirm3dsv1(JSPayResult, JS3dsv1AcsOptions);
} catch(JSErrorObject) {}

Full integration example


<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script>
      (function (f, p, s, d, k) {
        d = f.createElement(p);
        k = f.getElementsByTagName(p)[0];
        d.src = 'https://cdn.freedompay.kz/sdk/js-sdk-1.0.0.js';
        k.parentNode.insertBefore(d, k);
      })(document, 'script');
    </script>
  </head>
  <body>
    <div id="3dsForm"></div>
    <button onclick="pay()">Pay</button>
    <script>
      window.onload = function () {
        FreedomPaySDK.setup('mypublickey', 'mytoken');
      }

      async function pay() {
		validateMyForm();

        const JSPaymentOptions = {
          order_id: "my-order", // must be unique per request
          auto_clearing: 0,
          amount: 20,
          currency: "KZT",
          description: "Order description",
          test: 0,
          options: {
            custom_params: {},
            user: {
              email: "client@email.com",
              phone: "+77777777777"
            }
          },
        };

        const JSTransactionOptionsBankCard = {
          type: 'bank_card',
          options: {
            card_number: "11111111111111",
            card_holder_name: "test",
            card_exp_month: "09",
            card_exp_year: "25",
            card_cvv: 123
          }
        };

        try {
          setLoading(true);

          let JSPayResult = await FreedomPaySDK.charge(
            JSPaymentOptions, JSTransactionOptionsBankCard
          );

          if (JSPayResult.payment_status === "need_confirm") {
            showPopup('3dsFormWrapper');

            JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
          }

          // open the payment result page, etc.
          // ...
          console.log(JSPayResult);

        } catch(JSErrorObject) {
          // Process JSErrorObject.response
          setLoading(false);
          showError(JSErrorObject);
        }
      }

      // optional functions, needed as an example
      function showPopup(id) {
        // opening a popup window
      }

      function setLoading(status) {
        // load trigger, form overlay, button blocking
      }

      function showError(error) {
        // show error
      }

      function validateMyForm() {
		// validation of data entered by the user, for example card
      }
    </script>
  </body>
</html>

*test cards are available in the merchant's personal account at

https://my.freedompay.kz/dev