Интерфейс приема платежей для интернет-проектов в виде пополнения на произвольную сумму внутреннего счета пользователя в системе клиента.
Разработан для проектов имеющих систему учета пользователей и прочих биллинговых систем.
- Введение
- Назначение
- Описание
- Термины и понятия
- Подготовительные работы
- Принцип работы
- Легенда
- Порядок шагов при успешной оплате
- Типы передаваемых данных
- Обеспечение безопасности
- Запросы
- Ответы Billing
- Адреса отвечающих серверов
- Запросы
- Переход плательщика в Billing
- Проверка ID плательщика
- Оповещение ИС о платеже
- Список принятых платежей
- Проверка баланса
- Рекуррентные (периодические) платежи
- Аппендикс
- Данные получаемые из интерфейса Клиентского Кабинета
- Тестирование
1. Введение
1.1. Назначение
Прием платежей для пополнения счета/баланса. В отличие от Merchant с сайта Клиента приходит информация только об Id плательщика, а сумма и номер счета формируется на стороне Billing.
1.2. Описание
Система представляет собой магазин, который формирует счета для оплаты в Paysto, и оповещает Клиента о приеме платежа. Взаимодействие с Paysto происходит посредством API Billing для магазинов. Клиентские настройки для приема платежей происходят в кабинете Клиента Paysto на странице «Настройки магазина». Информация о принятых платежах отображается в кабинете Клиента Paysto на странице «История».
1.3. Термины и понятия
Термин |
Описание |
Получатель |
Billing Клиента, в пользу которого идет зачисление средств |
Плательщик |
Лицо, осуществляющее платеж |
ИС |
Информационная система Получателя |
1.4. Подготовительные работы 
Порядок подключения проекта описан здесь.
1.5. Принцип работы

1.5.1. Легенда
- Красные стрелки – переходы Плательщика;
- Зеленые стрелки – запросы между Billing и ИС;
- Сплошные – обязательные;
- Точечные – опциональные.
1.5.2. Порядок шагов при успешной оплате.
- Красная 1. – Пользователь переходит в Billing;
- Зеленая 1, Зеленая 2 - PaySto запрашивает у ИС подтверждение Id Плательщика;
- Красная 2, Красная 3 – при необходимости пользователь отправляется в мерчант платежной системы;
- Зеленая 3 – Billing оповещает ИС об оплате;
- Красная 4 – Пользователь возвращается в Магазин;
- Зеленая 4 – При необходимости ИС запрашивает историю платежей в Billing.
2. Типы передаваемых данных 
Название |
Описание |
Диапазон значений |
Целое |
Целое |
От 0 до 2147483647 |
Длинное целое |
Длинное целое |
От 0 до 4294967296 |
Денежное |
Вещественное, разделитель целой и дробной части «.» (точка), разделителя разрядов нет, дробная часть с точностью до сотых. |
от 0.01 до 1000000.00 |
Строка |
Строка. Не может содержать символ «=» (равно) и символ «&» (амперсанд). |
- |
Дата время |
Всемирное координированное время (UTC). Представлено в формате yyyymmddhhnn где y – цифры для обозначения года, m – месяца, d – дня месяца, h – часа (hh – число от 0 до 23) n – минут. Например, 15 января 2010 17:04 201001151704 |
От 201001010000 до 205012312359 |
MD5 |
Строка, представляющая собой 32-разрядное число в 16-ричной форме и в верхнем регистре (всего 32 символа 0-9, A-F).
Алгоритм создания подписи данных.
- Пары Название-Значение всех параметров запроса (кроме PAYSTO_MD5) сортируются по Названию в алфавитном прямом порядке регистронезависимо.
- Название-Значения склеиваются в строку «Название=Значение&», полученные строки склеиваются в порядке установленном в п1.
- В конец полученной строки приклеивается значение секретного ключа (указывается при регистрации магазина).
Например, должно получиться «Название1=Значение1& Название2=Значение2&СекретныйКлюч»
- Если в кабинете включен «Режим совместимости md5», то из полученной строки удаляются все символы, зависящие от кодировок, т.е. удовлетворяющие регулярному выражению, указанному на странице настройки магазина.
- Вычисляется MD5 полученной в п3 строки в UTF8.
- Результат из п4 записывается строкой и переводится в верхний регистр.
|
|
Статус заявки |
Код статуса заявки. Возможные значеня:
- RES_RESERVED - сумма зарезервирована на счете;
- RES_WRITEOFF сумма списана, деньги отправлены;
- RES_PAYOUT_DONE выплата состоялась;
- RES_HOLD - заявка приостановлена;
- RES_CANCEL - заявка отменена, списанные деньги по заявке вернулись;
- RES_ERROR - при платеже произошли ошибки.
|
Смотри колонку «Описание». |
3. Обеспечение безопасности 
3.1. Запросы
Проверяется IP источника запроса (Billing проверяет опционально, если IP ИС указан в настройках кабинета). Подпись MD5 (обязательно).Счетчик запроса, делает невозможным получить ответ с данными при повторе запроса без увеличения номера и пересчета подписи (опционально, если указан). Обращаем внимание, текущие значения счетчика от ИС и от Billing разные. Настоятельно рекомендуется для запросов GET, особенно если возможны запросы, где остальные параметры не меняются (например, при запросе баланса).
3.2. Ответы Billing
Проверяйте SSL сертификат ответившего сервера.
3.3. Адреса отвечающих серверов
IP-адрес сервера |
95.213.209.218 |
95.213.209.219 |
95.213.209.220 |
95.213.209.221 |
95.213.209.222 |
4. Запросы 
4.1. Переход плательщика в Billing
Данный шаг начинает процедуру пополнения баланса через Billing.
Данные проходят через компьютер Плательщика. Сумма к получению и Id Плательщика проверяются на последующих шагах.
Элемент адреса |
Значение |
Протокол |
https |
Метод |
Get | Post |
Путь |
https://paysto.com/ru/upBalance |
Кодировка |
UTF8 |
Параметры
Название |
Описание |
Тип |
Обязательный |
PAYSTO_SHOP_ID |
Id магазина, выдается при регистрации магазина |
Целое |
Да |
PAYSTO_SUM |
Требуемая к получению сумма. Сумма должна быть в базовой валюте (которая была указана при регистрации). Может быть изменена плательщиком |
Денежное |
Нет |
PAYSTO_PAYER_ID |
Id плательщика в ИС. Может быть изменен плательщиком |
Строка до 50 символов. |
Нет |
PAYSTO_PAYER_EMAIL |
Email плательщика |
Строка до 50 символов. |
Нет |
PAYSTO_CURRENCY |
Id валюты (актуальный список доступных валют можно уточнить в отделе поддержки пользователей) |
Целое |
Нет |
PAYSTO_PERIOD |
Периодичность платежа в формате y.m.d где y-количество лет, m-количество месяцев, d- количество дней. Например, «0.1.14» - совершать платеж через месяц и 14 дней |
Строка |
Нет |
PAYSTO_DELIVERYTIME |
Срок доставки товара (пополнения счета). Указывает количество дней необходимое для доставки товара или пополнения счета. Минимальное значение 1. Если значение не передается, то оно будет взято из настроек проекта в кабинете пользователя системы PAYSTO. |
Целое |
нет |
4.2. Проверка ID плательщика 
Billing спрашивает у ИС о существовании ID плательщика.
Внимание! Магазин должен при данном запросе проверять IP, с которого пришел запрос (он должен быть IP Billing - узнайте в технической поддержке возможные значения), подпись.
Отказ от данных проверок может серьезно ослабить защиту от мошенников.
Элемент адреса |
Значение |
Протокол |
http | https |
Метод |
Post |
Путь |
Url указанный в настройках Получателя |
Кодировка |
UTF8 |
Параметры
Название |
Описание |
Тип |
Обязательный |
PAYSTO_PAYER_ID |
Id плательщика в ИС. |
Строка до 50 символов. |
Да |
PAYSTO_REQUEST_NO |
Счетчик запросов от Billing, каждое последующее значение больше предыдущего. |
Длинное целое |
Да |
PAYSTO_MD5 |
Подпись передаваемых данных. Контрольная сумма MD5 |
MD5 |
Да |
Ответы
HTTP CODE |
Значение (Content) |
Описание |
200 |
YES |
Id плательщика существует, и на него можно зачислять средства. Значение в верхнем регистре. |
200 |
Любое другое значение |
Отказать в приеме средств для этого Id Плательщика |
любой |
Timeout |
Считается, что ИС не доступна и не может выполнить свои обязательства перед Плательщиком. Платеж принят не будет. |
4.3. Оповещение ИС о платеже 
Billing оповещает ИС о принятии средств от Плательщика.
Внимание! Магазин должен при данном запросе проверять IP, с которого пришел запрос (он должен быть IP Paysto - узнайте в технической поддержке возможные значения), подпись.
Отказ от данных проверок может серьезно ослабить защиту от мошенников.
Следите за тем, что PAYSTO_PAYMENT_ID – уникальное значение. Перед увеличением баланса Плательщика убедитесь в том, что до этого, баланс на основании платежа с переданным PAYSTO_PAYMENT_ID не увеличивался.
Элемент адреса |
Значение |
Протокол |
http | https |
Метод |
Post |
Путь |
Url указанный в настройках Получателя |
Кодировка |
UTF8 |
Параметры
Название |
Описание |
Тип |
Обязательный |
PAYSTO_PAYER_ID |
Id плательщика в ИС |
Строка до 50 символов. |
Да |
PAYSTO_SUM |
Сумма, принятая от Плательщика в базовой валюте Клиента. |
Денежный |
Да |
PAYSTO_ACCOUNT_SUM |
Сумма на внутренний счет Paysto Клиенту |
Денежный |
Да |
PAYSTO_PAYMENT_ID |
Номер транзакции в PaySto |
Длинное целое |
Да |
PAYSTO_MD5 |
Подпись передаваемых данных. Контрольная сумма MD5 |
MD5 |
Да |
PAYSTO_TEST |
Тестовый ли платеж. Возможные значения: «1» - тестовый, «0» - нет |
|
Да |
Значения ответа
HTTP CODE |
Значение (Content) |
Описание |
200 |
YES |
Платеж зачислен. |
200 |
Любое другое значение |
Вернуть принятые средства для этого Id Плательщика |
любой |
Timeout |
Считается, что ИС не доступна и не может выполнить свои обязательства перед Плательщиком. Платеж не будет зачислен на счет Клиента, до выяснения обстоятельств. |
4.4. Список принятых платежей 
ИС запрашивает Billing о принятых средствах от Плательщиков.
Внимание! При запросе рекомендуется проверить SSL сертификат ответившего сервера для предотвращения DNS подлогов.
Максимальный период, задаваемый параметрами, FROM и TO 31 день.
Элемент адреса |
Значение |
Протокол |
https |
Метод |
Get | Post (рекомендуется) |
Путь |
https://paysto.com/api/upBalance/GetList |
Параметры
Название |
Описание |
Тип |
Обязательный |
FROM |
начало периода (по умолчанию – начало текущих суток). |
Дата время |
Да |
TO |
конец периода (по умолчанию – текущий момент). |
Дата время |
Да |
PAYSTO_SHOP_ID |
Id в Billing для ИС. Узнается из настроек в кабинете Клиента |
целое |
Да |
PAYSTO_REQUEST_NO |
Сквозной (общий для всех типов запросов) счетчик запросов ИС, каждое последующее значение должно быть больше предыдущего. |
Длинное целое |
Нет |
PAYSTO_MD5 |
Подпись передаваемых данных. Контрольная сумма MD5 |
MD5 |
Да |
Ответы
HTTP CODE |
Значение (Content) |
200 |
CSV файл в виде Datetime,PAYSTO_PAYMENT_ID,PAYSTO_PAYER_ID,PAYSTO_SUM,PAYSTO_ACCOUNT_SUM,PAYSTO_TEST |
403 |
Нарушены условия безопасности. Проверьте передаваемые параметры и настройки. |
404 |
Не найдена зарегистрированная ИС в Billing с переданным PAYSTO_SHOP_ID |
Описание столбцов
Название |
Описание |
Тип |
Datetime |
Дата и время регистрации заявки. |
Дата время |
PAYSTO_PAYMENT_ID |
Номер транзакции в PaySto |
Длинное целое |
PAYSTO_PAYER_ID |
Id плательщика в ИС. |
Строка до 50 символов |
PAYSTO_SUM |
Поступившая (в валюте Счета Клиента) или отправленная (в валюте Получателя) из PaySto сумма. |
Денежный |
PAYSTO_ACCOUNT_SUM |
Движение по Счету Клиента. Положительное – увеличение баланса, отрицательное – уменьшение баланса. |
|
PAYSTO_TEST |
Тестовый ли платеж. Возможные значения: «1» - тестовый, «0» - нет |
|
4.5. Проверка баланса 
Внимание! При данных запросах рекомендуется проверять SSL сертификат ответившего сервера для предотвращения DNS подлогов.
Элемент адреса |
Значение |
Протокол |
https |
Метод |
Get | Post (рекомендуется) |
Путь |
https://paysto.com/api/Common/Balance |
Параметры
Название |
Описание |
Тип |
Обязательный |
PAYSTO_SHOP_ID |
Id в Billing для ИС. Узнается из настроек в кабинете Клиента |
Целое |
Да |
PAYSTO_REQUEST_NO |
Сквозной (общий для всех типов запросов) счетчик запросов ИС, каждое последующее значение должно быть больше предыдущего. |
Длинное целое |
Нет |
PAYSTO_MD5 |
Подпись передаваемых данных. Контрольная сумма MD5. |
MD5 |
Да |
PAYSTO_TEST |
Тестового ли счета баланс. Возможные значения: «1» - тестовый, «0» - нет. Если не указан -воспринимается как «0» |
|
Нет |
Ответы
HTTP CODE |
Значение (Content) |
Тип |
200 |
Скалярное значение. Доступный баланс. |
Денежный |
403 |
Нарушены условия безопасности. Проверьте передаваемые параметры и настройки. |
|
404 |
Не найдена зарегистрированная ИС в Billing с переданным PAYSTO_SHOP_ID |
|
5. Рекуррентные (периодические) платежи 
Повторяющиеся платежи позволяют производить автоматическое списание с кредитной карты плательщика и зачисление на счет продавца денежных средств с заданной периодичность. При использовании этого способа оплаты необходимо в запросе 4.1 передать параметр PAYSTO_PERIOD. При формировании такого платежа в случае оплаты кредитной картой плательщику будет предложено автоматически осуществлять оплату с заданной периодичностью. В случае согласия плательщика в системе будет создана подписка по которой будет осуществляться списание с заданной периодичностью такой же суммы. Отменить подписку может как пользователь системы в кабинете пользователя, так и плательщик в кабинете плательщика.
ВНИМАНИЕ! Возможность использования повторяющихся платежей включается индивидуально для каждого проекта по запросу в службу поддержки.
6. Аппендикс 
6.1. Данные получаемые из интерфейса Клиентского Кабинета.
Рисунок 1 Определение PAYSTO_SHOP_ID - страница "Настройки магазина"

6.2. Тестирование 
Для тестирования используйте способ оплаты "Тестовый рубль" - включение и отключение производится в Карточке магазина.