Отправка платежа через API


На шаге 2 запрос коммерсанта должен быть в отправлен в eCom методом POST на адрес https://jpay.jysanbank.kz/ecom/api.

Параметры запроса на шаге 2:
Наименование Обязательность Формат Описание
ORDER Да N(6 - 10) Номер заказа, должен быть уникальным для этого коммерсанта
AMOUNT Да N(1 - 13) Сумма заказа, разделитель - точка
CURRENCY Да C(3) Валюта заказа (ISO 4217, например KZT)
MERCHANT Да C(6 - 15) Идентификатор коммерсанта
TERMINAL Да C(6 - 8) Идентификатор терминала
NONCE Нет N(6 – 64) Случайное уникальное число
LANGUAGE Нет С(2) Предпочтительный язык клиента, поддерживаются значения «ru» и «en»
CLIENT_ID Нет N(0 – 64) Идентификатор аутентифицированного клиента
DESC Да C(1 – 50) Краткое описание заказа
DESC_ORDER Нет C(0 – 4000) Полное описание заказа
EMAIL Нет C(0 – 80) Адрес Email клиента
BACKREF Нет C(0 – 250) Ссылка для отправки результата по заказу
Ucaf_Flag Нет C(0 – 250) Зарезервировано для данных UCAF
Ucaf_Authentication_Data Нет C(0 – 250) Зарезервировано для данных UCAF
crd_pan Нет C(250) Номер карты в зашифрованном виде
crd_exp Нет C(250) Дата устаревания карты в формате MM/YY в зашифрованном виде
crd_cvc Нет C(250) CVV/CVC/CVC2 карты в зашифрованном виде
P_SIGN Да C(80 - 250) Подпись заказа

Алгоритм формирования подписи в поле P_SIGN следующий: нужно собрать в одну строку значения полей заказа (без LANGUAGE!) через разделитель «;», затем добавить эту строку к значению секретного ключа SHARED_SECRET (этот ключ индивидуальный для каждого коммерсанта), и вычислить из полученной строки значение хэш SHA512. В строках DESC, DESC_ORDER перед обработкой нужно убрать все переносы строк. Например, на PHP это будет выглядеть так:

vSign=hash("sha512",C_SHARED_KEY.$_POST["ORDER"].";".$_POST["AMOUNT"].";".$_POST["CURRENCY"].";".$_POST["MERCHANT"].";".$_POST["TERMINAL"].";".$_POST["NONCE"].";"
.$_POST["CLIENT_ID"].";".preg_replace("/\n|\r/g","",$_POST["DESC"]).";".preg_replace("/\n|\r/g","",$_POST["DESC_ORDER"]).";".$_POST["EMAIL"].";".$_POST["BACKREF"].";"
.$_POST["Ucaf_Flag"].";".$_POST["Ucaf_Authentication_Data"].";");

Пример вычисления (на JS) есть на странице примера https://ecom.jysanbank.kz:8462/ecom/static/e/test.html.

Обратите внимание! В продуктовой системе хэш должен вычисляться не в браузере на стороне клиента, а в процедуре на стороне web-сервера коммерсанта!

Пример на странице test.html – только для тестирования.

Секретный ключ SHARED_SECRET ни в коем случае не должен быть доступен кому-либо вне Вашего сервера!


Ввод реквизитов карты на сайте коммерсанта

Платежную страницу можно также выводить на сайте коммерсанта. В этом случае необходимо шифровать реквизиты платежной карты публичным ключем RSA банка на веб-странице перед передачей данных на сайт коммерсанта. На сайте коммерсанта данные подписываются SHA512 с помощью SHARED_SECRET (к строке данных при этом добавляются значения crd_pan, crd_exp, crd_cvc - зашифрованные реквизиты платежной карты), затем данные и подпись отправляются в ecom методом POST на адрес https://jpay.jysanbank.kz/ecom/api.

В случае ввода параметров оплаты на сайте коммерсанта, имеет смысл использовать возможность «Перенаправление результата на страницу коммерсанта», т.е. добавить redirect=true в значение параметра BACKREF.

Пример шифрования и вычисления подписи можно посмотреть на странице примера https://ecom.jysanbank.kz:8462/ecom/static/e/test_crd.html.

В случае ввода реквизитов платежной карты на сайте коммерсанта, весь сайт коммерсанта считается влияющим на безопасность карточных данных, и согласно PCI DSS к сайту применяются следующие требования:

  • работа только по HTTPS с валидным SSL сертификатом
  • заполнить лист самооценки SAQ-EP
  • ежеквартально проходить ASV тестирование (автоматизированную проверку сайта на наличие уязвимостей)

Шифрование данных карты должно производиться на web-странице клиента, до подписывания данных секретным ключем!

Подписание данных секретным ключем SHARED_KEY должно производиться на сервере коммерсанта!


Платежный виджет на сайте коммерсанта

Платежную страницу на сайте коммерсанта можно вывести в виде виджета, например в виде диалога:

или в указанном месте на странице сайта коммерсанта:

Платежная страница банка выводится в iframe, параметры заказа могут передаваться POST или GET методом. Значения параметров должны быть подписаны SHA512, так же как в обычном вызове (см. выше). Подпись должна формироваться на бэк-стороне сайта коммерсанта.

Примерная последовательность процесса оплаты следующая:

  • клиент выбирает товары/услуги
  • клиент переходит на страницу оплаты сайта коммерсанта, при этом параметры заказа проверяются на сайте коммерсанта и подписываются
  • на странице сайта коммерсанта выводится платежная страница банка в iframe, параметры заказа и подпись передаются в параметрах вызова

Пример вывода виджета можно посмотреть на тестовой странице:

https://ecom.jysabank.kz:8462/ecom/static/e/test_widget.html

Из iframe виджета на родительскую страницу высылается window.postMessage c результом. Значение targetOrigin берется из указанного адреса сайта коммерсанта в параметре BACKREF или в поле “URL отправки ответа”.


Возможные ошибки при отправке платежа


Код Описание (ru) Описание (en)
11 Сервис временно недоступен, попробуйте позже Service temporary unavailable, try again later
12 Неправильное значение в поле ORDER: %s Order number is invalid: %s
13 Неправильная сумма: %s Amount is invalid: %s
14 Неправильная валюта: %s Currency is invalid: %s
15 Сервис MPI временно недоступен, попробуйте позже MPI service temporary unavailable, try again later
16 Сервис Db временно недоступен, попробуйте позже Db service temporary unavailable, try again later
17 Неправильное значение в поле MERCHANT: %s Merchant is invalid: %s
18 Запрос ORDER=%s уже выполнялся Request of ORDER=%s is already in progress
19 Неправильная дата дейстия карты (MM/ГГ) : %s Card exp date (MM/YY) is invalid: %s
20 Неправильное значение в поле TERMINAL : %s Terminal is invalid: %s
21 Неправильная подпись! Signature is invalid!
22 Не найден курс валюты %s The rate of currency %s is not found
23 Превышен лимит! %s Limit exeeded! %s
24 Не указано значение в поле "%s". The value of field "%s" is required.
25 Размер значения в поле "%s" менее %d симоволов. The size of value of the field "%s" less then %d symbols.
26 Размер значения в поле "%s" больше %d симоволов. The size of value of the field "%s" more then %d symbols.
27 Введите валидное значение в поле "%s". Enter a valid value of field "%s".
28 Ошибка MPI при выполнении проверки 3DS: %s MPI returns error: %s
29 Недопустимый тип карты Invalid card type
99 Другая ошибка : %s Other error: %s/td>