Подключение

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

ProstoPlateg.kz: руководство для программистов

Инструкция по настройке платежного шлюза ProstoPlateg

Этот раздел предназначен для программистов, которым необходимо реализовать взаимодействие с системой приема платежей ProstoPlateg.kz.

Быстрые способы подключения

Подключение по уже существующим протоколам

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

Подключение по протоколам ProstoPlateg.kz

  1. подключение по экспресс-методу — этот тип подключения предполагает минимальное вмешательство в структуру интернет-магазина и реализует все взаимодействие с клиентом на стороне нашего платежного сервера.
  2. полнофункциональная реализация с системой приема платежей — представлена ниже.

Готовые скрипты для работы с ProstoPlateg.kz

Готовые скрипты для подключения нашего платежного решения написаны на языке PHP и обеспечивают интеграцию функций платежей в любой системе.

Содержание раздела

  1. Общее описание системы
  2. Входные параметры
  3. Выходные параметры
  4. Использование UTF-8 и XML при подаче запроса на оплату
  5. Рекурсивные (рекуррентные) платежи

Общее описание системы

При подключении интернет-ресурса (ИР) к платежному движку вы получаете доступ в административную систему — личный кабинет.

Личный кабинет позволяет

  • проверять баланс выручки от текущих продаж;
  • формировать отчет о продажах за период;
  • настраивать удержание комиссий при совершении клиентом ИР платежей в пользу ИР;
  • экспортировать отчеты в CSV- и DBF-форматах в любую бухгалтерскую систему;
  • автоматически подключать магазины на платформе Satu.kz к нашему платежному движку.

Владелец ИР может настроить списание комиссии за услуги нашего сервиса двумя способами — за счет магазина и за счет покупателя. В случае выбора за счет магазина комиссия за услуги нашего сервиса будет удержана из оплаты, которая поступает в адрес ИР. В случае выбора за счет покупателя торговая точка получит ровно ту сумму тенге, которая была отправлена в платежный интерфейс, а конечная сумма оплаты для покупателя будет увеличена на сумму комиссии магазина в выбранной валюте электронной платежной системы.

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

Обе схемы работы выгодны покупателю: допустим, он хочет оплатить ваш товар по безналу или наличкой, т.е. ровно на 20 000 тенге, а у него есть виртуальная валюта. Чтобы поменять виртуальные единицы платежной системы на «живые» тенге — затраты на такой обмен будут равнозначны или больше, чем сумма к оплате, при этом покупателю необходимо будет сделать несколько шагов и это займет 1–2 рабочих дня, что весьма неудобно. И пользователю выгоднее сделать покупку в интернет-магазине, чем менять виртуальную валюту на тенге и делать покупку.

Процесс покупки

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

Кодировка полей

По умолчанию кодировка полей воспринимается как windows-1251. Если сайт ИР работает в кодировке UTF-8 — в Разделе 3 описан метод отсылки данных в систему с использованием UTF-8.

К содержанию

Входные параметры

Входные параметры передаются методом POST в платежный интерфейс системы на платежный URL https://balance.prostoplateg.kz/sale.php.

  • PAYMENT_AMOUNT — сумма оплачиваемых товаров в тиынах, целое число больше нуля.
  • PAYMENT_INFO — информация о товаре, 255 символов.
  • PAYMENT_DELIVER — информация о доставке, 255 символов.
  • PAYMENT_ADDVALUE — дополнительная информация клиента (для передачи каких-либо параметров торговой точки), 255 символов.
  • MERCHANT_INFO — уникальный номер торговой точки в нашей системе (целое положительное число).
  • PAYMENT_ORDER — уникальный номер заказа в системе торговой точки, проверяется системой на уникальность — в случае поступления заказа на оплату с уже существующим оплаченным номером — система не примет заказ, выдаст ошибку.
  • PAYMENT_TYPE — тип валюты, который используется при оплате:
    • 27 — EKZT;
    • 31 — termkz (Касса24, Qiwi);
    • 26 — WMK;
    • 1 — WMZ;
    • 2 — WMR;
    • 3 — WMU4
    • 5 — Яндекс.Деньги;
    • 33 — Visa/Master
  • PAYMENT_RULE — указание, на чей счет будет отнесена комиссия по транзакции:
    • 1 — за счет интернет-магазина;
    • 2 — за счет клиента;
    • если параметр не определен — по умолчанию используются настройки из административного интерфейса (на текущий момент всё за счет клиента).
  • PAYMENT_VISA — зарезервирован для параметров оплат картами Visa/MasterCard в случае пользования нашим интерфейсом.
  • PAYMENT_RETURNRES — полный URL, на который будет возвращен результат транзакции.
  • PAYMENT_RETURN — полный URL, на который будет возвращен клиент после оплаты в случае успешной оплаты.
  • PAYMENT_RETURNMET — метод, который будет использован для возврата результата на URL возврата результата:
    • 1 — GET;
    • 2 — POST;
    • если параметр не указан — возвращаться будет методом POST.
  • PAYMENT_RETURNFAIL — полный URL, на который будет возвращен клиент после оплаты в случае неудачной оплаты.
  • PAYMENT_TESTMODE — признак режима тестирования:
    • 0 — режим нормальной работы;
    • 1 — режим тестирования.
  • PAYMENT_HASH — MD5-хэш для цифровой подписи параметров. Формируется строкой из параметров, разделенных знаком : (двоеточием).

Подробнее о PAYMENT_HASH

Из чего он состоит:

$MERCHANT_INFO:$PAYMENT_TYPE:$PAYMENT_RULE:$PAYMENT_AMOUNT:$PAYMENT_ADDVALUE:$PAYMENT_INFO:$PAYMENT_DELIVER:$PAYMENT_ORDER:$PAYMENT_VISA:$PAYMENT_TESTMODE:$PAYMENT_RETURNRES:$PAYMENT_RETURN:$ PAYMENT_RETURNMET:$SECRETCODE

Последний параметр $SECRETCODE — это строка-пароль, который известен только торговой точке и платежному шлюзу.

Т.е. в параметрах php это выглядит так:

md5("$MERCHANT_INFO:$PAYMENT_TYPE:$PAYMENT_RULE:$PAYMENT_AMOUNT:$PAYMENT_ADDVALUE:$PAYMENT_INFO:$PAYMENT_DELIVER:$PAYMENT_ORDER:$PAYMENT_VISA:$PAYMENT_TESTMODE:$PAYMENT_RETURNRES:$PAYMENT_RETURN:$PAYMENT_RETURNMET:$SECRETCODE");

Пример такой строки:

3:1:1:4500:da5cae4c3f8333e54b26cbf3be57cd18:Регистрация домена:Система оплаты счетов ProHosting.ua:91::0:http://prohosting.ua/cgi-bin/billing/moneyuares.php:http://prohosting.ua/cgi-bin/billing/moneyuaret.php:2:test7

Silent-метод

Выше приведен обычный метод входа на платежный шлюз. Для крупных интернет-магазинов возможен silent-режим работы платежного шлюза. В этом режиме, помимо обычных данных, в выходной поток добавляются форматированные. XML-код имеет следующие параметры:

<UASILENT>
	<UAHIDDENS>Набор параметров формы, которая направит покупателя в платежный шлюз выбранной системы</UAHIDDENS>
	<UAAMOUNTUAH>Сумма платежа в тенге</UAAMOUNTUAH>
	<UAAMOUNTVAL>Сумма платежа в выбранном виде оплаты</UAAMOUNTVAL>
	<UANAMEVAL>Название вида оплаты</UANAMEVAL>
	<UASALEPOINT>Название магазина</UASALEPOINT>
	<UAOWNER>Владелец магазина</UAOWNER>
	<UAGOODSINFO>Информация о покупке</UAGOODSINFO>
	<UAGOODSDELIVER>deliver — информация о доставке товара</UAGOODSDELIVER>
</UASILENT>

Т.е. между <UASILENT> и </UASILENT> находится набор необходимых параметров.

Помимо этого выводится таблица со всеми этими значениями, уже отформатированная для вывода на экран, её XML-код расположен между тегами <UATOTAL> и </UATOTAL>.

Достаточно сделать запрос к странице платежного шлюза, получить XML-код и вывести его на экран, при необходимости отформатировав.

Как сделать такой вызов методом PHP

$params = 
	"PAYMENT_AMOUNT=$total&PAYMENT_INFO=$invoice_info&PAYMENT_DELIVER=$deliver&PAYMENT_ADDVALUE=$pass&MERCHANT_INFO=$merchant&PAYMENT_ORDER=$order&PAYMENT_TYPE=$type&PAYMENT_RULE=$comiss&PAYMENT_VISA=$visa&PAYMENT_RETURNRES=$urlresult&PAYMENT_RETURN=$urlreturn&PAYMENT_RETURNMET=$method&PAYMENT_RETURNFAIL=$urlfail&PAYMENT_TESTMODE=$testmode&PAYMENT_HASH=$hash";
$httpurl =
	"https://balance.prostoplateg.kz/sale.php";

// инициализация сеанса
$ch = curl_init();

// установка URL и других необходимых параметров
curl_setopt($ch, CURLOPT_URL, $httpurl);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS,$params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);

// выполнение запроса
$answer = curl_exec($ch);

// завершение сеанса и освобождение ресурсов
curl_close($ch);
echo $answer;

Т.е. в переменной $answer находится ответ платежного шлюза, который вы и выводите на экран своему покупателю.

К содержанию

Выходные параметры

Возврат информации торговой точке осуществляется на возвратный URL выбранным методом.

Возвращаемые параметры

  • RETURN_UNIQ_ID — уникальный номер транзакции в нашей системе.
  • RETURN_MERCHANT — номер торговой точки в нашей системе.
  • RETURN_ADDVALUE — возвратное значение PAYMENT_ADDVALUE.
  • RETURN_CLIENTORDER — возвратное значение PAYMENT_CLIENTORDER.
  • RETURN_AMOUNT — возвратное значение суммы заказа в тиынах.
  • RETURN_RESULT — результат транзакции:
    • 20 — положительный результат, транзакция успешна;
    • все остальные коды — неуспешные.
  • RETURN_COMISSION — сумма комиссии, которая была удержана с торговой точки по данной транзакции — выражена в тиынах; целое число.
  • TEST_MODE — признак режима тестирования:
    • 0 — режим нормальной работы;
    • 1 — режим тестирования.
  • PAYMENT_DATE — дата платежа в UNIX-формате.
  • RETURN_PMEMAIL — e-mail покупателя. Нужен при оплате через WebMoney чеком Paymer.
  • RETURN_TPHONE — номер телефона покупателя. Нужен для оплаты через WebMoney с мобильного телефона («Телепат»).
  • RETURN_COMMISSTYPE — признак, за чей счет была взята комиссия:
    • 1 — за счет фирмы;
    • 2 — за счет клиента.
  • RETURN_TYPE — каким методом была оплата:
    • 27 — EKZT;
    • 31 — termkz (Касса24, Qiwi);
    • 26 — WMK;
    • 1 — WMZ;
    • 2 — WMR;
    • 3 — WMU4
    • 5 — Яндекс.Деньги;
    • 33 — Visa/Master
  • RETURN_HASH — MD5-хэш для цифровой подписи выходных параметров. Формируется строкой из параметров, разделенных знаком : (двоеточием).
    $RETURN_MERCHANT:$RETURN_ADDVALUE:$RETURN_CLIENTORDER:$RETURN_AMOUNT:$RETURN_COMISSION:$RETURN_UNIQ_ID:$TEST_MODE:$PAYMENT_DATE:$SECRETCODE:$RETURN_RESULT

    Соответственно, если построенный хэш равен пришедшему RETURN_HASH — транзакция подлинна.

Когда ваш возвратный URL получит результат оплаты, ваш скрипт должен ответить шлюзу OK (две большие латинские буквы „O“ и „K“). После этого шлюз прекратит попытки отправить вам результат заново.

К содержанию

Использование UTF-8 при подаче запроса на оплату

При использовании кодировки UTF-8 как основной, на сайте магазина возникают ошибки при подсчете контрольной суммы хэша при перекодировании символов в кодировку windows-1251. Чтобы избежать таких проблем, используйте альтернативный формат запроса в систему.

Передавайте входные параметры методом POST в платежный интерфейс системы на платежный URL https://balance.prostoplateg.kz/sale.php.

Набор POST-переменных

  1. flagxml — обозначает, что используется метод подачи запроса через XML, должен быть равен 1.
  2. MERCHANT_INFO — уникальный номер торговой точки в нашей системе (целое положительное число).
  3. PAYMENT_HASH — MD5-хэш, который вычисляется путем слияния двух параметров strxml и SECRETCODE:
    $PAYMENT_HASH = md5($strxml.$SECRETCODE);
    где $SECRETCODE — это строка-пароль, который известен только торговой точке и платежному шлюзу.
  4. strxml — содержимое XML-запроса, которое является URL-кодированной строкой в соответствии с RFC 1738, после этого закодированной способом MIME Base64.

Формат XML-запроса

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<PAYMENT_AMOUNT></PAYMENT_AMOUNT>
	<PAYMENT_INFO></PAYMENT_INFO>
	<PAYMENT_DELIVER></PAYMENT_DELIVER>
	<PAYMENT_ADDVALUE></PAYMENT_ADDVALUE>
	<PAYMENT_ORDER></PAYMENT_ORDER>
	<PAYMENT_TYPE></PAYMENT_TYPE>
	<PAYMENT_RULE></PAYMENT_RULE>
	<PAYMENT_VISA></PAYMENT_VISA>
	<PAYMENT_RETURNRES></PAYMENT_RETURNRES>
	<PAYMENT_RETURN></PAYMENT_RETURN>
	<PAYMENT_RETURNMET></PAYMENT_RETURNMET>
	<PAYMENT_RETURNFAIL></PAYMENT_RETURNFAIL>
	<PAYMENT_TESTMODE></PAYMENT_TESTMODE>
</MAIN>

Если вы используете в полях запроса служебные символы, которые интерпретатором XML могут воспринимается двояко — обрамляйте такие значение специальными служебными символами: <![CDATA[ и ]]>.

После получения текста XML-запроса он URL-кодируется, после чего к полученной строке применяется MIME-кодирование:

$strxml=
	base64_encode(rawurlencode($strxml));

Полученный результат отправляется методом POST.

К содержанию

Рекурсивные (рекуррентные) платежи

Если интернет-магазину требуются регулярные платежи по карточкам его клиентов — в системе предусмотрен механизм снятия денег по запросу интернет-магазина.

Возможность основана на работе платежного шлюза «КазКоммерцбанка».

Для активации рекуррентного платежа при подаче запроса на оплату через шлюз «ККБ» необходимо добавить три поля:

<RECUR>
	<recur_freq></recur_freq>     <!-- минимальное количество дней между авторизациями, целое число -->
	<recur_exp></recur_exp>       <!-- срок действия регулярных платежей в формате YYYYMMDD (20160430) -->
	<person_id></person_id>       <!-- идентификатор абонента в системе интернет-магазина, целое число -->
	<person_email></person_email> <!-- e-mail абонента в системе интернет-магазина -->
	<recur_id></recur_id>         <!-- порядковый номер регистрации рекуррентного платежа в платежном шлюзе -->
</RECUR>

Если для рекуррентного платежа используется шлюз Processing.kz, то дополнительная секция будет выглядеть так:

<RECUR>
	<recur_id></recur_id>         <!-- порядковый номер регистрации рекуррентного платежа в платежном шлюзе -->
</RECUR>

Для создания рекуррентного платежа необходимо указать все три параметра. Если проводка пройдет удачно — дальнейшие рекуррентные платежи для абонента интернет-магазина будут активированы. Проверить, что для данного абонента установлены рекуррентные платежи, можно с помощью протокола управления рекуррентными платежами.

Если установка рекуррентного платежа успешна, то для последующего снятия денег с карты абонента достаточно подать обычный запрос на выполнения платежа, указав только поле <person_id></person_id>, остальные поля указывать не нужно. Если проводка была успешной — платежный движок вернет обычное сообщение о принятии платежа в пользу интернет-магазина без ввода пользователем каких-либо платежных данных.

Для управления рекуррентными платежами был создан протокол управления, основанный на XML аналогично основному протоколу использования XML-команд. В нашем случае параметры команды следующие.

Набор POST-переменных

  1. flagxml — обозначает, что используется метод подачи запроса через XML, должен быть равен 1.
  2. MERCHANT_INFO — уникальный номер торговой точки в нашей системе (целое положительное число).
  3. PAYMENT_HASH — MD5-хэш, который вычисляется путем слияния двух параметров strxml и SECRETCODE.
  4. xmlgate — должен быть равен 4.

Формат XML-запроса

Запрос общего списка всех действующих рекуррентных платежей

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<comm>list</comm>
</MAIN>

Ответ на команду:

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<list>
		<id></id>                  <!-- порядковый номер рекуррентного платежа -->
		<person_id></person_id>    <!-- номер абонента в системе интернет-магазина -->
		<freq></freq>              <!-- минимальное количество дней между авторизациями -->
		<expire></expire>          <!-- срок действия регулярных платежей в формате YYYYMMDD (20160430) -->
		<cardhash></cardhash>      <!-- хэш-код номера карты -->
	</list>
</MAIN>

Запрос на удаление установленного рекуррентого платежа по ID

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<comm>del</comm>
	<id></id>                     <!-- порядковый номер рекурренного платежа, который удаляется -->
</MAIN>

Ответ на команду:

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<del id="">OK</del>
</MAIN>

Запрос на создание рекуррентного платежа в шлюзе Processing.kz

<?xml version="1.0" encoding="UTF-8"?>
<MAIN>
	<comm>addhalyk</comm>
	<recur_freq></recur_freq>     <!-- минимальное количество дней между авторизациями, целое число -->
	<recur_exp></recur_exp>       <!-- срок действия регулярных платежей в формате YYYYMMDD (20160430) -->
	<person_id></person_id>       <!-- идентификатор абонента в системе интернет-магазина, целое число -->
	<person_email></person_email> <!-- email абонента в системе интернет-магазина -->
</MAIN>

К содержанию