поддержка
регистрация авторизация email-адрес пароль введите код забыли пароль ?
вход
Новости
Платежный интерфейс
12
05.2016
Продажа через Каталог
21
03.2016
Вывод на WebMoney
22
06.2015
Оплата через СМС
все новости
Контакты
support@sprypay.ru
8 (800) 333-12-31
+7 (495) 646-82-54
482-240-435
Платежные системы > Платежный интерфейс
  • SpryPay Payment Interface
  • API



Описание 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 до 1024 символов, допускаются цифры, латинские и русские символы, ' _$`-.:,;№#()|' (ci).
Описание может быть представлено в виде списка ( например список товаров ), в это случае разделителем строк будет `||`, а разделителем позиций и цены - `|`.
Пример: `Шуба|1000||Магниафон импортный|300`.
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.
формат: список числовых или текстовых кодов п.с через запятую, смотрите ниже
цветовая схема colorTheme Параметр "colorTheme" используется для указания цветовой схемы платежного интерфейса. Допустимые значения: `white` - светлая тема, параметр не задан или имеет любое другое значение - темная тема.
активная вкладка в списке п.с. activeTab Данный параметр используется для указания активной вкладки с платежными системами при переходе на страницу оплаты. Допустимые значения: 1 | 2 | 3 | 4 ( по умолчанию активна вкладка 1 => `Электронные деньги`).
авторедирект с 1 выставленной п.с. autoRedirect Данный параметр используется для автоматического перенаправления на сайт платежной системы, в случае если список п.с. состоит из одной п.с.. Для автоматического перенаправления на сайт п.с., указанная п.с должна быть online'овой ( WM, Яд, QIWI-wallet ... ). При использовании авторедиректа, данные о email-адресе клиента и номере телефона ( если необходимо ), должны передаваться в форме запроса платежа.
Допустимые значения: 1 | 0.
Для проверки данного параметра можно в форму запроса платежа добавить 3 парметра: autoRedirect = '1', spSelectedPS = 'WMRUR', spUserEmail = 'test@mail.ru';

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

Форма оповещения о платеже
Эта форма передает продавцу реквизиты выполненного платежа. Она имеет следующие атрибуты и поля:
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 цифр ( 2012****** )
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
  • Секретный ключ
При формирования контрольной подписи формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5) разработанным Ron Rivest из MIT Laboratory for Computer Science и RSA Data Security, Inc. Алгоритм был опубликован в Интернете в апреле 1992 года (RFC 1321).

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

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 интерфейсом.

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

PerfectMoney USD (88 / PFMUSD)
QIWI Кошелек ( выставление счета ) (129 / QIWIPR)
QIWI Кошелек ( через каталог ) (544 / QIWITRW)
WebMoney E (8 / WMEUR)
WebMoney R (6 / WMRUR)
WebMoney Z (5 / WMUSD)
Яндекс.Деньги (141 / YNDRUR)
HandyBank (128 / HNDBNK)
Raiffeisen CONNECT (442 / RFNRUR)
Альфа-Клик (38 / AFCRUR)
ВТБ24.Телебанк (28 / VTBRUR)
РосБанк интернет-банк (461 / RSBRUR)
Сбербанк ОнЛ@йн (121 / SBORUR)
Тинькофф КС (401 / TCSRUR)
Фактура.РУ (241 / FKTRUR)
QIWI Терминалы (29 / QIWITR)
Банковский перевод (для физ. лиц.) по РФ (36 / BNKRUR)
Евросеть салоны связи (163 / ERSRUR)
Почта России (43 / RPRUR)
Связной салоны связи (242 / SVZRUR)
Элекснет терминалы (37 / EXNRUR)
Билайн (84 / SMSBEE)
МТС (126 / SMSMTS)
Мегафон (127 / SMSMGF)
ТЕЛЕ2 (501 / SMSTL2)
Главная Схема работы
Верификация
Подключить
магазин
SPPI / IPN
документация
Партнерская
программа
Комиссии
системы
Поиск платежа
Печать чека
Каталог Контакты
Copyright 2008-2016
Система приема платежей
"SpryPay.ru"
• карта сайта
• публичная оферта
Принимаемые платежные системы
Наша кнопка
Соц. сети



Google+