Веб Оплата: описание платежного интерфейса IPN/API.

Новости

25 12.2020	Вывод в КИВИ
18 12.2020	Прием Яндекс
13 12.2020	Прием КИВИ

Контакты

info@web-oplata.com

199-902

Содержание

Основные термины
- Продавец
- Покупатель
Описание IPN интерфейса
API
Список платежных систем с их номерами

Основные термины

Продавец

Продавцом считается пользователь системы "Веб Оплата", принимающий на свой счет в системе оплату от пользователей сети Интернет с помощью IPN сервиса. Предполагается, что продавец принимает оплату за товары или услуги, предоставляемые им через Интернет, и следовательно, имеет собственный веб-сайт.

Покупатель

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

Описание IPN интерфейса

Настройка параметров магазина для приема платежей

Помимо регистрации в "Веб Оплата" для приема платежей через IPN сервис продавец должен настроить ряд параметров добавленного им в систему магазина, регулирующих приема платежей и метод оповещения продавца о факте проведения платежа. Настройка параметров выполняется на странице 'Список магазинов'. Для каждого магазина, через который продавец принимает платежи, в системе хранится свой набор параметров.
Полный перечень параметров и их назначение приведено ниже:

Название параметра	Описание/Формат
ipnUrl:	URL (на веб-сайте продавца), на который сервис IPN посылает HTTP GET/POST запрос ( оповещение ) о совершении платежа с его детальными реквизитами.
failUrl:	URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в том случае, если платеж в сервисе IPN не был выполнен по каким-то причинам.
successUrl:	URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в случае успешного выполнения платежа в IPN сервисе.
ipnEmail:	E-mail адрес на который будет высылаться письмо с полной информацией о прошедшем платеже.
ipnSecretKey:	Строка символов, используется для герерации подписи данных, высылаемых продавцу с оповещением. Содержание строки известно только IPN сервису и продавцу!

Формы HTML
Для передачи информации между веб-сайтом продавца и IPN сервисом используются четыре основных HTML-формы:

Форма запроса платежа - генерируется веб-сайтом продавца для формирования запроса на проведение платежа в IPN сервисе и передачи его через веб-браузер покупателя.
Форма оповещения о платеже - генерируется IPN сервисом для передачи оповещения о платеже на веб-сайт продавца. Оповещение передается без использования веб-браузера покупателя.
Форма выполненного платежа - генерируется IPN сервисом в случае успешного выполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
Форма невыполненного платежа - генерируется IPN сервисом в случае невыполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.

Форма запроса платежа
Эта форма передает запрос с веб-сайта продавца в IPN сервис через веб-браузер покупателя. Она должна иметь следующие атрибуты и поля:
Action - http[s]://web-oplata.com/Pay/
Method - GET/POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:

Название	HTML Field Name	Описание/Формат
id магазина	ShopId	Номер магазина продавца. формат: 1-11 цифр.
Внутренний номер покупки продавца	ShopPaymentId	В этом поле продавец задает уникальный номер для каждого платежа. формат: до 50 символов, цифры и латинские символы.
Сумма платежа	Amount	Сумма платежа, которую продавец желает получить от покупателя. Сумма должна быть больше нуля, дробная часть отделяется точкой. формат: вещественное число, разделитель - точка.
Валюта платежа	Currency	Валюта платежа, в которой продавец желает получить от покупателя платеж. формат: usd, rur, eur, kzt, uah или tmt.
Назначение платежа	Purpose	Описание товара или услуги. Формируется продавцом. кодировка: utf-8 формат: от 1 до 128 символов, допускаются цифры, латинские и русские символы, ' ', '.', '-', '_', ':', ';'
E-mail покупателя	UserEmail	E-mail адрес покупателя, на который высылается полная информация по совершаемому им платежу. Данный параметр не является обязательным. Может быть заранее определен продавцом ( допустим из собственной базы покупателей ), чтобы избавить покупателя от его ввода. формат: до 255 символов, может содержать латинские буквы, цифры, '_', '.', '@' и '-'
Дополнительные параметры продавца	UserData	Поле формы, имеющие названии "UserData", обрабатываются IPN сервисом автоматически и передаются на веб-сайт продавца после выполнения платежа. формат значения параметра: до 255 символов, допускаются любые символы.

Пример формы запроса платежа

<form action="http://web-oplata.com/Pay/" method="POST" accept-charset="utf-8">
  <input name="ShopId" value="номер вашего магазина" type="hidden">
  <input name="ShopPaymentId" value="ваш номер платежа" type="hidden">
  <input name="Currency" value="rur, usd, eur, uah, kzt или tmt" type="hidden">
  <input name="Purpose" value="назначение платежа" type="hidden">
  <input name="Amount" value="3.00" type="hidden">
  <input name="UserEmail" value="usermail@mail.ru" type="hidden">
  <input name="UserData" value="order_#1234567" type="hidden">
  <input value="оплатить" type="submit">
</form>

Форма оповещения о платеже
Эта форма передает продавцу реквизиты выполненного платежа, метод вызова ipnUrl "POST".
Она имеет следующие атрибуты и поля:
action - ipnUrl
fields - поля, передаваемые в форме, описаны в таблице ниже:

Название	HTML Field Name	Описание
id платежа	PaymentId	Номер платежа в системе исчисления "Веб Оплата". Является уникальным. формат: целое число.
id магазина	ShopId	Номер магазина продавца. формат: целое число, 1-11 цифр.
Внутренний номер покупки продавца	ShopPaymentId	Номер покупки в соответствии с системой исчисления продавца. формат: до 12 символов, цифры и латинские символы (cs).
сумма на баланс	BalanceAmount	Сумма которая будет зачислена продавцу на баланс при зачислении платежа. Вычисляется по курсу ЦБРФ на день создания платежа. формат: вещественное число, разделитель - точка.
Валюта баланса	BalanceCurrency	формат: rur, usd, eur, uah, kzt или tmt.
сумма платежа	Amount	Сумма платежа указанная в "Форме запроса платежа" на сайте продавца. формат: вещественное число, разделитель - точка.
валюта платежа	Currency	Валюта платежа, указанная в "Форме запроса платежа", в которой продавец желает получить от покупателя платеж. формат: rur, usd, eur, uah, kzt или tmt.
E-mail покупателя	CustomerEmail	E-mail адрес покупателя. формат: до 255 символов, может содержать латинские буквы, цифры, '_', '.', '@' и '-' (ci).
назначение платежа	Purpose	Описание товара или услуги указанное в "Форме запроса платежа". формат: от 1 до 128 символов, допускаются цифры, латинские и русские символы, ' ', '.', '-', '_', ':', ';' (ci).
id платежной системы	PaymentSystemId	Номер платежной системы в которой покупатель совершил оплату. Список платежных систем с их номерами смотрите ниже. формат: целое число, 1-11 цифр.
дата зачисления	EnrollDateTime	Дата и время в которое система "Веб Оплата" получила данные о выполненном платеже от выбранной покупателем платежной системы. В это же время производится зачисление средств на баланс продавца. Значение в UNIX формате: 1695571437
дополнительные параметры продавца	UserData	Поле формы, имеющие название "UserData". формат: описан выше
контрольная подпись	HashString	Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя. Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже".

Пример формы оповещения о платеже

<form action="ipnUrl" method="POST" accept-charset="utf-8">
  <input name="PaymentId" value="номер платежа в Веб-оплата" type="hidden">
  <input name="ShopId" value="номер вашего магазина" type="hidden">
  <input name="ShopPaymentId" value="ваш номер платежа" type="hidden">
  <input name="BalanceAmount" value="32.52" type="hidden">
  <input name="BalanceCurrency" value="rur" type="hidden">
  <input name="Amount" value="1" type="hidden">
  <input name="Currency" value="usd" type="hidden">
  <input name="CustomerEmail" value="someuser@somemailserver.ru" type="hidden">
  <input name="Purpose" value="назначение платежа" type="hidden">
  <input name="PaymentSystemId" value="32" type="hidden">
  <input name="EnrollDateTime" value="1695571437" type="hidden">
  <input name="UserData" value="какой-то не обязательнй параметр" type="hidden">
  <input name="HashString" value="4fb1f77821ccf9ed79ddadf0688c9d45" type="hidden">
</form>

Примечание: данные, отправляемые на ваш ipnUrl, будут в кодировке utf-8.

Формат ответа на оповещение о платеже
В результате обработки POST запроса, содержащего данные о платеже, скрипт магазина должен вернуть ответ в виде строки:

Ответ равен строке `ok` – это означает, что данные о платеже получены, оповещения по этому платежу более не требуются.
Любые другие оветы – для IPN сервиса это означает, что данные магазином не получены и оповещние магазина будет продолжено.

Форма выполненного платежа
Эта форма передает реквизиты выполненного платежа на веб-сайт продавца после успешного выполнения операции. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL "GET" или "POST". Форма имеет следующие атрибуты и поля:
action - successUrl
fields - поля, передаваемые в форме, описаны в таблице ниже:

Название	HTML Field Name	Описание
статус платежа	status	1 - платеж успешно выполнен.
id магазина	ShopId	Номер магазина продавца. формат: целое число, 1-11 цифр.
id транзакции	ShopPaymentId	Уникальный номер покупки в магазине продавца. 1-12 цифр.
сумма платежа	Amount	Сумма платежа указанная в "Форме запроса платежа" на сайте продавца. формат: вещественное число, разделитель - точка.
валюта платежа	Currency	Валюта платежа, указанная в "Форме запроса платежа", формат: rur, usd, eur, uah, kzt или tmt.

Форма невыполненного платежа
Эта форма передает реквизиты невыполненного платежа на веб-сайт продавца. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL "GET" или "POST". Она имеет следующие атрибуты и поля:
Action - Fail URL
Method - Метод Fail URL
Fields - поля, передаваемые в форме, описаны в таблице ниже:

Название	HTML Field Name	Описание
статус платежа	status	0 - платеж не выполнен.
id магазина	ShopId	Номер магазина продавца. формат: целое число, 1-11 цифр.
id транзакции	ShopPaymentId	Уникальный номер покупки в магазине продавца. 1-12 цифр.

Проверка информации о платеже
При выполнении платежа IPN высылает оповещение о платеже через "Форму оповещения о платеже" на ipnUrl, указанный продавцом. Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":

Проверить, не исказились ли данные в процессе передачи ( проверка целостности данных )
Проверить сумму и валюту платежа
Проверить id магазина продавца

Проверка целостности данных
Высылая оповещение о проведение платежа, IPN сервис передает реквизиты платежа и контрольную подпись, позволяющую проверять неизменность передаваемых данных.

Контрольная подпись данных о платеже
Контрольная подпись данных о платеже позволяет продавцу проверять как источник данных, так и целостность данных, переданных на IPN URL через "Форму оповещения о платеже". При формировании контрольной подписи IPN сервис "склеивает" значения полей, передаваемых "Формой оповещения о платеже", в одну строку в следующем порядке:

PaymentId
ShopId
ShopPaymentId
BalanceAmount
BalanceCurrency
Amount
Currency
CustomerEmail
Purpose
PaymentSystemId
EnrollDateTime
Секретный ключ

При формирования контрольной подписи формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5) разработанным Ron Rivest из MIT Laboratory for Computer Science и RSA Data Security, Inc. Алгоритм был опубликован в Интернете в апреле 1992 года (RFC 1321).

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

Сформируйте строку путем "склеивания" значений параметров, полученных через "Форму оповещения о платеже", в том же порядке, что и при формировании контрольной подписи в IPN сервисе (см. выше).
Помните, что при формировании подписи используется Secret Key.
Вычислите MD5 полученной строки.
Сравните полученное значение с значением параметра "HashString", полученного через "Форму оповещения о платеже".

Если сформированная подпись совпадает с полученной через "Форму оповещения о платеже", данные не изменены, и источник данных действительно IPN сервис.

PHP пример формировния контрольной подниси

<?php
 
// список переменных, которые должны присутствовать в запросе с данными платежа
$QueryFields = array('PaymentId', 'ShopId', 'ShopPaymentId', 'BalanceAmount', 'BalanceCurrency', 'Amount', 'Currency', 'CustomerEmail', 'Purpose', 'PaymentSystemId', 'EnrollDateTime', 'HashString');
 
// проверим, что все они присутутвуют в запросе
foreach($QueryFields as $FieldName) if (!isset($_POST[$FieldName])) exit("error");
 
// ваш секретный ключ, задается в настройках магазина
$yourSecretKeyString = 'F22U39r6Liq49EqNfY323XV81kTPxB7n';
 
// получим контрольную подпись
$localHashString = md5($_POST['PaymentId'].$_POST['ShopId'].$_POST['ShopPaymentId'].$_POST['BalanceAmount'].$_POST['BalanceCurrency'].$_POST['Amount'].$_POST['Currency'].$_POST['CustomerEmail'].$_POST['Purpose'].$_POST['PaymentSystemId'].$_POST['EnrollDateTime'].$yourSecretKeyString);
 
// сравним полученную подпись и ту, что пришла с запросом
if ($localHashString==$_POST['HashString'])
{
  // все хорошо, далее делаем проверку суммы, номера магазина и все, что вам понадобится
  ...
  ...
  ...
  exit("ok");
}
else
{
  // подписи не совпали
  exit();
}
?>

Проверка суммы и валюты платежа
Так как покупатель "вручную" может изменить данные конечной формы оплаты, которые передаются уже непосредственно в выбранную платежную систему, продавцу рекомендуется проверять информацию о сумме и валюте платежа, передаваемую через параметр "Amount" и "Currency".

Проверка id магазина продавца
Несмотря на то, что покупатель не может изменить id магазина, с которого совершается платеж, продавцу рекомендуется контролировать его путем проверки параметра "ShopId", особенно при использовании нескольких магазинов при работе с IPN интерфейсом.

API

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

Метод зароса: GET или POST.
Содержимое запроса представляет собой простой перечень параметров и их значений.
Адрес на который отправляются API-запросы: https://web-oplata.com/API/api.php

Формат API-ответа

Ответ на API-запрос отправляется клиенту в XML формате. Кодировка ответа: utf-8. Примеры положительного и отрицательного API-ответа:
.	<response> <resultCode>1</resultCode> <responseBody> ... содержимое ответа ... </responseBody> </response>	.	<response> <resultCode>0</resultCode> <responseBody> <errorMessage>код ошибки</errorMessage> </responseBody> </response>
Ответ всегда начинается и заканчивается с "response". Обязательным параметром ответа является "resultcode". Если "resultcode"="1" - то запрос успешно выполнен и можно читать "содержимое ответа". Если "resultcode"="0" - то возникла ошибка, код ошибки будет присутствовать в обязательном, в этом случае, параметре "errorMessage".
Значения и описание ошибок в параметре "errorMessage". 0 - В запросе отсутствуют обязательные параметры 1 - Пользователь не найден 2 - Неправильный пароль 3 - Ваш IP-адрес отличается от указанного в настройках доступа к API 4 - У отправителя недостаточно средств 5 - Получатель перевода не найден 6 - Сумма должна быть больше нуля

Список API-запросов

Баланс пользователя
Запрос на баланс пользователя. Запрос требует авторизационных данных пользователя.
В таблице представлен список параметров и их значения для данного запроса.

Название	Значение	Описание
action	getBalance
userEmail	email-адрес клиена	email-адрес клиента, с которым он зарегистрирован в системе web-oplata.com
userPasswd	пароль клиента	пароль клиента, с которым он авторизуется на сайте web-oplata.com, пароль в данном запросе передатся не в `чистом` виде, а в виде md5-хэша от него

Форма запроса:

<FORM action="http://web-oplata.com/API/api.php" method="POST" accept-charset="utf-8">
  <input name="action" value="getBalance" type="hidden">
  <input name="userEmail" value="user@email.ru" type="hidden">
  <input name="userPasswd" value="134e3b3e256ef473be91b9s09e1at23d" type="hidden">
  <input value="запрос" type="submit">
</FORM>

Ответ на запрос:

<response>
    <resultCode>1</resultCode>
    <responseBody>
          <rur>0.00</rur>
          <usd>0.00</usd>
          <eur>0.00</eur>
          <uah>0.00</uah>
          <kzt>0.00</kzt>
          <tmt>0.00</tmt>
    </responseBody>
</response>

Проверка данных перед внутренним переводом
Запрос на проверку данных перед выполнением внутреннго перевода.
В таблице представлен список параметров и их значения для данного запроса.

Название	Значение	Описание
action	checkInternalTransfer
userEmail	email-адрес отправителя	email-адрес отправителя, с которым он зарегистрирован в web-oplata.com
userPasswd	пароль отправителя	пароль отправителя, с которым он авторизуется на сайте web-oplata.com, пароль в данном запросе передается не в `чистом` виде, а в виде md5-хэша от него
receiveEmail	получатель перевода	email-адрес получателя, с которым он зарегистрирован в web-oplata.com
Currency	валюта отправления	валюта в которой отправитель отправляет платеж
Amount	сумма отправления	сумма перевода ( в валюте отправления ), которая будет списана с баланса отправителя

Форма запроса:

<FORM action="http://web-oplata.com/API/api.php" method="POST" accept-charset="utf-8">
  <input name="action" value="checkInternalTransfer" type="hidden">
  <input name="userEmail" value="user@email.ru" type="hidden">
  <input name="userPasswd" value="134e3b3e256ef473be91b9s09e1at23d" type="hidden">
  <input name="receiveEmail" value="user2@emaila.net" type="hidden">
  <input name="Currency" value="rur" type="hidden">
  <input name="Amount" value="100" type="hidden">
  <input value="отправить" type="submit">
</FORM>

Ответ на запрос:

.	<response> <resultCode>1</resultCode> <responseBody> <sendAmount>100_rur ( сумма, которая спишется с баланса отправителя )</sendAmount> <receiveAmount>100_rur ( сумма, которую получит получатель )</receiveAmount> </responseBody> </response>

Если `resultCode` - 1, то все данные в запросе прошли проверку и платеж с такими данными будет выполнен. В `sendAmount` и `receiveAmount` можно увидеть суммы которые будут сняты и зачислены по данному платежу ( если его выполнить ).

Внутренний перевод
Запрос на выполнение внутреннго перевода.
Данный запрос идентичен запросу `Проверка данных перед внутренним переводом`, только меняется значение параметра `action`.

Название	Значение	Описание
action	makeInternalTransfer

Генерация подарочного сертификата

Запрос на выполнение генерации подарочного сертификата.

Название	Значение	Описание
action	GenerateGiftCertificates
userEmail	email-адрес пользователя	email-адрес, с которым пользователь зарегистрирован в web-oplata.com
userPasswd	пароль пользователя	пароль с которым пользователь авторизуется на сайте web-oplata.com, пароль в данном запросе передается не в `чистом` виде, а в виде md5-хэша от него
Currency	валюта сертификата	валюта в которой отправитель генерирует сертификат
Amount	сумма сертификата	сумма генерации сертификата, которая будет списана с баланса пользователя который создает сертификат

Форма запроса:

<FORM action="http://web-oplata.com/API/api.php" method="POST" accept-charset="utf-8">
  <input name="action" value="GenerateGiftCertificates" type="hidden">
  <input name="userEmail" value="user@email.ru" type="hidden">
  <input name="userPasswd" value="134e3b3e256ef473be91b9s09e1at23d" type="hidden">
  <input name="Currency" value="rur" type="hidden">
  <input name="Amount" value="100" type="hidden">
  <input value="создать" type="submit">
</FORM>

Ответ на запрос:

.	<response> <resultCode>1</resultCode> <responseBody> <Certificate>603-297-815_100_rur (код_сумма_валюта сертификата)</Certificate> </responseBody> </response>

Список платежных систем с их номерами кодами

	ВЕБ-оплата Пин-код (0)
	ВЕБ-оплата RUR (1)
	ВЕБ-оплата USD (2)
	ВЕБ-оплата EUR (3)
	ВЕБ-оплата UAH (4)
	ВЕБ-оплата KZT (5)
	ВЕБ-оплата TMT (6)
	WebMoney R (7)
	WebMoney Z (8)
	WebMoney E (9)
	WebMoney U (10)
	QIWI Терминалы RUR (11)
	Яндекс Деньги RUR (12)
	LiqPay RUR (13)
	LiqPay USD (14)
	LiqPay EUR (15)
	LiqPay UAH (16)
	Visa/MasterCard (LiqPay) RUR (17)
	Visa/MasterCard (LiqPay) USD (18)
	Visa/MasterCard (LiqPay) EUR (19)
	Visa/MasterCard (LiqPay) UAH (20)
	CONTACT RUR (21)