Прием платежей на сайте
Выставление счета
Механизм взаимодействия, описанный на данной странице предоставит Вам возможность выставить пользователю счёт к оплате, на заданную Вами сумму. Далее он либо будет переадресован на страницу платёжного сервиса, где он сможет осуществить оплату данного счёта удобным ему способом, либо Вы получите ссылку (url) данного счета и в последствии самостоятельно сможете передать её плательщику по email’у или отобразить её в качестве QR кода.
Для инициализации платежа посредством единой формы оплаты вам достаточно направить пользователя по специальному URL, а также передать ряд обязательных для оплаты параметров.
На Вашем сайте необходимо разместить форму, которая будет содержать два поля: поле data, в котором будет содержаться xml или json в зависимости от формата который вы используете с необходимой информацией и поле key, в котором будет находиться подпись данной информации.
» Формат: XML
POST
https://www.bpay.md/user-api/payment1
<form method="POST" action="https://www.bpay.md/user-api/payment1"> <input type="hidden" name="data" value=""> <input type="hidden" name="key" value=""> <input type="submit" value="Submit" > </form>
» Формат: JSON
POST
https://www.bpay.md/user-api-v2/payment
<form method="POST" action="https://www.bpay.md/user-api-v2/payment"> <input type="hidden" name="data" value="<?php echo $data; ?>"> <input type="hidden" name="key" value="<?php echo $key; ?>"> <input type="submit" name="button" value="Submit"> </form>
После нажатия кнопки Submit, пользователь перейдет на платежную форму системы bpay.md, где он осуществляет сам платеж. После завершения платежа, пользователь будет возвращен на страницу Вашего сайта, указанну в success_url. В течении 15 секунд, платежный сервис высылает уведомление о полученном платеже, указанным Вами способом
В форме поле data должно содержать следующий xml, зашифрованный по алгоритму base64 (Функция base64_encode в php, или encode_base64 в perl):
<payment> <type>1.2</type> <merchantid>MERCHANT_ID</merchantid> <amount>AMOUNT_VALUE</amount> <description>PAYMENT_DESCRIPTION</description> <method>bpay</method> <order_id>USER_ACCOUNT</order_id> <success_url>SUCCESS_URL</success_url> <fail_url>FAIL_URL</fail_url> <callback_url>CALLBACK_URL</callback_url> <lang></lang> <advanced1></advanced1> <advanced2></advanced2> <istest>ISTEST</istest> <getUrl>GET_URL</getUrl> </payment>
» Формат: JSON
Необходимо сформировать массив (array) и перевести его в json формат и кодировать данные в формат MIME base64.
$json = [ 'merchantid' => 'test_merchant', 'amount' => 10, 'order_id' => 9876, 'description' => 'user api v2', 'lang' => 'ru', 'method' => 'bpay', 'success_url' => 'https://bpay.md/success', 'fail_url' => 'https://bpay.md/fail', 'callback_url' => 'https://bpay.md/callback', 'valute' => 498, 'dtime' => date('Ymd H:i:s'), 'getUrl' => '1', 'params' => [ 'type_of_payer' => 'main', 'info' => 'test information', 'invoice' => [ [ 'id' => 156, 'name' => 'mobile phone', 'model' => 'iphone 8+', 'sum' => 800 ], [ 'id' => 556, 'name' => 'TV Philips', 'model' => 'K223AA2200', 'sum' => 300 ] ] ] ]; $data = base64_encode(json_encode($json));
Для дополнительной безопасности ваших платежей мы проводим обязательную проверку цифровой подписи при создании платежа. Наличие подписи гарантирует защиту от подмены передаваемых значений (например, изменение суммы платежа или номера заказа).
» Формат: XML
Подпись формируется посредством объединения строк md5 хэшей от сформированного нами XML и хэша Signature, полученного при регистрации мерчанта MD5 (MD5(XMLDATA) + MD5 (Signature)):
Функция md5 возвращает хэш строки в HEX виде в нижнем регистре.
После, полученная подпись вставляется в форму в поле key
md5(md5($xmldata) . md5($signature))
» Формат: JSON
Подпись формируется путем обьединения json данных с сигнатурой которая выдается при регистрации магазина. Далее необходимо сформировать хэш в алгоритме sha256 он же (метод хеширования)
$signature = 'signature'; // Формирование hash // hash - Генерирует хеш-код // Первый параметр это алгоритм шифрования // Второй параметр это json // Третий параметр это сигнатура $key = hash('sha256', base64_encode(json_encode($json)) . $signature)
Поле | Значение | Тип | Формат | Описание |
---|---|---|---|---|
type | Обязательное | String | XML | Поле определяет версию протокола. На данный момент устанавливается 1.1 |
merchantid | Обязательное | String | XML | JSON | MerchantID интернет магазина, полученный при регистрации в качестве Merchant’a |
amount | Обязательное | Number | XML | JSON | Сумма, которую клиент должен оплатить в пользу интернет магазина. Указывается в той валюте, в которой у вас открыт счёт в платёжной системе. |
dtime | Обязательное | date | JSON | Время формирования платежа . |
description | Обязательное | String | XML | JSON | Описание платежа, которое будет выводиться в соответствующем поле при оплате. |
method | Обязательное | String | XML | JSON | Тип оплаты, который будет включен для пользователя по-умолчанию. Возможные типы: bpay (счет bpay), perfectMUSD (кошелек PerfectMoney), advcashUSD (кошелек AdvCash) и т.д. Полный актуальный список методов оплаты Вы можете узнать у курирующего Вас менеджера. |
order_id | Обязательное | Number | XML | JSON | Поле, по которому Вы (интернет магазин), сможете однозначно идентифицировать плательщика или платеж, после его завершения. Например: номер телефона, номер заказа, номер счета. Значение этого поля может быть не уникальным для каждой оплаты, как например: номер телефона, email и т.п. |
success_url | Необязательное | String | XML | JSON | Адрес страницы, на которую пользователь будет возвращен, после успешного завершения оплаты. Не обязательное поле. В случае его отсутствия будет взято значение по умолчанию из настроек Вашего мерчанта. |
fail_url | Необязательное | String | XML | JSON | Адрес страницы, на которую пользователь будет возвращен, в случае, если он откажется от оплаты на странице платёжной системы. Не обязательное поле. В случае его отсутствия будет взято значение по умолчанию из настроек Вашего мерчанта. |
callback_url | Необязательное | String | XML | JSON | Url адрес мерчанта (интернет магазина), на который будет приходить уведомление об успешном осуществлении платежа. После этого уведомления, мерчант может осуществлять отправку товара или же оказание услуги. Не обязательное поле. В случае его отсутствия будет взято значение по умолчанию из настроек Вашего мерчанта. |
lang | Необязательное | String | XML | JSON | Язык формы оплаты. Может содержать значения: ru, ro, en. Не обязательное поле. Используется только, если значение getUrl установлено в 0, или же не установлено вообще. |
advanced1, advanced2 | Необязательное | String | XML | Не обязательные, дополнительные поля, которые заполняются произвольными данными. Эти данные будут возвращены интернет-магазину после осуществления оплаты. Могут содержать любые данные по желанию интернет магазина. |
params | Необязательное | String | JSON | Не обязательные, дополнительные поля, которые заполняются произвольными данными. Эти данные будут возвращены интернет-магазину после осуществления оплаты. Могут содержать любые данные по желанию интернет магазина. |
istest | Необязательное | String | XML | JSON | 0 — реальный платеж, 1 -тестовый. В случае тестового платежа доступен только метод оплаты bpay. При тестовом платеже деньги со счета плательщика не снимаются, однако мерчант получает уведомление о платеже. Не обязательное поле. По умолчанию платеж реальный. |
getUrl | Необязательное | String | XML | JSON | Если 0, то система автоматически переадресует плательщика на страницу оплаты. Если 1 — вернёт мерчанту (интернет магазину) xml, в котором будет содержаться url ссылка на счёт. Данная ссылка в последствии может быть передана пользователю по email’у, текстовом мессенджеру или распечатана в качестве QR кода. Не обязательное поле. По умолчанию происходит переадресация на страницу платёжной системы. |
<?php $signature="123456"; // подпись, полученная при регистрации мерчанта // xml данные: $xmldata="<payment> <type>1.2</type> <merchantid>myeshop</merchantid> <amount>10.00</amount> <description>оплата за рога и копыта</description> <method>default</method> <order_id>kesha@xxx.yyy</order_id> <success_url>".htmlspecialchars("http://myeshop.com/success.html")."</success_url> <fail_url>".htmlspecialchars("http://myeshop.com/pay_error.html")."</fail_url> <callback_url>".htmlspecialchars("http://myeshop.com/callback.html")."</callback_url> <lang>ru</lang> <advanced1>12, Lenina street ap. 46</advanced1> <advanced2></advanced2> </payment>"; // шифрум данные и подписываем их $data = base64_encode($xmldata); $sign = md5(md5($xmldata) . md5($signature)); ?> <form method="POST" action="https://www.bpay.md/user-api/payment1"> <input type="hidden" name="data" value="<? echo $data; ?>"> <input type="hidden" name="key" value="<? echo $sign; ?>"> <input type="submit" value="Transfer" > </form>
После нажатия кнопки Transfer, пользователь перейдет на платежную форму системы bpay.md, где он осуществляет сам платеж. После завершения платежа, пользователь будет возвращен на страницу Вашего сайта, указанну в success_url. В течении 15 секунд, платежный сервис высылает уведомление о полученном платеже, указанным Вами способом
<?php $signature = "123456"; // строка, для подписи, указанная при регистрации мерчанта $json = [ 'merchantid' => 'test_merchant', 'amount' => 10, 'order_id' => 9876, 'description' => 'user api v2', 'lang' => 'ru', 'method' => 'bpay', 'success_url' => 'https://bpay.md/success', 'fail_url' => 'https://bpay.md/fail', 'callback_url' => 'https://bpay.md/callback', 'valute' => 498, 'dtime' => '20220705 13:48:10', 'getUrl' => '1', 'params' => [ 'type_of_payer' => 'main', 'info' => 'test information', 'invoice' => [ [ 'id' => 156, 'name' => 'mobile phone', 'model' => 'iphone 8+', 'sum' => 800 ], [ 'id' => 556, 'name' => 'TV Philips', 'model' => 'K223AA2200', 'sum' => 300 ] ] ] ]; $data = base64_encode(json_encode($json)); $key = hash('sha256', $data . $signature); ?> <form method="POST" action="https://www.bpay.md/user-api-v2/payment"?> <input type="hidden" name="data" value=""?> <input type="hidden" name="key" value=""?> <input type="submit" name="button" value="Transfer"?> </form?>
После нажатия кнопки Transfer, пользователь перейдет на платежную форму системы bpay.md, где он осуществляет сам платеж. После завершения платежа, пользователь будет возвращен на страницу Вашего сайта, указанну в success_url. В течении 15 секунд, платежный сервис высылает уведомление о полученном платеже.
Код | Валюта | Навание |
---|---|---|
498 | MDL | Молдавский Лей |
643 | RUB | Российский рубль |
840 | USD | Доллар |
946 | RON | Румынский лей |
978 | EUR | Евро |
Проверка оплаты (обработка callback)
После того, как пользователь осуществил оплату выставленного Вами счета, платежная система bpay.md может в автоматическом режиме уведомлять информационную систему интернет магазина о поступившей оплате. Для того что бы включить автоматическое уведомление, Вам необходимо при регистрации мерчанта указать CALLBACK_URL — адрес скрипта, который будет вызван платежной системой после осуществления оплаты пользователем. В этот скрипт при его вызове будут переданы данные методом POST. Данные будут состоять из 2х полей — поля data и поля key.
Расшифровка поля data производиться методами base64_decode в PHP, или decode_base64 в perl. Первоначально необходимо проверить правильность подписи полученных данных, что бы убедиться, что они отосланы именно сервисом bpay. Для этого необходимо сформировать заново подпись и сверить её с той, что была передана в поле key.
В поле data будет содержаться зашифрованный в base64 json с данными о платеже, а в поле key будет содержаться подпись этих данных. Посредством сверки данной подписи, Вы сможете убедиться в том, что данные были присланы именно Платежным сервисом bpay.md
» Формат: XML
Формирование подписи происходит по следующему алгоритму: MD5(MD5(XMLDATA) + MD5(SIGNATURE)). SIGNATURE — поле, указанное Вами при регистрации мерчанта.
<payment> <type>1.2</type> <order_id>USER_ACCOUNT</order_id> <amount>AMOUNT_VALUE</amount> <valute>498</valute> <comand>pay</comand> <advanced1></advanced1> <advanced2></advanced2> <transid>105</transid> <receipt>108757114530315</receipt> <time>20111007 134928</time> <test>0</test> </payment>
» Формат: JSON
Формирование подписи происходит по следующему алгоритму: hash(‘sha256’, hash(‘sha256’,$_POST[‘data’]) + hash(‘sha256’,SIGNATURE)). SIGNATURE — поле, указанное Вами при регистрации мерчанта.
{ "merchantid":"12312", "order_id' ":"232", "amount' ":"40", "valute' ":"498", "comand' ":"pay", "transid' ":"1232", "receipt' ":"1231231231", "time' ":"2020-02-04 22:22:22", "params ":{ "param1":{ "data":1 }, "param2":{ "data":2 } } }
В случае, если сформированная Вами подпись соответствует той, что передана в поле key, можно переходить к процессу зачисления платежа. После расшифровки поля data, в нем будет содержаться следующий xml:
Поле | Описание |
---|---|
type | поле определяет версию протокола. На данный момент устанавливается 1.2 |
order_id | Возвращает значение order_id, переданное Вами, при формировании счета |
amount | сумма, которую клиент оплатил. |
valute | код валюты, в которой указана сумма оплаты. 498 — молдавские леи |
comand | если был осуществлен платеж — указано pay, если только произведена проверка существования указанного order_id в системе интернет магазина, то будет содержать check |
advanced1, advanced2 | поля, переданные вами при формировании счета. |
transid | уникальный номер платежа в системе bpay.md |
receipt | уникальный номер чека, присвоенный системой bpay.md. Зная этот номер, любой человек сможет проверить существование платежа, через эту форму: https://www.bpay.md/check |
time | время платежа (по времени платежного сервера bpay) в формате ГГГГММДД ччммсс |
test | данный тэг содержит 1 — если платеж тестовый, 0, или пустой если платеж рабочий. |
После обработки платежа, Вам необходимо уведомить платежную систему об успешности, или не успешности данного процесса. Для этого, Вам необходимо вернуть xml или json :
» Формат: XML
<?xml version='1.0' encoding="utf8"?> <result> <code>100</code> <text>success</text> </result>
» Формат: JSON
{ 'code' => 100, 'text' => "success" }
Код | Описание |
---|---|
100 | Если зачисление прошло успешно |
30 | Возникла проблема при зачислении. Система bpay.md повторит попытку через интервал времени. |
Вы можете проверить данные на подлинность путем формирования подписи:
» Формат: XML
// строка, для подписи, указанная при регистрации мерчанта $ourkey=md5(md5($xmldata) . md5($signature))
» Формат: JSON
// строка, для подписи, указанная при регистрации мерчанта $signature = "123456"; $data = $_POST['data']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',hash('sha256',$data).hash('sha256',$signature));
В случае, если сформированная Вами подпись соответствует той, что передана в поле key, можно переходить к процессу зачисления платежа.
<?php $signature = "123456"; // строка, для подписи, указанная при регистрации мерчанта $data = $_POST['data']; $key = $_POST['key']; $xmldata = base64_decode($data); $vrfsign = md5(md5($xmldata) . md5($signature)); if ($key == $vrfsign) { $xml = simplexml_load_string ($xmldata); if ((string)$xml->comand == "check") { // проверка существования указанного order_id // 100 - номер существует, 50 - номер не существует echo "<?xml version='1.0' encoding=\"utf8\"?>"; echo "<result>"; echo "<code>50</code>"; echo "<text>not exist</text>"; echo "</result>"; } elseif ((string)$xml->comand=="pay") { // здесь осуществляем обработку данного платежа echo "<?xml version='1.0' encoding=\"utf8\"?>"; echo "<result>"; echo "<code>100</code>"; echo "<text>success</text>"; echo "</result>"; } else { echo "<?xml version='1.0' encoding=\"utf8\"?>"; echo "<result>"; echo "<code>30</code>"; echo "<text>unknown method</text>"; echo "</result>"; } } else { echo "<?xml version='1.0' encoding=\"utf8\"?>"; echo "<result>"; echo "<code>30</code>"; echo "<text>incorrect signature</text>"; echo "</result>"; } ?>
<?php // строка, для подписи, указанная при регистрации мерчанта $signature = "123456"; $data = $_POST['data']; $key = $_POST['key']; $jsondata = base64_decode($data); $vrfsign = hash('sha256',hash('sha256',$data).hash('sha256',$signature)); if ($key == $vrfsign) { if ((string)$jsondata->comand == "check") { // проверка существования указанного order_id // 100 - номер существует, 50 - номер не существует $json_answer = [ 'code' => 50, 'text' => 'not exist' ]; echo json_encode($json_answer); } else if ((string)$jsondata->comand == "pay") { // здесь осуществляем обработку данного платежа $json_answer = [ 'code' => 100, 'text' => 'success' ]; echo json_encode($json_answer); } else { $json_answer = [ 'code' => 30, 'text' => 'unknown method' ]; echo json_encode($json_answer); } $json_answer = [ 'code' => 30, 'text' => 'unknown method' ]; echo json_encode($json_answer); }