Мы используем cookie-файлы
Хорошо

Введение

API SDK это метод интеграции с системой Freedom Pay с помощью отправки токенов. API SDK позволяет самостоятельно настроить удобный для мерчанта метод обращения в наш API, отправляя карточные данные, которые будут надежно зашифрованы. Платежи соответствуют правилам PCI DSS, при соблюдении мерчантом определенных требований.

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

Группа роутов создана для работы с JS SDK, который предоставляется мерчантам для реализации приема платежей без использования фреймов или платежных страниц.
Механика отправки запросов
Заголовки запросов
Пример стандартного запроса
{
    "data": [
        "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"
    ],
    "token": "merchant-token"
}
Каждый запрос состоит из двух полей:
Авторизация

Авторизация запроса производится путем передачи уникального токена в теле запроса.

Так же само тело запроса должно быть зашифровано публичным ключом, который выдается мерчанту при подключении вместе с токеном.
Процесс шифрования тела запроса

  1. Сначала переводим данные в JSON строку, которая не содержит переносов и лишних пробелов.
  2. Кодируем полученную строку в Base64.
  3. Разбиваем полученную строку на подстроки по 200 символов.
  4. Шифруем каждую подстроку отдельно публичным ключом.
  5. Снова кодируем каждую строку в Base64.
  6. Записываем полученные подстроки в массив data.
// Пример отправки запроса:
$array = [
  'type' => 'bank_card',
  'options' => [
    'card_number' => '4405645000001234',
    'card_holder_name' => 'NAME',
    'card_exp_month' => '02',
    'card_exp_year' => '25',
  ]
];
$json = json_encode($array); // Переводим данные в json
$base64 = base64_encode($json); // Кодируем в Base64
$chunks = str_split($base64, 200); // Разбиваем на части по 200 символов
$result = [];
foreach ($chunks as $chunk) {
    openssl_public_encrypt($chunk, $encrypted, $publicKey); // Шифруем публичным ключом
    $result[] = base64_encode($encrypted); // Снова кодируем в base64
}
print_r($result);
Уникальность запроса

Каждый запрос должен сопровождаться передачей параметра Request-Id в Headers.

Рекомендуется использовать Uuid V4 для того, чтоб исключить пересечения с другими запросами.

В случае если сервис получает второй запрос с тем Request-Idкоторый был получен ранее, вернется ошибка.

Токенизация карты

Токенизация карты для проведения дальнейшей оплаты.
Пример запроса:
{
    "type": "bank_card",
    "options": {
        "card_number": "4405645000001234",
        "card_holder_name": "NAME",
        "card_exp_month": "02",
        "card_exp_year": "25"
    }
}
Пример ответа:
{
    "status": "success",
    "data": {
        "token": "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.LyIIVulOXIj3tV_ttHigOsCFEhjy2_CZRGI8T7jx8QqtkpgI9gu52aBgUFZ1NHMVYihxcl6P4m5vC2BP88oWGDYtTLW4SzJkCd27LXqMMYtZo9XretbodQS-MF6k5lAeTqfC_lILWXl0eGmoYg5tLXStiVsiTHjVksu9VqSgp8PxBdR-RMZ5gDJ0dkEnHghv4_WK8KudcXU6MiabxtqYPACoy_NZ9rR2zic0tSTW2Ev8e-k75kgwWLNSTxw7QvrrtOfmOGW5_jWssjaK31FZnvrjhpJ8snmMxBzXLfj98GvwjEj9a96sDyK3bApas9e6SLoSxpH9mGgrBA_H7_wPkg.dyHVsu7o9zlWTOG7_MIMTQ.RYrLoCxYDeOSoxHG4XlXfKDlQPZACMZro9poUxFUkyrfDnGNEv2BIQm9WFkIaR4PXf-G8cD1L44hgZNjZ-v5o3kS0ABiFtaEWL-QE9Zl8KutPFMPU_1uIxFbcfNwgO4QX2zJxdYX2Bjm2nDUml3oUg.vKd5QUUKWiKwhA4FSh5DFQ"
    }
}
URL запроса
POST https://api.freedompay.kz/v5/sdk/tokenize

Headers
Проведение платежа

Запрос на проведение платежа с использованием ранее токенизированной карты.
Пример запроса:
{
  "order_id": "my-order",
  "auto_clearing": 1,
  "amount": 20,
  "currency": "KZT",
  "description": "Описание заказа",
  "test": 0,
  "options": {
    "custom_params": {},
    "user": {
      "email": "string",
      "phone": "string"
    }
  },
  "transaction": {
    "type": "tokenized_card",
    "options": {
      "token": "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.eTYB5I4ttwS6CM1oawgYRf9aLfTFzcEK3mKjJ5AMNCM69SdWysQdjrWVTh3Mh7BQtJYypmnbYNZb5SdSkvMawqnnEaEjS4UFFLM_bXYa8Eut3ZX4tXL-rZfouzUdpjatXsMvcxOixGiQm2UP6pEo7tAOx_t5h2_y8vk9so8garyTBbOQqF3MKDGShRLQUyNqcYzg1qezE_OZiFnpS1uU_x6La2XqqgkejIfiS2f3lc4DkD5aygM_yGwDcQMeGRdgBI_rg23q71zbOxuFOXoXVRdIdx2Y_V_tZ3JnXX1KkZSqdUNL2-XMGCC4Nnk2A3W1YQ_Ld0gN02b4Om43Nmpr9Q.xcXMT0eeva-2UnX3zNK1KQ._thk7WP3-pcIh_XuS_tnUkCYcNsnw0-yUbzx1rsq182jy1SH0PDaM_54KYfsqzgsemplO5U2tzPivx_k9VzoLwFFxjHfIMmVc3SFleyVIIKO0xY0KsU7fzNf4_BKwvXR6Ur4Q3E1g8NE4sWQJpy6tQ.vKqh65_qZS9-G2JmxYLErQ",
      "card_cvv": 223
    }
  }
}
Пример ответа:
{
    "status": "success",
    "data": {
        "3ds": {
            "acsurl": "some_asc_url",
            "frame_url": "",
            "md": "MD",
            "pareq": "PaReq",
            "version": 1
        },
        "payment_id": "97397805",
        "payment_status": "need_confirm"
    }
}
Если мерчант сам проводит 3DS, требуется переслать клиента на AcsUrl методом POST. Кроме параметров MD и PaReq, требуется передать TermUrl. На этот TermUrl вернется клиент после прохождения 3ds с параметрами MD и PaRes.
Пример формы для пересылки клиента:
<form name="3dsForm" action="data.3ds.acsurl" method="POST">
  <input type="hidden" name="PaReq" value="data.3ds.pareq">
  <input type="hidden" name="MD" value="data.3ds.md">
  <input type="hidden" name="TermUrl" value="https://mysite.com/myTermUrl">
</form>
<script>
    document.getElementById('3dsForm').submit();
</script>
URL запроса
POST https://api.freedompay.kz/v5/sdk/charge

Headers
Запрос на ACS Url

Метод может быть использован в случае прохождения 3DS без JS SDK. После того, как клиент вернулся на TermUrl с параметрами MD и PaRes, требуется вызвать текущий метод.
Пример запроса:
{
    "payment_id": 0,
    "pares": "string",
    "md": "string"
}
Пример ответа:
{
    "status": "success",
    "data": {
        "auth_code": "123456",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
URL запроса
POST https://api.freedompay.kz/v5/sdk/charge

Headers
Проверка статуса платежа

Рекомендуется проверять статус каждого платежа после его проведения.
Пример запроса:
{
  "order_id": "merchant_order_id",
  "payment_id": 123456
}
Пример ответа:
{
    "status": "success",
    "data": {
        "order_id": "merchant_order_id",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
URL запроса
POST https://api.freedompay.kz/v5/sdk/charge

Headers
Справочники

Статусы платежей
Коды ошибок