В стиле ePay

Этот раздел полезен для участников ProstoPlateg.kz. Если вы еще не с нами — имеет смысл зарегистрироваться. Понятно

Использование протокола ePay для передачи команд на онлайн-оплату

ePay

Если на вашем сайте уже реализован прием оплаты через ePay «Казкоммерцбанка» — мы предлагаем вам сэкономить время и подключить ProstoPlateg.kz через передачу команд в формате протокола ePay.

Пример ниже реализован на стандартном рабочем скрипте ePay. Он написан на PHP. Если ваш сайт использует другой язык — далее мы объясним, как изменить ваш код, чтобы все заработало.

Как подключить платежный шлюз по протоколу ePay решение для PHP

Скачайте необходимые PHP-скрипты и включите их в свой код. Удобнее всего это сделать, добавив скрипты в файл kkb.utils.php из типовой поставки ePay.

Для подключения сделайте следующее:

  1. Найдите в БД вашего сайта таблицу, которая обслуживает платежи ePay. Скопируйте её структуру в другую новую таблицу (давайте назовем её paypp).

    Новая таблица нужна, чтобы платежи, проводимые через ProstoPlateg.kz, учитывались отдельно. (При желании достаточно добавить флаг, отделяющий платежи ePay от других, в существующей таблице.)

  2. Сделайте копию скрипта, который реализует старт оплаты по ePay. В стандартной поставке скриптов ePay есть файл kkb.utils.php, в котором для старта оплаты используется функция process_request(). В примере эта функция выглядит так:

    $content = process_request($order_id,$currency_id,$amount,$path1);

    Если вы включили в код своих скриптов аналогичную функцию из нашего пакета — замените эту строку такой:

    $content = process_requestPP($order_id,$currency_id,$amount,$path1);

    Замените в этом скрипте имя таблицы баз данных на созданное вами в пункте 1.

  3. Сделайте копию скрипта, который реализует прием результата оплаты по ePay. В стандартной поставке скриптов ePay есть файл kkb.utils.php, в котором для начала оплаты используется функция process_responsePP(), в примере эта функция выглядит так:

    $result = process_response(stripslashes($response),$path1);

    Если вы включили в текст своих скриптов аналогичную функцию из нашего пакета — указанную выше строку надо заменить на:

    $result = process_responsePP(stripslashes($response),$path1);

    И опять: замените в этом скрипте имя таблицы баз данных на созданное вами в пункте 1.

  4. Сделайте копию скрипта, на который ваш клиент возвращается после оплаты на ePay.

    Здесь тоже замените в этом скрипте имя таблицы баз данных на созданное вами в пункте 1.

  5. Создайте скрипт со своими уникальными параметрами, которые будут использоваться в транзакциях: номером мерчанта и секретным ключом. Вы получили их при регистрации в системе ProstoPlateg.kz, они доступны в вашем кабинете. Эти константы надо записать в PHP-файл (пусть будет PPinfo.php):

    <?
    $PP_merchant_info = 2; // номер мерчанта, полученный при регистрации
    $PP_secretcode = "JDieEJ3SKDjhn4hDDyr4swEe"; // секретное слова для подписи транзакций.
    ?>

    После этого пропишите переменную $path1 как $path="PPinfo.php". Эта переменная используется в пунктах 3 и 4.

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

    В оригинале HTML-код формы оплаты выглядит примерно так:

    <form name="SendOrder" method="post" action="https://epay.kkb.kz/jsp/process/logon.jsp">
    	<input type="hidden" name="Signed_Order_B64" value="PGRvY3VtZW50PjxtZXJjaGFudCBjZXJ0X2lkPSIwMEMxODJCMTg5IiBuYW1lPSJzaG9wLnByb3N0b3BsYXRlZy5reiI+PG9yZGVyIG9yZGVyX2lkPSIwMDA0NjIiIGFtb3VudD0iMTAiIGN1cnJlbmN5PSIzOTgiPjxkZXBhcnRtZW50IG1lcmNoYW50X2lkPSI5MjA2MTEwMSIgYW1vdW50PSIxMCIvPjwvb3JkZXI+PC9tZXJjaGFudD48bWVyY2hhbnRfc2lnbiB0eXBlPSJSU0EiPnFhT3NKVzNIcXE4YnFzT1Jzc00rK2VFbGZ6NlhjNEp3SnpmOEVZN3BNZS92bUwrdWVnU0xKT0szcThBdVpMT1JocGl2L0FvdE5Db1NmQ0VUY1FGd2RnPT08L21lcmNoYW50X3NpZ24+PC9kb2N1bWVudD4=">
    	<input type="hidden" name="Language" value="rus">
    	<!-- язык формы оплаты rus/eng -->
    	<input type="hidden" name="BackLink" value="http://www.bl.test.kz/">
    	<input type="hidden" name="PostLink" value="http://www.pl.tes.kz/post_link.php">
    	Со счетом согласен(-а)
    	<br>
    	<input type="submit" name="GotoPay" value="Да, перейти к оплате">
    </form>

    Первую строку формы необходимо заменить на следующую:

    <form name="SendOrder" method="post" action="https://prostoplateg.kz/salekz.php">

    Для возврата пользователя и результата оплаты на ваш сервер вам надо сделать изменения параметров BackLink и PostLink:

    <input type="hidden" name="BackLink" value="http://www.bl.test.kz/">
    <input type="hidden" name="PostLink" value="http://www.pl.test.kz/post_link.php">

    …прописав там имена скриптов, которые вы создали в пунктах 3 и 4.

На этом настройка системы на прием команд на оплату онлайн интернет-платежей с использованием протокола ePay закончен.

Дополнительные программные плюшки

Если вы, как программист, хотите повысить управляемость протокола ProstoPlateg.kz в существующих рамках протокола ePay — для удобного приема онлайн-платежей можно внедрить ряд дополнений.

  1. Использование переменной $currency_code в функции process_responsePP() в качестве параметра передачи типа платежа из перечня типов платежей, описанных в листинге типов оплат ProstoPlateg.kz.

    По умолчанию в этом параметре используется код валюты тенге 398. Если вы оставите его — при переходе к оплате система ProstoPlateg.kz уточнит у покупателя, в какой валюте он хочет оплатить свою покупку. Если вы укажете валюту из списка — система не будет делать дополнительный запрос.

  2. Передавать команды шлюза ProstoPlateg.kz по протоколу ePay вы можете гораздо гибче, если начнете использовать глобальные переменные, описанные как global в теле функции process_responsePP() из набора наших скриптов:

    global $PAYMENT_INFO, $PAYMENT_DELIVER, $PAYMENT_ADDVALUE, $PAYMENT_RULE, PAYMENT_TESTMODE;

    Назначение этих переменных объяснено в документации протокола приема онлайн-платежей ProstoPlateg.kz. Наиболее удобным является инициализация переменной $PAYMENT_INFO, которая описывает содержимое оплачиваемого.

Как подключить платежный шлюз по протоколу ePay решение для разных языков программирования

Если вы не используете PHP в своей системе — ниже объясняется, как работает механизм трансляции команд ePay в команды ProstoPlateg.kz

При передаче данных в систему ePay фактически используется только две переменные: $order_id (номер заказа) и $amount (сумма оплаты). По ним идет идентификация заказа интернет-магазина как в самом магазине, так и в системе ProstoPlateg.kz, переменная $currency_code всегда принимает значение 398.

Для приема платежей система создает XML-код, который на выходе base64-кодируется; полученный результат отправляется методом POST на URL платежного шлюза ePay через переменную Signed_Order_B64.

Трансляция заключается в передаче на платежный URL системы ProstoPlateg.kz данных в xml-формате, который основан на всё тех же двух переменных $order_id (номер заказа) и $amount (сумма оплаты), но понятен системе ProstoPlateg.kz.

Формирование делается следующим образом:

  1. Сначала создадим простой XML-код:

    <?xml version="1.0" encoding="UTF-8"?>
    <MAIN>
    	<PAYMENT_AMOUNT>$PAYMENT_AMOUNT</PAYMENT_AMOUNT>
    	<PAYMENT_INFO>$PAYMENT_INFO</PAYMENT_INFO>
    	<PAYMENT_DELIVER>$PAYMENT_DELIVER</PAYMENT_DELIVER>
    	<PAYMENT_ADDVALUE>$PAYMENT_ADDVALUE</PAYMENT_ADDVALUE>
    	<PAYMENT_ORDER>$order_id</PAYMENT_ORDER>
    	<PAYMENT_TYPE>$currency_code</PAYMENT_TYPE>
    	<PAYMENT_RULE>$PAYMENT_RULE</PAYMENT_RULE>
    	<PAYMENT_TESTMODE></PAYMENT_TESTMODE>
    </MAIN>

    …где $PAYMENT_AMOUNT — это $amount*100 — сумма в тиынах — целое число, остальные переменные соответствуют переменным из протокола ProstoPlateg.kz.

  2. Этот xml-код поместим в переменную $oper и применим к ней base64-кодирование:

    $oper = base64_encode($oper);
  3. Потом определим переменную $sign. Она получается при вычислении MD5-хэша для текстовой строки, которая, в свою очередь, является результатом склеивания переменной $oper и $PP_secretcode (секретного слова, которое было сгенерировано при регистрации магазина).

    $sign = md5($oper.$PP_secretcode);
  4. Полученные результат мы используем для формирования XML-команды:

    <?xml version="1.0" encoding="UTF-8"?>
    <content>
    	<gate>1</gate>
    	<MERCHANT_INFO>$PP_merchant_info</MERCHANT_INFO>
    	<oper>$oper</oper>
    	<sign>$sign</sign>
    </content>

    …где

    • 1 — константа, обозначающая механизм трансляции ePay;
    • $PP_merchant_info — номер магазина, который был выдан при регистрации в системе ProstoPlateg.kz;
    • $oper — base64-кодированное содержимое XML-кода;
    • $sign — вычисленный MD5-хэш.
  5. К получившейся XML-команде применяем base64-кодирование и полученный результат является результатом HTML-переменной Signed_Order_B64, которая передается в платежной форме на сервер.

Если вы хотите сделать интерфейс более гибким — вам достаточно реализовать советы из раздела «Дополнительные программные плюшки».