API

Введение

Описание

API PAYSTO — программный комплекс для управления мультиканальной торговой инфраструктурой.

API PAYSTO полностью совместимо с API Authorize.net Secure Hosted Payment Form, что позволяет настроить интеграцию любого web-ресурса без значительных расходов и в короткий срок.

Назначение

API PAYSTO позволяет автоматизировать приём платежей и обработку online-заказов в России.

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

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

Упрощенная схема оплаты

Сплошные линии – обязательные
Точечные линии – опциональные.

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

1. Запрос на оплату;
2. Проверка товаров в каталоге PAYSTO;
3. Перевод плательщика на оплату;
4. Статус оплаты;
5. Формирование кассового чека;
6. Статус оплаты;
7. Возврат покупателя на сайт Поставщика;
8. Запрос статуса платежа;
9. Статус платежа.

Типы передаваемых данных

Название	Описание	Диапазон значений
Целое	Целое	От 0 до 2147483647
Длинное целое	Длинное целое	От 0 до 4294967296
Денежное	Вещественное, разделитель целой и дробной части «.» (точка), разделителя разрядов нет, дробная часть с точностью до сотых. Наличие точки и двух цифр после нее – обязательно. Например, 10 должно быть записано как 10.00, 10.123 должно быть записано как 11.12 или 11.13	от 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).

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

Запросы

Проверяется IP источника запроса. Подпись (обязательно).

Ответы PAYSTO

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

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

IP-адрес отвечающего сервера указан в ЛК PAYSTO > Параметры

Запросы для осуществления платежа

Запрос на оплату счета

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

Элемент адреса	Значение
Протокол	https
Метод	Post
Путь	Информация предоставлена в ЛК PAYSTO > Параметры
Кодировка	UTF8

Параметры

Название	Описание	Тип	Обязательный
x_description	Комментарий платежа	Строка	Да
x_login	Код магазина	Целое	Да
x_amount	Сумма к оплате	Денежное	Да
x_currency_code	Валюта суммы к оплате. Может принимать значения USD или RUB	Строка	Да
x_cart_currency	Валюта корзины магазина. Значения: USD, EUR или другое короткое название валюты. Передается при валюте корзины отличной от рублей (RUB) для отражения на страницах оплаты (сумма и валюта списания берутся из значений x_amount и x_currency_code).	Строка	Нет
x_line_item	Содержимое корзины для оплаты. Подробное описание значения поля приведено в таблице ниже.	Строка	Да
x_email	Электронный адрес покупателя	Строка	Нет
x_fp_sequence	Номер сделки назначенный магазином. Это может быть номер счета или любое другое случайное число.	Числовой	Да
x_fp_timestamp	UTC время в секундах, начиная с 1 января 1970	числовой	Да
x_fp_hash	Подпись сгенерированная с использованием алгоритма хеширования HMAC-MD5 с использованием полей x*login, x_fp_sequence, x_fp_timestamp, x_amount и x_currency_code разделенными знаком ^ Примеры подписи		Да
x_invoice_num	Номер счета в магазине	числовой	Да
x_first_name	Имя покупателя	Строка	Нет
x_last_name	Фамилия покупателя	Строка	Нет
x_address	Адрес покупателя	Строка	Нет
x_city	Город покупателя	Строка	Нет
x_state	Регион покупателя	Строка	Нет
x_country	Страна покупателя	Строка	Нет
x_ship_to_first_name	Имя контактного лица при доставке	Строка	Нет
x_ship_to_last_name	Фамилия контактного лица при доставке	Строка	Нет
x_phone	Контактный телефон	Строка	Нет
x_fax	Контактный факс	Строка	Нет
x_cust_id	Идентификатор покупателя в магазине	Строка	Нет
x_ship_to_address	Адрес доставки	Строка	Нет
x_ship_to_state	Регион доставки	Строка	Нет
x_ship_to_zip	Индекс адреса доставки	Строка	Нет
x_ship_to_country	Страна доставки	Строка	Нет
x_relay_response	Строка должна иметь значение «TRUE»	Строка	Да
x_relay_url	URL оповещения об оплате	Строка	Да

Пример строки: "11111^789^67897654^10.50^USD" 
Пример генерации подписи: 
Fingerprint = HMAC-MD5 ("11111^789^67897654^10.50^USD", "секретный\*ключ")

Поле x_line_item должно содержать одну строку из оплачиваемой корзины пользователя состоящую из нескольких элементов разделенных разделителем | . Количество передаваемых полей должно соответствовать количеству элементов в корзине.

Формат поля x_line_item

Название	Описание	Обязательный
Item ID	Идентификатор товара. Строка длинной до 31 символа	Да
item name	Название товара. Строка длинной до 31 символа	Да
item description	Описание товара. Строка длинной до 255 символов.	Да
item quantity	Количество. Должно быть положительным числом.	Да
item price (unit cost)	Стоимость единицы товара. Вещественное, разделитель целой и дробной части «.» (точка), разделителя разрядов нет, дробная часть с точностью до сотых. Наличие точки и двух цифр после нее – обязательно. Например, 10 должно быть записано как 10.00, 10.123 должно быть записано как 11.12 или 11.13	Да
item taxable	Облагается ли товар НДС. Возможные значения: TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0	Нет

Пример передаваемой корзины:

x_line_item=item1<|>golf balls<|><|>2<|>18.95<|>Y&
x_line_item=item2<|>golf bag<|>Wilson golf carry bag, red<|>1<|>39.99<|>Y&
x_line_item=item3<|>book<|>Golf for Dummies<|>1<|>21.99<|>Y&

Сведения об оплате

Данный шаг оповещает Магазин о результатах оплаты счета.

При данном запросе магазин должен проверять:

• IP-адрес, с которого пришел запрос;
• Номер счета;
• Сумму платежа;
• Подпись.

Отказ от данных проверок может серьезно ослабить защиту от мошенников.

Элемент адреса	Значение
Протокол	https
Метод	Post
Путь	Указывается в x_relay_url при передаче запроса на оплату
Кодировка	UTF8

Параметры

Название	Описание	Тип
x*response_code	Результат оплаты 1 – оплачено 2 – отклонено 3 – ошибка	Целое
x_trans_id	Номер платежа в PAYSTO	Длинное целое
x_invoice_num	Номер платежа в магазине	Целое
x_MD5_Hash	Подпись сгенерированная с использованием алгоритма хеширования MD5 с использованием секретного ключа и полей x_login, x_trans_id, x_amount Пример строки «секретный*ключ111119876543211.00»	MD5
x_amount	Сумма оплаты	Денежное
x_cust_id	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_first_name	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_last_name	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_address	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_city	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_state	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_zip	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_country	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_phone	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_fax	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_cust_id	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_email	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_first_name	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_last_name	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_address	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_city	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_state	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_zip	Значение равняется соответствующему параметру в запросе на оплату	Строка
x_ship_to_country	Значение равняется соответствующему параметру в запросе на оплату	Строка

Интерпретация ответа HTTP CODE 200	Интерпретация отсутствия ответа другие HTTP CODE, Timeout
Считается, что сервис магазин получил уведомление.	Считается, что сервис магазина не доступен и не может выполнить свои обязательства перед покупателем. Полученные деньги от покупателя будут заблокированы.

Возвращение Покупателя в Магазин

На данном шаге Покупатель возвращается в Магазин.

Данные этого запроса проходят через компьютер Покупателя и могут быть подделанными недобросовестным Покупателем. Поэтому не рекомендуется на страницах Success url и Fail Url устанавливать статус выставленному счету. Используйте для этого Result Url.

Рекомендуем Success url и Fail Url указывать адрес одной и той же страницы, где на основе сохраненных данных при обработке Result url (или, переспросив статус счета в PAYSTO) перенаправлять пользователя на итоговую страницу успешной (неуспешной) оплаты.

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

Элемент адреса	Значение
Протокол	https
Метод	Post
Путь	Указывается при регистрации магазина
Кодировка	UTF8

Параметры совпадают с описанным в пункте Сведения об оплате

Сведения о платежах

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

Выписка за период

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

Параметры

Название	Описание	Тип	Обязательный
FROM	начало периода (по умолчанию – начало текущих суток).	Дата время	Да
TO	конец периода (по умолчанию – текущий момент).	Дата время	Да
PAYSTO_SHOP_ID	ID магазина	целое	Да
PAYSTO_REQUEST_NO	Сквозной (общий для всех типов запросов) счетчик запросов ИС, каждое последующее значение должно быть больше предыдущего.	Длинное целое	Нет
PAYSTO_MD5	Подпись передаваемых данных. Контрольная сумма MD5.	MD5	Да

Значения ответа

HTTP CODE	Комментарий
200	CSV файл в виде Datetime,PAYSTO_PAYMENT_ID,PAYSTO_INVOICE_ID,PAYSTO_SUM,accountSum,status, statusNote Если за указанный период не было платежей – пустой файл

Описание столбцов

Название	Описание	Тип
Datetime	Дата и время регистрации заявки.	Дата время
PAYSTO_PAYMENT_ID	Номер транзакции в PAYSTO	Длинное целое
PAYSTO_INVOICE_ID	Переданный номер счета в магазине.	Строка до 50 символов
PAYSTO_SUM	Сумма заявки (сумма которую фактически собирались оплатить/уже оплатили)	Денежный
accountSum	Движение по Счету Клиента. Положительное – увеличение баланса, отрицательное – уменьшение баланса.	Денежный
status	Код статуса заявки.	Статус заявки
statusNote	Комментарий к статусу. Например, если статус RES_ERROR – то описание ошибки.	Строка

Значения ответа

HTTP CODE	Комментарий
403	Нарушены условия безопасности. Проверьте передаваемые параметры и настройки.
404	Не найден магазин

Сведения о платеже

Элемент адреса	Значение
Протокол	https
Метод	Get
Путь	https://paysto.com/api/Payment/GetByInvoiceId

Параметры

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

Значения ответа

HTTP CODE	Комментарий
200	CSV файл в виде Datetime,PAYSTO_PAYMENT_ID,PAYSTO_INVOICE_ID,PAYSTO_SUM,accountSum,status, statusNote

Описание столбцов

Название	Описание	Тип
Datetime	Дата и время регистрации заявки.	Дата время
PAYSTO_PAYMENT_ID	Номер транзакции в PAYSTO	Длинное целое
PAYSTO_INVOICE_ID	Переданный номер счета в магазине.	Строка до 50 символов
PAYSTO_SUM	Сумма заявки (сумма которую фактически собирались оплатить/уже оплатили)	Денежный
accountSum	Движение по Счету Клиента. Положительное – увеличение баланса, отрицательное – уменьшение баланса.	Денежный
status	Код статуса заявки.	Статус заявки
statusNote	Комментарий к статусу. Например, если статус RES_ERROR – то описание ошибки.	Строка

Значения ответа

HTTP CODE	Комментарий
403	Нарушены условия безопасности. Проверьте передаваемые параметры и настройки.
404	Не найден счет с таким номером для данного магазина

Состояние счета

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

Проверка баланса

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

Параметры

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

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

Аппендикс. Параметры подключения

Данные получаемые из интерфейса Личного Кабинета (требуется регистрация):

1. ID Магазина;
2. Адрес для API-запросов;
3. Адрес отвечающего сервера;
4. Секретный ключ (задается пользователем при подключении);