К основному контенту

Введение

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:
НазваниеТипОписание
typestringТип криптуемых данных. bank_card - банковская карта
options.card_numberstringНомер карты. Поле для ввода номера карты должно поддерживать ввод от 13 до 19 цифр
options.card_holder_namestringИмя держателя карты
options.card_exp_monthstringМесяц истечения карты
options.card_exp_yearstringГод истечения карты
После получения токена, ее можно использовать для проведения платежа.
Одноэтапный платеж
// Создание объекта платежа
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:
НазваниеТипОписание
order_idstringУникальный идентификатор в системе магазина
auto_clearingint1 - если требуется провести клиринг автоматически, 0 - если мерчант сам вызовет метод клиринга
amountfloatСумма платежа
currencystringВалюта платежа
descriptionstringОписание платежа
testint1 - если тестовый режим платежа, 0 - если боевой
options.custom_paramsobjectДополнительные параметры. Будут высланы обратно мерчанту на ResultURL после проведения платежа.
options.user.emailstringEmail клиента
options.user.phonestringНомер телефона клиента
// Оплата через заранее полученный токен
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:
НазваниеТипОписание
typestringТип передаваемых данных. tokenized_card - передача токена карты
options.tokenstringРанее полученный токен карты
options.card_cvvintCVC/CVV карты, для которой был сделан токен
JS3dsv1AcsOptions:
НазваниеТипОписание
paresstringПараметр, который приходит на termUrl
mdstringПараметр, который приходит на termUrl
// Оплата через карточные данные, без предварительной генерации токена
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:
НазваниеТипОписание
typestringТип передаваемых данных. bank_card - передача открытых данных карты
options.card_numberstringНомер карты. Поле для ввода номера карты должно поддерживать ввод от 13 до 19 цифр
options.card_holder_namestringИмя держателя карты
options.card_exp_monthstringМесяц истечения карты
options.card_exp_yearstringГод истечения карты
options.card_cvvintCVC/CVV карты
Ответы

JSPayResult:
НазваниеТипОписание
payment_idintegerНомер платежа
order_idstringУникальный идентификатор в системе продавца
payment_statusstringСтатус платежа. Возможные значения: success, error, need_confirm
3dsobjectДанные для 3ds, приходит при payment_status = need_confirm
3ds.versionstringВерсия 3ds
3ds.acsurlstringUrl Банка эмитента карты для проверки 3ds
3ds.mdstringПараметр для запроса 3ds
3ds.pareqstringПараметр для запроса 3ds
3ds.frame_urlstringПараметр, который используется для проведения 3ds на стороне FreedomPay, мерчант никак не взамодействует с данным параметром.
JSTokenResponse:
НазваниеТипОписание
tokenintegerТокен для дальнейшей оплаты
JSErrorObject:
НазваниеТипОписание
response.error_codestringКод ошибки
response.error_messagestringОписание ошибки
Если пришел JSPayResult.payment_status = need_confirm

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

  1. На стороне 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>
ПолеОписание
PaReqПараметр pareq из ответа
MDПараметр md из ответа
TermUrlUrl, на который будет переведен клиент после прохождения 3DS
В случае успеха на TermUrl поступит POST запрос со следующими параметрами:
ПолеОписание
PaResПараметр необходим для запроса paymentAcs
MDПараметр необходим для запроса paymentAcs
После получения этих параметров, требуется сделать запрос на 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