Введение

JS SDK - библиотека, которая поможем вам интегрироваться с API SDK. Вам остается лишь сделать свою форму и вызвать соответствующий метод в JS SDK. Для использования этого метода необходимо соблюдать определенные требования безопасности .

Для того, чтобы использовать эту механику, мерчант должен установить скрипт на свой сайт. Скрипт будет собирать данные сайта и надежно зашифровывать их. Потом эти данные в виде токена будут отправлены в API. Если эта механика не подходит, то можно использовать API SDK для интеграции. Для использования JS SDK вам необходимо обратиться к личному менеджеру.

SDK для JavaScript

Инициализация

Для инициализации SDK требуется добавить следующий код в 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>

Теперь вам доступен объект SDK, установите ваш publickey и token

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

* publickey и token можно получить у Вашего менеджера

Описание методов SDK

Получение токена

Для проведения платежа первым этапом требуется создать токен платежной карты:

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:

После получения токена, ее можно использовать для проведения платежа.

Одноэтапный платеж

// Создание объекта платежа
const JSPaymentOptions = {
  order_id: "my-order",
  auto_clearing: 0, 
  amount: 20, 
  currency: "KZT", 
  description: "Описание заказа",
  test: 0,
  options: {
    custom_params: {},
    user: {
      email: "string",
      phone: "string"
    }
  },
};

JSPaymentOptions:

// Оплата через заранее полученный токен
const JSTransactionOptionsBankCardToken = {
  type: 'tokenized_card',
  options: {
    token: JSTokenResponse.token,
    card_cvv: 123
  }
};

// Создание платежа
try {
  let JSPayResult = await FreedomPaySDK.charge(
    JSPaymentOptions, JSTransactionOptionsBankCardToken
  );

  if (JSPayResult.payment_status === "need_confirm") {
    // FreedomPay делает обработку 3ds проверки
    JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
    // или
    // JSPayResult = await FreedomPaySDK.confirm3ds1(JSPayResult, JS3dsv1AcsOptions);
  }

} catch(JSErrorObject) {}

JSTransactionOptionsBankCardToken:

JS3dsv1AcsOptions:

// Оплата через карточные данные, без предварительной генерации токена
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 делает обработку 3ds проверки
    JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
    // или
    // JSPayResult = await FreedomPaySDK.confirm3ds1(JSPayResult, JS3dsv1AcsOptions);
  }
 
} catch(JSErrorObject) {}

JSTransactionOptionsBankCard:

Ответы

JSPayResult:

JSTokenResponse:

JSErrorObject:

Если пришел JSPayResult.payment_status = need_confirm

Есть несколько механик прохождения 3DS:

На стороне SDK:

Весь процесс 3ds проходит на стороне js sdk, единственное что надо сделать мерчанту - это создать DOM елемент с id="3dsForm", в нем плательщик будет вводить данные 3ds.

Рекомендованные размеры DOM элемента - 550px X 600px.
Свойство id можно изменить при вызове функции confirmInIframe(JSPayResult, "myCustom3dsElement").

В этот момент, мерчант должен подготовить контейнер (3dsForm) для правильного отображения клиенту. К примеру, открыть выплывающее окно, убрать форму и показать контейнер и т д.

Запрос на confirmInIframe

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

2. Собственная реализация обработки 3ds формы

При запросе на charge, в случае, если на карте установлен 3ds, необходимо сделать запрос в ACS сервер банка эмитента карты.

При необходимости прохождения 3ds в ответе на вызов метода charge будет JSPayResult.payment_status = need_confirm и дополнительный объект 3ds с параметрами JS3dsv1Object:

<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>

В случае успеха на TermUrl поступит POST запрос со следующими параметрами:

После получения этих параметров, требуется сделать запрос на confirm3dsv1:

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

Пример полной интеграции

<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()">Оплатить</button>
    <script>
      window.onload = function () {
        FreedomPaySDK.setup('mypublickey', 'mytoken');
      }

      async function pay() {
		validateMyForm();

        const JSPaymentOptions = {
          order_id: "my-order", // должен быть уникальным на каждый запрос
          auto_clearing: 0,
          amount: 20,
          currency: "KZT",
          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");
          }

          // открыть страницу результата платежа и т д
          // ...
          console.log(JSPayResult);

        } catch(JSErrorObject) {
          // Обработать JSErrorObject.response
          setLoading(false);
          showError(JSErrorObject);
        }
      }

      // необязательные функции, нужны как пример
      function showPopup(id) {
        // открытие всплывающего окна
      }

      function setLoading(status) {
        // триггер для загрузки, перекрытие формы, блокировка кнопок
      }

      function showError(error) {
        // показываем ошибку
      }

      function validateMyForm() {
		// валидация данных введенных пользователем, к примеру данные карты
      }
    </script>
  </body>
</html>

* тестовые карты доступны в личном кабинете мерчанта по адресу — https://my.freedompay.kz/dev