API upBalance - сбор платежей от пользователей (произвольная сумма)

Интерфейс приема платежей для интернет-проектов в виде пополнения на произвольную сумму внутреннего счета пользователя в системе клиента.
Разработан для проектов имеющих систему учета пользователей и прочих биллинговых систем.
 
Демонстрация работы интерфейса
 
Любые работы по подключению приема платежей на вашем сайте могут быть выполнены только специалистами с соответствующими знаниями в области программирования. Проведение работ на сайте без соответствующей подготовки может вызвать нарушения работы вашей веб-системы, включая полную или частичную потерю любых данных.  Перед началом проведения работ рекомендуется выполнить архивацию (back-up) всех данных вашей веб-системы, включая данные исполняемых файлов/скриптов.  Любые работы с вашим сайтом Вы производите на собственный страх и риск. Paysto не несет ответственность за любые повреждения или нарушения в работе вашего сайта, а также утрату данных.  Техническая поддержка по работе интерфейсов Paysto будет оказана только в части взаимодействия на стороне Paysto.
Техническая поддержка оказывается только через постановку тикета в соответствующий отдел. Создать тикет

 

  1. Введение
    1. Назначение
    2. Описание
    3. Термины и понятия
    4. Подготовительные работы
    5. Принцип работы
      1. Легенда
      2. Порядок шагов при успешной оплате
  2. Типы передаваемых данных
  3. Обеспечение безопасности
    1. Запросы
    2. Ответы upBalance
    3. Адреса отвечающих серверов
  4. Запросы
    1. Переход плательщика в upBalance
    2. Проверка ID плательщика
    3. Оповещение ИС о платеже
    4. Список принятых платежей
    5. Проверка баланса
  5. Рекуррентные (периодические) платежи
  6. Аппендикс
    1. Данные получаемые из интерфейса Клиентского Кабинета
    2. Тестирование

1. Введение    

1.1. Назначение

Прием платежей для пополнения счета/баланса. В отличие от onlineMerchant, с сайта Клиента приходит информация только об Id плательщика, а сумма и номер счета формируется на стороне upBalance.

1.2. Описание

Система представляет собой магазин, который формирует счета для оплаты в Paysto, и оповещает Клиента о приеме платежа. Взаимодействие с Paysto происходит посредством API Paysto для магазинов. Клиентские настройки для приема платежей происходят в кабинете Клиента Paysto в разделе «Настройки» → «Источники дохода». Информация о принятых платежах отображается в кабинете Клиента Paysto в разделе «Прием платежей» → «upBalance»

1.3. Термины и понятия

Термин Описание
Получатель upBalance Клиента, в пользу которого идет зачисление средств
Плательщик Лицо, осуществляющее платеж
ИС Информационная система Получателя

 

1.4. Подготовительные работы    

Порядок подключения проекта описан здесь.

 

1.5. Принцип работы

1.5.1. Легенда

  • Красные стрелки – переходы Плательщика;
  • Зеленые стрелки – запросы между upBalance и ИС;
  • Сплошные – обязательные;
  • Точечные – опциональные.

1.5.2. Порядок шагов при успешной оплате.

  • Красная 1. – Пользователь переходит в upBalance;
  • Зеленая 1, Зеленая 2 - PaySto запрашивает у ИС подтверждение Id Плательщика;
  • Красная 2, Красная 3 – при необходимости пользователь отправляется в мерчант платежной системы;
  • Зеленая 3 – upBalance оповещает ИС об оплате;
  • Красная 4 – Пользователь возвращается в Магазин;
  • Зеленая 4 – При необходимости ИС запрашивает историю платежей в upBalance.

 

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).  

Алгоритм создания подписи данных.

  1. Пары Название-Значение всех параметров запроса (кроме PAYSTO_MD5) сортируются по Названию в алфавитном прямом порядке регистронезависимо.
  2. Название-Значения склеиваются в строку «Название=Значение&», полученные строки склеиваются в порядке установленном в п1.
  3. В конец полученной строки приклеивается значение секретного ключа (указывается при регистрации магазина).
    Например, должно получиться «Название1=Значение1& Название2=Значение2&СекретныйКлюч»
  4. Если в кабинете включен «Режим совместимости md5», то из полученной строки удаляются все символы, зависящие от кодировок, т.е. удовлетворяющие регулярному выражению, указанному на странице настройки магазина.
  5. Вычисляется MD5 полученной в п3 строки в UTF8.
  6. Результат из п4 записывается строкой и переводится в верхний регистр.
 
Статус заявки

Код статуса заявки. Возможные значеня:

  • RES_RESERVED - сумма зарезервирована на счете;
  • RES_WRITEOFF сумма списана, деньги отправлены;
  • RES_PAYOUT_DONE выплата состоялась;
  • RES_HOLD - заявка приостановлена;
  • RES_CANCEL - заявка отменена, списанные деньги по заявке вернулись;
  • RES_ERROR - при платеже произошли ошибки.
Смотри колонку «Описание».

 

 

3. Обеспечение безопасности    

3.1. Запросы

Проверяется IP источника запроса (upBalance проверяет опционально, если IP ИС указан в настройках кабинета). Подпись MD5 (обязательно).Счетчик запроса, делает невозможным получить ответ с данными при повторе запроса без увеличения номера и пересчета подписи (опционально, если указан). Обращаем внимание, текущие значения счетчика от ИС и от upBalance разные. Настоятельно рекомендуется для запросов GET, особенно если возможны запросы, где остальные параметры не меняются (например, при запросе баланса).

3.2. Ответы upBalance

Проверяйте SSL сертификат ответившего сервера.

3.3. Адреса отвечающих серверов

IP-адрес сервера
23.102.21.72
137.135.207.41
23.102.17.162

 

4. Запросы    

4.1. Переход плательщика в upBalance

Данный шаг начинает процедуру пополнения баланса через upBalance.

Данные проходят через компьютер Плательщика. Сумма к получению и 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 плательщика    

upBalance спрашивает у ИС о существовании ID плательщика.

Внимание! Магазин должен при данном запросе проверять IP, с которого пришел запрос (он должен быть IP upBalance - узнайте в технической поддержке возможные значения), подпись.
Отказ от данных проверок может серьезно ослабить защиту от мошенников.

Элемент адреса Значение
Протокол http | https
Метод Post
Путь Url указанный в настройках Получателя
Кодировка UTF8

Параметры

Название Описание Тип Обязательный
PAYSTO_PAYER_ID Id плательщика в ИС. Строка до 50 символов. Да
PAYSTO_REQUEST_NO Счетчик запросов от upBalance, каждое последующее значение больше предыдущего. Длинное целое Да
PAYSTO_MD5 Подпись передаваемых данных. Контрольная сумма MD5 MD5 Да

Ответы

HTTP CODE Значение (Content) Описание
200 YES Id плательщика существует, и на него можно зачислять средства. Значение в верхнем регистре.
200 Любое другое значение Отказать в приеме средств для этого Id Плательщика
любой Timeout Считается, что ИС не доступна и не может выполнить свои обязательства перед Плательщиком. Платеж принят не будет.

 

4.3. Оповещение ИС о платеже    

upBalance оповещает ИС о принятии средств от Плательщика.

Внимание! Магазин должен при данном запросе проверять IP, с которого пришел запрос (он должен быть IP upBalance - узнайте в технической поддержке возможные значения), подпись.
Отказ от данных проверок может серьезно ослабить защиту от мошенников.

Следите за тем, что 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. Список принятых платежей    

ИС запрашивает upBalance о принятых средствах от Плательщиков.

Внимание! При запросе рекомендуется проверить SSL сертификат ответившего сервера для предотвращения DNS подлогов.

Максимальный период, задаваемый параметрами, FROM и TO 31 день.

Элемент адреса Значение
Протокол https
Метод Get | Post (рекомендуется)
Путь https://paysto.com/api/upBalance/GetList

Параметры

Название Описание Тип Обязательный
FROM начало периода (по умолчанию – начало текущих суток). Дата время Да
TO конец периода (по умолчанию – текущий момент). Дата время Да
PAYSTO_SHOP_ID Id в upBalance для ИС. Узнается из настроек в кабинете Клиента целое Да
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 Не найдена зарегистрированная ИС в upBalance с переданным 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 в upBalance для ИС. Узнается из настроек в кабинете Клиента Целое Да
PAYSTO_REQUEST_NO Сквозной (общий для всех типов запросов) счетчик запросов ИС, каждое последующее значение должно быть больше предыдущего. Длинное целое Нет
PAYSTO_MD5 Подпись передаваемых данных. Контрольная сумма MD5. MD5 Да
PAYSTO_TEST Тестового ли счета баланс. Возможные значения: «1» - тестовый, «0» - нет. Если не указан -воспринимается как «0»   Нет

Ответы

HTTP CODE Значение (Content) Тип
200 Скалярное значение. Доступный баланс. Денежный
403 Нарушены условия безопасности. Проверьте передаваемые параметры и настройки.  
404 Не найдена зарегистрированная ИС в upBalance с переданным PAYSTO_SHOP_ID  

 

5. Рекуррентные (периодические) платежи    

Повторяющиеся платежи позволяют производить автоматическое списание с кредитной карты плательщика и зачисление на счет продавца денежных средств с заданной периодичность. При использовании этого способа оплаты необходимо в запросе 4.1 передать параметр PAYSTO_PERIOD. При формировании такого платежа в случае оплаты кредитной картой плательщику будет предложено автоматически осуществлять оплату с заданной периодичностью. В случае согласия плательщика в системе будет создана подписка по которой будет осуществляться списание с заданной периодичностью такой же суммы. Отменить подписку может как пользователь системы в кабинете пользователя, так и плательщик в кабинете плательщика.

ВНИМАНИЕ! Возможность использования повторяющихся платежей включается индивидуально для каждого проекта по запросу в службу поддержки.

 

6. Аппендикс    

6.1. Данные получаемые из интерфейса Клиентского Кабинета.

Рисунок 1 Определение PAYSTO_SHOP_ID

 

6.2. Тестирование    

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


 
ДРУГИЕ ИНТЕРФЕЙСЫ PAYSTO
OnlineMerchant - для магазинов
UpBalance - для биллинговых систем
PaymentGate - для массовых выплат
LinkCharge - удаленное высталение счетов на оплату
FundingTo - сбор средств и коллективное финансирование
ActivateTo - активация кодов
Общее - способы оплаты, курсы, тарифы, настройки
B2B - удаленное создание и управление магазинами/аккаунтами
 

Если у Вас возникли вопросы, обратитесь в службу поддержки PAYSTO.

Add Feedback