API onlineMerchant-FULLCART

Интерфейс приема оплаты для интернет-магазинов, когда необходимо получить оплату по сформированному счету/заказу, при этом сумма не может быть изменена плательщиком.
Данная версия интерфейса разработана специально для интернет-магазинов с большим ассортиментом товаров и предполагающих несколько позиций товаров в заказе.  Для приема оплаты за единичные товары (одна позиция в заказе), а также для "пополнения баланса в системе" (формирование суммы платежа на стороне проекта) рекомендуется использовать упрощенный интерфейс - NOCART.

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

Оглавление

  1. Введение
    1. Назначение
    2. Описание
    3. Термины и понятия
  2. Упрощенная схема оплаты счета магазина.
    1. Легенда
    2. Порядок шагов при успешной оплате
  3. Типы передаваемых данных
  4. Обеспечение безопасности
    1. Запросы
    2. Ответы onlineMerchant
    3. Адреса отвечающих серверов
  5. Запросы для осуществления платежа
    1. Запрос на оплату счета
    2. Сведения об оплате
    3. Возвращение Покупателя в Магазин
  6. Сведения о платежах
    1. Выписка за период
    2. Сведения об отправленном на оплату счете
  7. Состояние счета
    1. Проверка баланса
  8. Аппендикс
    1. Данные получаемые из интерфейса Клиентского Кабинета

 

1. Введение     

1.1 Назначение

onlineMerchant —программный комплекс, который позволяет автоматизировать процесс оплаты счетов в Интернете, выставленных Вашим web-сайтом.

1.2. Описание

Данный интрефейс полностью совместим с API authorize.net Secure Hosted Payment Form. Если Ваш магазин поддерживает это способ оплаты Вы без труда сможете перейти на использование PAYSTO, расширив таким образом количество способов оплаты на своем сайте.

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

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

 

2. Упрощенная схема оплаты счета магазина    

[image]

2.1. Легенда

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

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

  • Красная 1. – Пользователь отсылает форму оплаты в PAYSTO;
  • Красная 2, Красная 3 – при необходимости пользователь отправляется в мерчант платежной системы;
  • Зеленая 1 – PAYSTO оповещает Магазин об оплате;
  • Красная 4 – Пользователь возвращается в Магазин;
  • Зеленая 2 – При необходимости Магазин запрашивает статус счета в PAYSTO;

 

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

Название Описание Диапазон значений
Целое Целое От 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).  

 

 

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

4.1. Запросы

Проверяется IP источника запроса (upBalance проверяет опционально, если IP ИС указан в настройках кабинета). Подпись (обязательно).

4.2. Ответы onlineMerchant

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

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

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

 

 

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

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

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

Элемент адреса Значение
Протокол https
Метод Post
Путь https://paysto.com/ru/pay/AuthorizeNet
Кодировка UTF8

Параметры

Название Описание Тип Обязательный
x_description Комметнарий платежа Строка Да
x_login Код магазина Целое Да
x_amount Сумма к оплате Денежное Да
x_currency_code Валюта суммы к оплате. Может принимать значения USD или RUB Строка Да
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 разделенными знаком ^ Пример строки: "11111^789^67897654^10.50^USD" Пример генерации подписи: Fingerprint = HMAC-MD5 ("11111^789^67897654^10.50^USD",
"секретный_ключ")  
  Да
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 оповещения об оплате Строка Да

Поле 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&

 

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

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

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

Элемент адреса Значение
Протокол 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 Считается, что сервис магазина не доступен и не может выполнить свои обязательства перед покупателем. Полученные деньги от покупателя будут заблокированы.

 

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

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

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

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

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

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

Параметры

Название Описание Тип Обязательный
Все параметры из «Запрос на осуществление платежа»     Да
PAYSTO_PAYMENT_ID Номер транзакции в PAYSTO Длинное целое Да

 

 

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

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

 

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

Элемент адреса Значение
Протокол https | http
Метод 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 Нарушены условия безопасности. Проверьте передаваемые параметры и настройки.
Значения ответа HTTP CODE 404 Не найден магазин

 

  6.2. Сведения об отправленном на оплату счете    

Элемент адреса Значение
Протокол https
Метод Get | Post (рекомендуется)
Путь 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 Нарушены условия безопасности. Проверьте передаваемые параметры и настройки.
Значения ответа HTTP CODE 404 Не найден счет с таким номером для данного магазина

 

 

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

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

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

Элемент адреса Значение
Протокол 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 Не найден магазин  


8. Аппендикс     

8.1. Данные получаемые из интерфейса Клиентского Кабинета.  
Рисунок 1 Определение PAYSTO_SHOP_ID

[image]


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

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

Add Feedback