|
Продавцом считается пользователь системы "SpryPay", принимающий на свой счет в системе оплату от пользователей
сети Интернет с помощью SPPI сервиса. Предполагается, что продавец принимает оплату за товары или услуги,
предоставляемые им через Интернет, и следовательно, имеет собственный веб-сайт.
|
|
Покупателем считается пользователь сети Интернет, желающий оплачивать услуги или товары, предлагаемые продавцом
на своем веб-сайте.
|
Помимо регистрации в "SpryPay" для приема платежей через SPPI сервис продавец должен настроить ряд параметров
добавленного им в систему магазина, регулирующих приема платежей и метод оповещения продавца о факте проведения платежа.
Настройка параметров выполняется на странице 'Магазины' сайта https://sprypay.ru. Для каждого магазина,
через который продавец принимает платежи, в системе хранится свой набор параметров.
Полный перечень параметров и их назначение приведено ниже:
|
|
IPN URL: |
|
URL (на веб-сайте продавца), на который сервис SPPI посылает HTTP/POST оповещение о совершении платежа с
его детальными реквизитами. Если продавец не определил этот URL, он не будет оповещаться сервисом о
совершенных платежах. URL должен начинаться с префикса "http://" или "https://". В этом случае SPPI
сервис будет посылать оповещение по портам 80 и 443 соответственно.
формат: до 255 символов (cs)
|
|
|
Метод IPN URL |
|
Метод, который будет использоваться при оповещении о совершении платежа на IPN URL.
При значении OFF продавец не будет оповещаться сервисом о прошедших платежах.
формат: POST, GET или OFF
|
|
|
Fail URL |
|
URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в том случае, если
платеж в сервисе SPPI не был выполнен по каким-то причинам. URL должен иметь префикс "http://" или "https://".
формат: до 255 символов (cs)
|
|
|
Метод Fail URL |
|
Метод, который будет использоваться при переходе на Fail URL.
При значении OFF покупатель останется на на странице SPPI сервиса.
формат: POST, GET или OFF
|
|
|
Success URL |
|
URL (на веб-сайте продавца), на который будет переведен интернет-браузер покупателя в случае успешного
выполнения платежа в SPPI сервисе. URL должен иметь префикс "http://" или "https://".
формат: до 255 символов (cs)
|
|
|
Метод Success URL |
|
Метод, который будет использоваться при переходе на Success URL.
При значении OFF покупатель останется на на странице SPPI сервиса.
формат: POST, GET или OFF
|
|
|
E-mail для уведомлений |
|
E-mail адрес на который будет высылаться письмо с полной информацией о прошедшем платеже.
Если его оставить пустым, то письма отправляться не будут.
формат: до 255 символов, может содержать латинские буквы, цифры, '_', '.', '@' и '-' (ci).
|
|
|
Секретный ключ |
|
Строка символов, добавляемая к реквизитам платежа, высылаемым продавцу вместе с оповещением. Эта строка
используется для повышения надежности идентификации высылаемого оповещения. Содержание строки
известно только SPPI сервису и продавцу!
формат: значение ключа генерируется системой автоматически
|
|
|
Состояние магазина |
|
Флаг, разрешающий или запрещающий прием платежей в данном магазине через сервис. Если флаг установлен в
состояние "Выкл.", SPPI интерфейс во всех случаях будет сообщать покупателю о невозможности выполнения платежа.
формат: Вкл/Выкл
|
|
Для передачи информации между веб-сайтом продавца и SPPI сервисом используются четыре основных HTML-формы:
- Форма запроса платежа - генерируется веб-сайтом продавца для формирования запроса на проведение
платежа в SPPI сервисе и передачи его через веб-браузер покупателя.
- Форма оповещения о платеже - генерируется SPPI сервисом для передачи оповещения о платеже на
веб-сайт продавца. Оповещение передается без использования веб-браузера покупателя.
- Форма выполненного платежа - генерируется SPPI сервисом в случае успешного
выполнения платежа и передается на веб-сайт продавца через веб-браузер покупателя.
- Форма невыполненного платежа - генерируется SPPI сервисом в случае невыполнения
платежа и передается на веб-сайт продавца через веб-браузер покупателя.
Эта форма передает запрос с веб-сайта продавца в SPPI сервис через веб-браузер покупателя. Она должна иметь
следующие атрибуты и поля:
Action - http[s]://sprypay.ru/sppi/
Method - POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:
|
id магазина |
|
spShopId |
|
Номер магазина продавца.
формат: 1-11 цифр. |
|
|
Внутренний номер
покупки продавца |
|
spShopPaymentId |
|
В этом поле продавец задает номер покупки в соответствии со своей системой учета.
Несмотря на то, что параметр не является обязательным, мы рекомендуем всегда задавать его.
Желательно использовать уникальный номер для каждого платежа, что позволит быстро получить относящуюся
к нему информацию через другие интерфейсы системы "SpryPay".
формат: до 12 символов, цифры и латинские символы (cs).
|
|
|
Сумма платежа |
|
spAmount |
|
Сумма платежа, которую продавец желает получить от покупателя.
Сумма должна быть больше нуля, дробная часть отделяется точкой.
формат: вещественное число, разделитель - точка.
|
|
|
Валюта платежа |
|
spCurrency |
|
Валюта платежа, в которой продавец желает получить от покупателя платеж.
формат: usd, rur, eur или uah.
|
|
|
Назначение платежа |
|
spPurpose |
|
Описание товара или услуги. Формируется продавцом.
формат: от 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).
|
|
|
какой показать "таб" клиенту |
|
tabNum |
|
Параметр указывает на номер "таба" который по умолчанию будет видеть клиент при переходе на страницу выбора платёжных систем.
Допустимые значения:
1 - "электронные системы"
2 - "денежные / банковские переводы"
3 - "терминалы"
4 - "sms платежи"
|
|
Эта форма передает продавцу реквизиты выполненного платежа. Она имеет следующие атрибуты и поля:
Action - IPN URL
Method - Метод IPN URL
Fields - поля, передаваемые в форме, описаны в таблице ниже:
|
id платежа |
|
spPaymentId |
|
Номер платежа в системе исчисления "SpryPay". Является уникальным.
формат: целое число, 10 цифр ( 2009****** )
|
|
|
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 |
|
Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности
полученной информации и однозначной идентификации отправителя. Алгоритм формирования описан в
разделе "Контрольная подпись данных о платеже".
|
|
В результате обработки GET/POST запроса, содержащего данные о платеже, скрипт магазина должен вернуть ответ
в виде строки:
- "OK" – операция прошла успешно, данные о платеже получены
- "любой другой текст" - ошибка
|
Если SPPI сервис при выполнении запроса оповещения о платеже получил ответ "OK" - то оповещеия по данному
платежу далее производиться не будут. Если ответ отличался от "OK" - то SPPI сервис будет производить
оповещение по данному платежу один раз в 1 минуту ( но не более 2 суток ) пока не получит ответ "OK".
|
Данная система проверки ответа скрипта магазина и повторные отправки данных о платежах, гарантирует получение
магазином всех данных о всех прошедших платежах, не смотря на любые временные проблемы в связи на стороне
провайдера магазина или в случае временного отключения/остановки магазина продавцом.
Эта форма передает реквизиты выполненного платежа на веб-сайт продавца после успешного выполнения операции.
Данные передаются через веб-браузер покупателя только в том случае, если выбран метод вызова Success URL "GET"
или "POST". Форма имеет следующие атрибуты и поля:
Action - Success URL
Method - Метод Success URL
Fields - поля, передаваемые в форме, описаны в таблице ниже:
|
статус платежа |
|
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 высылает оповещение о платеже через "Форму оповещения о платеже" на IPN URL,
указанный продавцом. Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":
- Проверить, не исказились ли данные в процессе передачи (Проверка целостности данных)
- Проверить сумму и валюту платежа
- Проверить 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 сервис.
Так как покупатель "вручную" может изменить данные конечной формы оплаты, которые передаются уже непосредственно
в выбранную платежную систему, продавцу рекомендуется проверять информацию о сумме и валюте платежа,
передаваемую через параметр "spAmount" и "spCurrency".
Несмотря на то, что покупатель не может изменить id магазина, с которого совершается платеж, продавцу
рекомендуется контролировать его путем проверки параметра "spShopId", особенно при использовании нескольких
магазинов при работе с SPPI интерфейсом.
|
