Авторизация
email-адрес
пароль
введите код
- вход
Новости
Платежный интерфейс
08 02.2012 |
Прием LiqPay для казино |
30 01.2012 |
Терминалы оплаты Сбербанка |
19 01.2012 |
Прием Contact RUR |
Описание SPPI ( sprypay payment interface ) интерфейса
Содержание
- Основные термины
- Описание SPPI интерфейса
- Список платежных систем с их номерами
Основные термины
Продавец
| Продавцом считается пользователь системы "SpryPay", принимающий на свой счет в системе оплату от пользователей сети Интернет с помощью SPPI сервиса. Предполагается, что продавец принимает оплату за товары или услуги, предоставляемые им через Интернет, и следовательно, имеет собственный веб-сайт. |
Покупатель
| Покупателем считается пользователь сети Интернет, желающий оплачивать услуги или товары, предлагаемые продавцом на своем веб-сайте. |
Описание SPPI интерфейса
Настройка параметров магазина для приема платежей
|
Помимо регистрации в "SpryPay" для приема платежей через SPPI сервис продавец должен настроить ряд параметров
добавленного им в систему магазина, регулирующих приема платежей и метод оповещения продавца о факте проведения платежа.
Настройка параметров выполняется на странице 'Магазины' сайта https://sprypay.ru. Для каждого магазина,
через который продавец принимает платежи, в системе хранится свой набор параметров. Полный перечень параметров и их назначение приведено ниже: |
| Название параметра | Описание/Формат |
| ipnUrl: | URL (на веб-сайте продавца), на который сервис SPPI посылает HTTP GET/POST запрос ( оповещение ) о совершении платежа с его детальными реквизитами. |
| failUrl: | URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в том случае, если платеж в сервисе SPPI не был выполнен по каким-то причинам. |
| successUrl: | URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в случае успешного выполнения платежа в SPPI сервисе. |
| ipnEmail: | E-mail адрес на который будет высылаться письмо с полной информацией о прошедшем платеже. |
| ipnSecretKey: | Строка символов, используется для герерации подписи данных, высылаемых продавцу с оповещением. Содержание строки известно только SPPI сервису и продавцу! |
| ipnFrequency: | Частота с которой SPPI сервис делает оповещения на ipnUrl. По умолчанию = 10 ( то есть 1 раз в 10 мин ). Значения могут колебаться от 1 до 60. |
| ipnMaxTryes: | Максимальное количество оповещений, которое выполнит SPPI сервис по 1-му платежу. Значения могут колебаться от 1 до 300. Оповещения не выполняются по платежам старше 3-х суток. |
Формы HTML
Для передачи информации между веб-сайтом продавца и SPPI сервисом используются четыре основных HTML-формы:
- Форма запроса платежа - генерируется веб-сайтом продавца для формирования запроса на проведение платежа в SPPI сервисе и передачи его через веб-браузер покупателя.
- Форма оповещения о платеже - генерируется SPPI сервисом для передачи оповещения о платеже на веб-сайт продавца. Оповещение передается без использования веб-браузера покупателя.
- Форма выполненного платежа - генерируется SPPI сервисом в случае успешного выполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
- Форма невыполненного платежа - генерируется SPPI сервисом в случае невыполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
Форма запроса платежа
Эта форма передает запрос с веб-сайта продавца в SPPI сервис через веб-браузер покупателя. Она должна иметь следующие атрибуты и поля:
Action - http[s]://sprypay.ru/sppi/
Method - GET/POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название | HTML Field Name | Описание/Формат |
| id магазина | spShopId | Номер магазина продавца. формат: 1-11 цифр. |
| Внутренний номер покупки продавца |
spShopPaymentId |
В этом поле продавец задает номер покупки в соответствии со своей системой учета.
Несмотря на то, что параметр не является обязательным, мы рекомендуем всегда задавать его.
Желательно использовать уникальный номер для каждого платежа, что позволит быстро получить относящуюся
к нему информацию через другие интерфейсы системы "SpryPay". формат: до 12 символов, цифры и латинские символы (cs). |
| Сумма платежа | spAmount |
Сумма платежа, которую продавец желает получить от покупателя.
Сумма должна быть больше нуля, дробная часть отделяется точкой. формат: вещественное число, разделитель - точка. |
| Валюта платежа | spCurrency | Валюта платежа, в которой продавец желает получить от покупателя платеж. формат: usd, rur, eur или uah. |
| Назначение платежа | spPurpose |
Описание товара или услуги. Формируется продавцом. кодировка: utf-8 формат: от 1 до 128 символов, допускаются цифры, латинские и русские символы, ' ', '.', '-', '_', ':', ';' (ci). |
| E-mail покупателя | spUserEmail |
E-mail адрес покупателя, на который высылается полная информация по совершаемому им платежу.
Данный параметр не является обязательным. Может быть заранее определен продавцом ( допустим из
собственной базы покупателей ), чтобы избавить покупателя от его ввода. формат: до 255 символов, может содержать латинские буквы, цифры, '_', '.', '@' и '-' (ci). |
| Дополнительные параметры продавца | spUserData[*] |
Все поля формы, имеющие в названии префикс "spUserData", обрабатываются SPPI сервисом автоматически и
передаются на веб-сайт продавца после выполнения платежа. формат имени параметра: не более 20 символов, может содержать цифры и латинские символы (cs). формат значения параметра: до 255 символов, допускаются любые символы (cs). |
| URL оповещения | spIpnUrl |
URL на вашем сайте, на который будет приходить полная информация о платеже ( см. "Форма оповещения о платеже" ). Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. |
| метод для URL оповещения | spIpnMethod |
Метод (POST/GET) при помощи которого будет выполнен запрос с данными на вышеописанный "URL оповещения". Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. формат значения параметра: '1' для POST, '0' для GET метода. |
| URL удачного платежа | spSuccessUrl |
URL на вашем сайте, на который будет перенаправлен пользователь в случае удачного выполнения платежа ( см. "Форма выполненного платежа" ). Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. |
| метод для URL удачного платежа | spSuccessMethod |
Метод (POST/GET) при помощи которого будет выполнена переадресация пользователя на вышеописанный "URL удачного платежа". Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. формат значения параметра: '1' для POST, '0' для GET метода. |
| URL неудачного платежа | spFailUrl |
URL на вашем сайте, на который будет перенаправлен пользователь в случае неудачного выполнения платежа ( см. "Форма выполненного платежа" ). Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. |
| метод для URL неудачного платежа | spFailMethod |
Метод (POST/GET) при помощи которого будет выполнена переадресация пользователя на вышеописанный "URL неудачного платежа". Данный параметр является не обязательным, а в случае необходимости переопределяет подобный параметр в настройках магазина. формат значения параметра: '1' для POST, '0' для GET метода. |
| язык (en,ru) | lang | Параметр "lang" предназначен для установки языка. Допустимые значения (ru, en). |
| разрешенный список п.с | spSelectedPS |
Параметр "spSelectedPS" используется для указания строгого списка показываемых при оплате платежных систем.
Например, в настройках магазина указан для приема весь возможный список платежных систем, а Вам необходимо показать пользователю только WebMoney WMZ. формат: список числовых или текстовых кодов п.с через запятую, смотрите ниже |
| запрещенный список п.с | spForbiddenPS |
Параметр "spForbiddenPS" используется для исключения какой либо п.с. из списка показываемых при оплате.
Например, в настройках магазина указан для приема весь возможный список платежных систем, а Вам необходимо скрыть от пользователя WebMoney WMZ и WebMoney WMR. формат: список числовых или текстовых кодов п.с через запятую, смотрите ниже |
Пример формы запроса платежа
Форма оповещения о платеже
Эта форма передает продавцу реквизиты выполненного платежа. Она имеет следующие атрибуты и поля:
action - ipnUrl
fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название | HTML Field Name | Описание |
| id платежа | spPaymentId |
Номер платежа в системе исчисления "SpryPay". Является уникальным. формат: целое число, 10 цифр ( 20******** ) |
| id магазина | spShopId |
Номер магазина продавца. формат: целое число, 1-11 цифр. |
| Внутренний номер покупки продавца |
spShopPaymentId |
Номер покупки в соответствии с системой исчисления продавца. формат: до 12 символов, цифры и латинские символы (cs). |
| сумма на баланс | spBalanceAmount |
Сумма sp которая будет зачислена продавцу на баланс при зачислении платежа. Вычисляется по курсу ЦБРФ на день создания платежа. формат: вещественное число, разделитель - точка. |
| сумма платежа | spAmount |
Сумма платежа указанная в "Форме запроса платежа" на сайте продавца. формат: вещественное число, разделитель - точка. |
| валюта платежа | spCurrency |
Валюта платежа, указанная в "Форме запроса платежа", в которой продавец желает получить от покупателя платеж. формат: usd, rur, eur или uah. |
| E-mail покупателя | spCustomerEmail |
E-mail адрес покупателя. формат: до 255 символов, может содержать латинские буквы, цифры, '_', '.', '@' и '-' (ci). |
| назначение платежа | spPurpose |
Описание товара или услуги указанное в "Форме запроса платежа". формат: от 1 до 128 символов, допускаются цифры, латинские и русские символы, ' ', '.', '-', '_', ':', ';' (ci). |
| id платежной системы | spPaymentSystemId |
Номер платежной системы в которой покупатель совершил оплату. Список платежных систем с их номерами смотрите ниже. формат: целое число, 1-11 цифр. |
| сумма в единицах платежной системы |
spPaymentSystemAmount |
Сумма платежа в еденицах измерения выбранной покупателем латежной системы. формат: вещественное число, разделитель - точка. |
| id платежа в платежной системе |
spPaymentSystemPaymentId |
Номер выполненного платежа в системе исчисления выбранной покупателем платежной системы. формат: строка до 12 символов |
| дата зачисления | spEnrollDateTime |
Дата и время в которое система "SpryPay" получила данные о выполненном платеже от выбранной
покупателем платежной системы. В это же время производится зачисление средств на баланс продавца. формат: ГГГГ-ММ-ДД ЧЧ:ММ:СС |
| дополнительные параметры продавца |
spUserData[*] |
Все поля формы, имеющие в названии префикс "spUserData". формат: описан выше |
| контрольная подпись |
spHashString | Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя. Алгоритм формирования описан в разделе "Контрольная подпись данных о платеже". |
| валюта суммы на баланс | spBalanceCurrency |
Валюта в которой вам будет зачислена на баланс сумма "spBalanceAmount". формат: usd, rur, eur или uah. |
Пример формы оповещения о платеже
Примечание: данные, отправляемые на ваш ipnUrl, будут в кодировке utf-8.
Формат ответа на оповещение о платеже
В результате обработки GET/POST запроса, содержащего данные о платеже, скрипт магазина должен вернуть ответ в виде строки:
- Ответ равен строке `ok` – это означает, что данные о платеже получены, оповещения по этому платежу более не требуются.
- Ответ начинается со слова `error` – это означает, что, при получении данных, на стороне магазина возникла какая-то ошибка, оповещения по этому платежу более не требуются.
- Любые другие оветы – для SPPI сервиса это означает, что данные магазином не получены и оповещние магазина будет продолжено.
Примечание: первый килобайт ответа магазина на запрос будет сохранен, вы сможете просмотреть его в данных платежа у себя в аккаунте.
Форма выполненного платежа
Эта форма передает реквизиты выполненного платежа на веб-сайт продавца после успешного выполнения операции. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL "GET" или "POST". Форма имеет следующие атрибуты и поля:
action - successUrl
fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название | HTML Field Name | Описание |
| статус платежа | status | 1 - платеж успешно выполнен. |
| id платежа | spPaymentId |
Номер платежа в системе исчисления "SpryPay". Является уникальным. формат: целое число, 10 цифр ( 2008****** ) |
| id магазина | spShopId |
Номер магазина продавца. формат: целое число, 1-11 цифр. |
| Внутренний номер покупки продавца |
spShopPaymentId |
Номер покупки в соответствии с системой исчисления продавца. формат: до 12 символов, цифры и латинские символы (cs). |
Форма невыполненного платежа
Эта форма передает реквизиты невыполненного платежа на веб-сайт продавца. Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL "GET" или "POST". Она имеет следующие атрибуты и поля:
Action - Fail URL
Method - Метод Fail URL
Fields - поля, передаваемые в форме, описаны в таблице выше ( см. "Форма выполненного платежа" ). Отличие состоит в том, что значение параметра "status" имеет значение "0".
Проверка информации о платеже
При выполнении платежа SPPI высылает оповещение о платеже через "Форму оповещения о платеже" на ipnUrl, указанный продавцом. Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":
- Проверить, не исказились ли данные в процессе передачи ( проверка целостности данных )
- Проверить сумму и валюту платежа
- Проверить id магазина продавца
Проверка целостности данных
Высылая оповещение о проведение платежа, SPPI сервис передает реквизиты платежа и контрольную подпись, позволяющую проверять неизменность передаваемых данных.
Контрольная подпись данных о платеже
Контрольная подпись данных о платеже позволяет продавцу проверять как источник данных, так и целостность данных, переданных на IPN URL через "Форму оповещения о платеже". При формировании контрольной подписи SPPI сервис "склеивает" значения полей, передаваемых "Формой оповещения о платеже", в одну строку в следующем порядке:
- spPaymentId
- spShopId
- spShopPaymentId
- spBalanceAmount
- spAmount
- spCurrency
- spCustomerEmail
- spPurpose
- spPaymentSystemId
- spPaymentSystemAmount
- spPaymentSystemPaymentId
- spEnrollDateTime
- Секретный ключ
Проверка контрольной подписи
Проверка контрольной подписи может выполняться на сайте продавца по следующему алгоритму:
-
Сформируйте строку путем "склеивания" значений параметров, полученных через "Форму оповещения о платеже",
в том же порядке, что и при формировании контрольной подписи в SPPI сервисе (см. выше).
Помните, что при формировании подписи используется Secret Key. - Вычислите MD5 полученной строки.
- Сравните полученное значение с значением параметра "spHashString", полученного через "Форму оповещения о платеже".
PHP пример формировния контрольной подниси
// в данном примере данные приходят в POST-запросе
// список переменных, которые должны присутствовать в запросе с данными платежа
$spQueryFields = array('spPaymentId', 'spShopId', 'spShopPaymentId', 'spBalanceAmount', 'spAmount', 'spCurrency', 'spCustomerEmail', 'spPurpose', 'spPaymentSystemId', 'spPaymentSystemAmount', 'spPaymentSystemPaymentId', 'spEnrollDateTime', 'spHashString', 'spBalanceCurrency');
// проверим, что все они присутутвуют в запросе
foreach($spQueryFields as $spFieldName) if (!isset($_POST[$spFieldName])) exit("error в запросе с данными платежа отсутствует параметр `$spFieldName`");
// ваш секретный ключ, задается в настройках магазина
$yourSecretKeyString = 'F22U39r6Liq49EqNfY323XV81kTPxB7n';
// получим контрольную подпись
$localHashString = md5($_POST['spPaymentId'].$_POST['spShopId'].$_POST['spShopPaymentId'].$_POST['spBalanceAmount'].$_POST['spAmount'].$_POST['spCurrency'].$_POST['spCustomerEmail'].$_POST['spPurpose'].$_POST['spPaymentSystemId'].$_POST['spPaymentSystemAmount'].$_POST['spPaymentSystemPaymentId'].$_POST['spEnrollDateTime'].$yourSecretKeyString);
// сравним полученную подпись и ту, что пришла с запросом
if ($localHashString==$_POST['spHashString'])
{
// все хорошо, далее делаем проверку суммы, номра магазина и все, что вам понадобится
...
...
...
exit("ok");
}
else
{
// подписи не совпали
exit("error не совпали контрольные подписи; локальная: `$localHashString`; в запросе:`".$_POST['spHashString']."`");
}
Проверка суммы и валюты платежаТак как покупатель "вручную" может изменить данные конечной формы оплаты, которые передаются уже непосредственно в выбранную платежную систему, продавцу рекомендуется проверять информацию о сумме и валюте платежа, передаваемую через параметр "spAmount" и "spCurrency".
Проверка id магазина продавца
Несмотря на то, что покупатель не может изменить id магазина, с которого совершается платеж, продавцу рекомендуется контролировать его путем проверки параметра "spShopId", особенно при использовании нескольких магазинов при работе с SPPI интерфейсом.
Список платежных систем с их номерами / кодами
|
|
|
