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

API SDK

Introduction

The API SDK is a method for integrating with the Freedom Pay system by sending tokens. The SDK API allows you to set up a convenient method for the merchant to contact our API by sending card data that will be securely encrypted. Payments comply with PCI DSS rules, subject to certain requirements by the merchant

To use the SDK API, you need to contact your personal manager. If you want to implement a payment form, then you can use the JS SDK to integrate.
Using the API

The route group was created to work with the JS SDK, which is provided to merchants to implement payment acceptance without using frames or payment pages.
Request submission mechanics
Request methodRequest body format
POSTJSON
Request headers
Name MeaningDescription
Content-typeapplication/jsonRequest body format
Request-Idunique stringA unique string for each request. In case of a double, the system will respond with an error. It is recommended to use UUID V4.
Example of a standard request
{
    "data": [
        "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"
    ],
    "token": "merchant-token"
}
Each request consists of two fields:
NameDescription
dataAn array containing the encrypted request body with the public key. The encryption process is described below.
tokenA unique token that is issued to the merchant for using the JS SDK
Authorization

Request authorization is done by passing a unique token in the request body.

Also, the request body itself must be encrypted with a public key, which is issued to the merchant upon connection along with the token.
Request Body Encryption Process

  1. First, we translate the data into a JSON string that does not contain hyphens and extra spaces.
  2. We encode the received string in Base64.
  3. We split the received string into substrings of 200 symbols each.
  4. We encrypt each substring separately with a public key.
  5. We encode each string in Base64 again.
  6. We write the received substrings to the data array.
// Example of sending a request:
$array = [
  'type' => 'bank_card',
  'options' => [
    'card_number' => '4405645000001234',
    'card_holder_name' => 'NAME',
    'card_exp_month' => '02',
    'card_exp_year' => '25',
  ]
];
$json = json_encode($array); // Convert data to json
$base64 = base64_encode($json); // Encode in Base64
$chunks = str_split($base64, 200); // Split into parts of 200 symbols
$result = [];
foreach ($chunks as $chunk) {
    openssl_public_encrypt($chunk, $encrypted, $publicKey); // Encrypt with public key
    $result[] = base64_encode($encrypted); // Encode in base64 again
}
print_r($result);
The uniqueness of the request

Each request must be accompanied by passing a Request-Id parameter in Headers.

It is recommended to use Uuid V4 in order to exclude intersections with other requests.

If the service receives a second request with the Request-Id that was received earlier, an error will be returned.
Card tokenization

Card tokenization for further payment.
Request example:
{
    "type": "bank_card",
    "options": {
        "card_number": "4405645000001234",
        "card_holder_name": "NAME",
        "card_exp_month": "02",
        "card_exp_year": "25"
    }
}
Field nameField typeDescription
typestringThe type of data to be encrypted. Only bank_card is available now
optionsobjectAn object containing information about the card
options.card_numberstringCard number
options.card_holder_namestringCardholder name
options.card_exp_monthstringCard expiration month
options.card_exp_yearstringCard expiration year
Пример ответа:
{
    "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"
    }
}
Field nameField typeDescription
statusstringProcessing status. It can be success or error
data.tokenstringThe result of data tokenization. It is used later for making payments.
Request URL

POST https://api.freedompay.kz/v5/sdk/tokenize

Headers
Content-TypeValue
Request-Id{{request_id}}
Content-Typeapplication/json
Making a payment

Request to make a payment using a previously tokenized card.
Request example:
{
  "order_id": "my-order",
  "auto_clearing": 1,
  "amount": 20,
  "currency": "KZT",
  "description": "Order 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
    }
  }
}
Field nameField typeDescription
order_idstringA unique order number in the merchant's system
auto_clearingint1 - if clearing is required automatically, 0 - if the merchant calls the clearing method himself/herself
amountfloatAmount of payment
currencystringPayment currency
descriptionstringPayment description
testint1 - if test payment mode, 0- if combat
options.custom_paramsobjectExtra options. Will be sent back to the merchant on the ResultURL after the payment is made.
user.email stringClient Email
user.phonestringClient phone number
transaction.typestringType of transmitted data to write off. Currently supports bank_card
transaction.options.tokenstringTokenized card
transaction.options.card_cvvstringCVV/CVC cards
Response example:
{
    "status": "success",
    "data": {
        "3ds": {
            "acsurl": "some_asc_url",
            "frame_url": "",
            "md": "MD",
            "pareq": "PaReq",
            "version": 1
        },
        "payment_id": "97397805",
        "payment_status": "need_confirm"
    }
}
Field nameField typeDescription
statusstring Processing status. It can be success or error
data.3ds.acsurlstringLink for redirecting the client if the merchant conducts 3DS himself/herself.
data.3ds.frame_urlstringRedirect link if 3DS is hosted using the JS SDK.
data.3ds.mdstringMD parameter
data.3ds.pareqstringPaReq parameter
data.3ds.versionint3DS version
data.payment_idstring Payment ID in the FreedomPay system
data.payment_statusstringPayment status
If the merchant conducts the 3DS himself/herself, you need to send the client to AcsUrl using the POST method. In addition to the MD and PaReq parameters, it is required to pass TermUrl. The client will return to this TermUrl after passing 3ds with MD and PaRes parameters.
Sample form for client forwarding:
<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>
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Content-TypeValue
Request-Id{{request_id}}
Content-Typeapplication/json
Request for ACS Url

The method can be used in case of passing 3DS without JS SDK. After the client has returned to TermUrl with the MD and PaRes parameters, you need to call the current method.
Request example:
{
    "payment_id": 0,
    "pares": "string",
    "md": "string"
}
Field nameField typeDescription
payment_idintPayment ID in the FreedomPay system
paresstringPaRes parameter
mdstringMD parameter
Response еxample:
{
    "status": "success",
    "data": {
        "auth_code": "123456",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
Field nameField typeDescription
statusstringProcessing status. It can be success or error
data.auth_codestringBank payment authorization code
data.payment_idstringPayment ID in the FreedomPay system
data.payment_statusstringPayment status
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Content-TypeValue
Request-Id{{request_id}}
Content-Typeapplication/json
Checking payment status

It is recommended to check the status of each payment after it is made.
Request example:
{
  "order_id": "merchant_order_id",
  "payment_id": 123456
}
Field nameField typeDescription
order_idstringPayment number in the merchant system. Required if not passed in payment_id
payment_idintPayment ID in the FreedomPay system. Required if not passed in order_id
Response еxample:
{
    "status": "success",
    "data": {
        "order_id": "merchant_order_id",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
Field nameField typeDescription
statusstringProcessing status. It can be success or error
data.order_idstringPayment number in the merchant system.
data.payment_idstringPayment ID in the FreedomPay system
data.payment_statusstringPayment status
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Content-TypeValue
Request-Id{{request_id}}
Content-Typeapplication/json
Reference books

Payment statuses
MeaningDescription
successPayment successfully completed
need_confirmPayment confirmation required. For example, in the case of passing 3DS
errorError making a payment
processPayment in the process
Error codes
Код ошибкиОписание ошибки
9992Вызываемый метод не активирован для магазина.
9993Не найден/не указан success/error/post-link URL.
9994Запрошенное действие отключено в настройках магазина
9995Платеж в тестовом режиме
9996Отсутствует или не действует контракт с магазином
9997Неверный номер магазина
9998Некорректная подпись запроса
9999Ошибка системы
10000Ошибка оплаты. Сервис недоступен. Повторите попытку позже.
10001Ошибка оплаты. Обратитесь в банк выпустивший карту
10003Превышено число попыток ввода проверочного кода
100043DSecure не введен или введен некорректно
10005Неверно указаны карточные данные
10006Превышен лимит частоты оплат
10007Отказано по причине нарушения безопасности карточных данных.
10008Неверно введены данные карты. Попробуйте повторить оплату.
10009Недостаточно средств
10010Ограничения на карте. Свяжитесь с банком выпустившим карту
10011Платеж успешно завершен
10012Невозможно отменить транзакцию. Обратитесь в магазин
10013Карта данной страны не разрешена для проведения транзакции
10014Превышен временной интервал. Свяжитесь с магазином
10015Ошибка оплаты. Транзакция уже совершена
10016Ошибка проведения оплаты. Обратитесь в службу поддержки сайта.
1001Срок действия карты истек.Просим оплатить с другой карты
10018Время жизни платежа истекло, необходимо создать новый
10019Операция не выполнена. Попробуйте использовать другую карту
10020Сумма возврата превышает сумму оплаты. Обратитесь в магазин
10021Недействительная транзакция - повторить попытку
10025Ошибка на стороне Международной Платежной системы
10026Ошибка выплаты. Обратитесь в Магазин
10028Превышен лимит по частоте оплаты. Свяжитесь с магазином
10029В данный момент выплаты на IBAN не работают
10030Ошибка минимальной суммы. Просим обратиться в Магазин
10031Некорректный номер телефона
10032Неправильный/несуществующий номер карты
11000Ошибка оплаты, сервис недоступен. Обратитесь в Службу поддержки
11001Операция неуспешна. Обратитесь в службу поддержки оператора.
11002Введен неверный код SMS. Повторите еще раз
11003На балансе Вашего номера образовалась задолженность
11004Введен неверный или несуществующий номер
11005Сумма введена некорректно
11006Недостаточно средств для проведения операции
11007Вы достигли лимита количества попыток кода подтверждения.
11008Срок действия кода подтверждения истек. Повторите операцию
11009Операция отклонена. Обратитесь в службу поддержки оператора
11010Вы превысили количество неуспешных попыток ввода SMS
11011Операция неуспешна, на номере имеются ограничения
11012Вы достигли лимита на количество платежей в сутки.
11013Операция неуспешна. Вы пытаетесь повторно провести операцию
11014Непредвиденная ошибка. Попробуйте позднее
11015Вы превысили единовременный лимит в размере 50МРП
11016Минимальная сумма платежа 1000тг
11017Платеж уже отменен
11018Платеж уже возвращен
11019Вы превысили месячный лимит в размере 1000МРП
11020Дневной лимит по количеству плажетей составляет 30 платежей
12000Ошибка ЦУС
10033Ошибка отмены платежа, отмена уже была проведена ранее.
10034Ошибка возврата платежа, по платежу необходимо провести клиринг
10035Ошибка платежа, не успешные платежи не могут пройти клиринг
10036Ошибка клиринга платежа, клиринг уже был проведен ранее
10022Сумма превышает допустимый лимит на карте.
10037Карта временно заблокирована, обратитесь в банк
99999Неизвестная ошибка платежной системы
11021Не удалось определить оператора или номер введён некорректно
11022Параметры платежа нарушают ограничения.
11023Платежи с номеров этого мобильного оператора не разрешены.
10038Карта заблокирована и подлежит удержанию, обратитесь в банк
10039Некорректная операция, обратитесь в банк
10040Неверный номер счета/карты, обратитесь в банк
10041Счет/карта закрыта, обратитесь в банк
9013Ошибка отмены платежа, не успешные платежи нельзя отменить.
10023Превышено количество попыток ввода PIN-кода
10024Неподтвержденный PIN, обратитесь в банк
11024Отказано по причине нарушения безопасности. Обратитесь в банк
11026По платежу имеется ChargeBack. Возврат невозможен.
11025Необходимо провести клиринг для возврата, или отменить платеж.
11027Ошибка оплаты. Географические ограничения по банковской карте.
11028Карта временно заблокирована. Повторите запрос после 30 дней.
11036Карта заблокирована на 30 дней, воспользуйтесь другой картой.
11049Код подтверждения 3DS не введен
110373DSecure не введен
11050Не пройдена проверка кода PIN владельца карты в системе VISA.
11051Блокировка по лимиту
11052Общая ошибка
11053Банк-эмитент не смог провести авторизацию 3dsecure-карты
8888Недостаточно средств! Пополните выплатной баланс
8889Ошибка прохождения 3D-Secure
11054С момента проведения данной транзакции прошло более 180 дней.
9991Неуникальный идентификатор заказа
11030Абоненту необходимо пройти идентификацию
11031Максимальная сумма платежа 15000 сом
11032Минимальная сумма платежа 5 сом
9990Карта уже сохранена. Введите другую карту на предыдущем шаге
9909Транзакция не найдена
9403Неверная валидация
9908Платеж с данным order_id уже существует
10042Карта не поддерживает 3DS. Обратитесь в банк выпустивший карту
125Карта неактивная или заблокированная
400Некорректно набирает ОТП код
9901Срок действия карты закончился
9073Выберите другой метод платежа, либо обратитесь в магазин
11055Попробуйте другую карту. Ошибка карты или есть гео-ограничения
9090Сумма выплаты превышает предельную (требуется идентификация)
11089Карты данной платёжной системы не поддерживаются
11085Требуется заполнить схему pg_split_refunds
11086Не установлены параметры сплитования
11076Неверный id продавца или продавец заблокирован
11064Неверный ИИН/БИН
11062Неверный номер карты отправителя
11063Неверный номер карты получателя
11069Неверный статус платежа
11067Неверный тип запроса
11065Некорректный CVC/CVV
11066Некорректный XML
11071Неправильный идентификатор первого платежа
11070Неправильный идентификатор реккурентного платежа
11084Сумма возврата не равна сумме частичных возвратов
11072Ошибка отмены платежа, был проведен клиринг
11080Параметр pg_split_refunds заполнен для несплитованного платежа
11068Платеж не найден
11079Необходимо прислать скорректированную схему сплитования
11082Сумма возврата позиции слишком большая
11078Сумма не должна превышать сумму платежа минус комиссия
11083Сумма возмещения позиции слишком большая
11077Сумма оплат покупателем по всем позициям не равна сумме платежа
11081Указан неверный идентификатор позиции
11087Заявка аннулирована провайдером
11061Неверный номер/идентификатор платежа
11088Отказ со стороны банка провайдера
11074Ошибка клиринга платежа, сумма для клиринга превышена
11060Ошибка настройки магазина, обратитесь в поддержку
10043По карте не подключено SMS-информирование. Обратитесь в банк.
10040Вы не можете установить скидку на комиссию
10041Вы должны выбрать один тип скидки
10042Вы должны выбрать тип скидки
11090Ошибка клиринга платежа, платеж был ранее отменен.
9102Ошибка возврата платежа, возврат находится в процессе выполнения
9103Ошибка отмены платежа, отмена находится в процессе выполнения
9043Ошибка файла конфигурации терминала платежной системы.
100066Превышен лимит частоты операций
10089Выплата на указанную карту в указанной валюте недоступна.
10088Перевод с указанной карты и в указанной валюте недоступен.