регистрация

Новости

 

 

Контакты


199-902

Терминал

Содержание




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


Продавец
Продавцом считается пользователь системы "Веб Оплата", принимающий на свой счет в системе оплату от пользователей сети Интернет с помощью 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 символов, допускаются любые символы.

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

1
2
3
4
5
6
7
8
9
10

<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 формате: 1558485891
дополнительные
параметры
продавца
UserData Поле формы, имеющие название "UserData". формат: описан выше
контрольная
подпись
HashString Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя. Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже".

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<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="1558485891" 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 пример формировния контрольной подниси
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?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-хэша от него

Форма запроса:
1
2
3
4
5
6
<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 сумма отправления сумма перевода ( в валюте отправления ), которая будет списана с баланса отправителя

Форма запроса:
1
2
3
4
5
6
7
8
9
<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 сумма сертификата сумма генерации сертификата, которая будет списана с баланса пользователя который создает сертификат

Форма запроса:
?
1
2
3
4
5
6
7
8
<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)

 
© 2010-2016 "ВЕБ-ОПЛАТА"
Система приема платежей.
Кнопка