Параметры интерфейса приема платежей

РАЗДЕЛ 0. Общее описание системы.

Как работает наша система общим языком:

При подключении интернет-магазина (ИМ) к платежному движку каждому ИМ предоставляется доступ в административную систему. Административная система позволяет:

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

Например, покупатель выбрал товар стоимостью 100 гривен и желает оплатить их через WMU. Если магазин отправляет в платежный движок оплату данного заказа с настройкой "за счет магазина" - клиенту будет выставлен счет на 100WMU, а после оплаты магазину на его счету в административной системе будет отражена проводка к выплате 96,50 грн - т.е. 100 грн. за вычетом комиссии 3,5%. Если магазин отправляет в платежный движок оплату данного заказа с настройкой "за счет покупателя" - клиенту будет выставлен счет на 103,50WMU, а после оплаты интернет-магазину на его счету в административной системе будет отражена проводка к выплате в 100 грн., т.е. комиссия за прием электронной валюты будет включена в сумму оплаты покупателя.

Обе схемы работы выгодны покупателю: допустим, он хочет оплатить ваш товар по безналу или наличкой, т.е. ровно на 100 гривен, а у не8го есть виртуальная валюта. Чтобы поменять виртуальные единицы платежной системы на "живую" гривну - затраты на такой обмен будут равнозначны или больше, чем оплата 103,50WMU, при этом покупателю необходимо будет сделать несколько шагов и это займет 1-2 рабочих дня, что весьма неудобно. И пользователю выгоднее сделать покупку в интернет-магазине, чем менять виртуальную валюту на гривну и делать покупку.

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

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

 

РАЗДЕЛ 1. Входные параметры.

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

PAYMENT_AMOUNT – сумма оплачиваемых товаров в копейках – целое число больше нуля.

PAYMENT_INFO = Информация о товаре - 255 символов.

PAYMENT_DELIVER = Информация о доставке – 255 символов

PAYMENT_ADDVALUE = Дополнительная информация клиента – 255 символов (для передачи дополнительных параметров торговой точки)

MERCHANT_INFO = уникальный номер торговой точки в нашей системе (целое положительное число)

PAYMENT_ORDER = уникальный номер заказа в системе торговой точки, проверяется системой на уникальность – в случае поступления заказа на оплату с уже существующим оплаченным номером – система не примет заказ, выдаст ошибку

PAYMENT_TYPE = тип валюты, который используется при оплате:

8 VISA/MASTER Card
1 wmz
5 Яндекс.Деньги
17 ПРИВАТ24-ГРН
34 BTC (Bitcoin)

 

PAYMENT_RULE = Признак на чей счет будет отнесена комиссия по транзакции:
1 – за счет интернет-магазина
2 – за счет клиента
если параметр не определен – по умолчанию используются настройки из административного интерфейса (на текущий момент все за счет клиента).
За счет клиента имеет смысл относить комиссию при оплате за Яндекс, Пейкеш, Монеймейл и еголд – самые дорогие в обслуживании валюты.
Для оплаты VC и НСМЭП этот параметр принудительно устанавливается в 1 из-за правил платежных систем, независимо от того, что прислала торговая точка.

PAYMENT_VISA = зарезервирован для параметров оплат картами Виза/Мастер в случае пользования нашим интерфейсом.

PAYMENT_RETURNRES = полный урл, на который будет возвращен результат транзакции.

PAYMENT_RETURN = полный урл, на который будет возвращен клиент после оплаты в случае успешной оплаты.

PAYMENT_RETURNMET = метод, который будет использован для возврата результата на URL возврата результата:
1 – GET
2 – POST 
Если не указан – возвращаться будет методом POST.

PAYMENT_RETURNFAIL = полный урл, на который будет возвращен клиент после оплаты в случае неудачной оплаты.

PAYMENT_TESTMODE = признак режима тестирования
0 – режим нормальной работы
1 – режим тестирования.

PAYMENT_HASH = 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"

Последний параметр $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-режим работы платежного шлюза.

При таком режиме в выходной поток выдаются помимо обычных данных форматированные данные:
Html-код имеет следующие параметры:
<UASILENT>
<UANIDDENS>
$form – набор параметров формы куда уйдет покупатель к самому платежному шлюзу какой-либо системы.
</UAHIDDENS>
<UAAMOUNTUAH>
$wm_uah – сумма платежа в гривне
</UAAMOUNTUAH>
<UAAMOUNTVAL>
$amount – сумма платежа в вібранном виде оплаты
</UAAMOUNTVAL>
<UANAMEVAL>
$wmval – название вида оплаты
</UANAMEVAL>
<UASALEPOINT>
$shopname – название магазина
</UASALEPOINT>
<UAOWNER>
$firm – владелец магазина
</UAOWNER>
<UAGOODSINFO>
$info – информация о покупке
</UAGOODSINFO>
<UAGOODSDELIVER>
$deliver – информация о доставке товара
</UAGOODSDELIVER>
</UASILENT>

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

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

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

Как сделать такой вызов методом 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 = "http://www.money.ua/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 лежит результат платежного шлюза, который надо вывести на экран своему покупателю.

 

РАЗДЕЛ 2. Выходные параметры.

Возврат информации торговой точке осуществляется на возвратный 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 – емейл покупателя в случае оплаты им товара чеком Paymer (при оплате в Webmoney)

RETURN_TPHONE – номер телефона покупателя в случае оплаты им товара из мобильного телефона (при оплате в Webmoney-Телепат)

RETURN_COMMISSTYPE – возвратное значение за счет кого в конечном итоге была взята комиссия
1 – за счет фирмы
2 – за счет клиента

RETURN_TYPE – каким методом была оплата:
16 VISA/MASTER Card
1 wmz
2 wmr
3 wmu
5 Yandex.Деньги
9 nsmep
14 Терминалы приема наличных
15 liqpay-USD
16 liqpay-ГРН
17 ПРИВАТ24-ГРН
18 ПРИВАТ24-USD
34 BTC (Bitcoin)

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" - в этом случае система больше не будет пытаться доставить на ваш УРЛ результат повторно.

 

 

РАЗДЕЛ 3.  Использование UTF-8 при подаче запроса на оплату.

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

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

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

1) flagxml - обозначает, что используется метод подачи запроса через XML, должен быть равен 1.

2) strxml - содержимое XML-запроса, которое является URL-кодированной строкой в соответствии с RFC1738 и после этого закодированная способом 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-запроса он URL-кодируется, после чего у полученной строке применяется MIME-кодирование:

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

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

 

3) MERCHANT_INFO - уникальный номер торговой точки в нашей системе (целое положительное число)

4) PAYMENT_HASH = md5-хэш, который вычисляется путем слияния двух параметров strxml и SECRETCODE:

            $PAYMENT_HASH  = md5($strxml.$SECRETCODE);

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

 

Copyright © 2000-2006 Cherkashyn Vyacheslav