Общая информация по API

Определения

Продавец (он же мерчант) – пользователь системы Onpay.ru (интернет-магазин, НКО, ИП и т.п.) обладающий правами получать платежи от третьих лиц через систему Onpay.ru
Клиент – любой пользователь системы Продавца, желающий переводить деньги Продавцу через систему Onpay.ru (покупка товаров и услуг, благотворительные пожертвования и проч.)

Подключение API

Для включения работы по API, Вам нужно:
1. Активировать функцию “Уведомление по API” в разделе Настройки Магазина в Кабинете Продавца Onpay
2. Указать API URL в соответствии со скриптом API на Вашем сервере.
3. Установить секретный ключ для “уведомлений по API”, который должен быть таким же, как в скрипте на Вашем сервере, чтобы позволить генерацию контрольных подписей.

Разрешается использование параметров в указываемом API URL, по которому будут приходить уведомления. При этом накладывается ограничение в виде списка зарезервированных API Onpay параметров, которые запрещается использовать в API URL настроек магазина. Список зарезервированных параметров прилагается:
onpay_id
pay_for
order_amount
order_currency
balance_amount
balance_currency
exchange_rate
type
comment
paymentDateTime
md5\\

Описание и очередность транзакций

Onpay.ru производит 2 вида запросов к системе Продавца через API:
1. Запрос “check” используется, чтобы получить разрешение от системы Продавца на прием платежа от Клиента. После удачного получения разрешения, Onpay.ru одобрит платёж. С этого момента, если Клиент действительно производит платёж, Продавец может видеть его во вкладке “Платежи” в Кабинете Продавца.
2. Запрос “pay” является, по сути, уведомлением для системы Продавца, о том, что для него принят платеж. После получения уведомления, система Продавца может автоматически отправить заказанные товары или сервисы Клиенту.
Очередность транзакции:
1. Клиент переходит по платежной ссылке на форму Onpay и заполняет данные(если необходимо).
2. Onpay.ru отправляет “check” запрос в адрес Продавца, удостоверяясь, что система Продавца может (и разрешает) принять платёж. Система Продавца проверяет все параметры запроса (существуют ли в системе ID Клиента и заказа, может ли Клиент платить и т.д.).
a. Если система Продавца не позволяет перевод (любой итог, кроме получения кода 0 от системы Продавца) – платёж не будет принят от Клиента.
b. Если API Продавца разрешает перевод (код 0) – Onpay разрешает Клиенту платить.
3. Клиент производит оплату
4. Onpay сохраняет платёж со статусом “Получен” и отправляет запрос типа “pay” в систему Продавца с теми же параметрами, что и запрос “check”, плюс ID платежа и дата/время момента, когда платёж был одобрен.
a. если система Продавца приняла уведомление (код 0) – Onpay.ru изменяет статус этого платежа с “Получен” на “Принят”
b. если система Продавца сообщает о некритичной ошибке – Onpay.ru попробует известить систему Продавца позже. Onpay.ru будет посылать извещения с возрастающими временными интервалами, до тех пор пока система Продавца не примет уведомление или пока не пройдёт 72 часа.
Платежи со статусами “получен” и “принят” могут быть просмотрены во вкладке “Платежи” в Кабинете Продавца Onpay.ru.
Продавцы могут помечать платежи, как “Принятые” вручную во вкладке “Платежи” если API не доступен.
Onpay.ru имеет несколько типов АПИ:
1. Основное АПИ (версия 2.0). В Кабинете продавца выбран по умолчанию (поле селектора на HTTPS 2.0). 2. API 1.0. Старое апи. С этим АПИ, в частности, работают все загружаемые модули с onpaysolutions.ru
3. Специальное АПИ для Insales (его настройка описана отдельно)
4. Гибридные АПИ для упрощения миграции (переход с Робокассы и Интеркассы)

Описание API (2.0)

Старое API (1.0)

API Insales

Миграция с Интеркассы

Миграция с Робокассы

Справочная информация

Недоступность сервера магазина

Если сервер магазина недоступен для “check” запроса или возвращает НЕположительный ответ, система Onpay не примет платёж от Клиента.

Если сервер магазина недоступен для “pay” запроса, система Onpay будет повторно отправлять запрос несколько раз в течение следующих 72 часов. Повторяющиеся запросы посылаются с увеличивающимися интервалами. При этом платеж будет зачислен на счет магазина.

Возвращаемые ошибки

На стороне сервера Onpay в зависимости от ответа сервера магазина могут быть сгенерированы следующие ошибки (и в дальнейшем показаны в личном кабинете):

7.1.1. С сервером магазина нет соединения. http://wiki.onpay.ru/doku.php?id=oshibki#7.1.1
7.1.2. Платеж отклонен получателем. http://wiki.onpay.ru/doku.php?id=oshibki#7.1.2
7.1.3. Ошибка авторизации - подпись не совпадает. http://wiki.onpay.ru/doku.php?id=oshibki#7.1.3
7.1.4. Магазин возвращает неверные данные - pay_for не совпадает. http://wiki.onpay.ru/doku.php?id=oshibki#7.1.4
7.1.5. Магазин возвращает неверные данные - неверное значение поля (code). http://wiki.onpay.ru/doku.php?id=oshibki#7.1.5
7.2.1. С сервером мерчанта нет соединения. http://wiki.onpay.ru/doku.php?id=oshibki#7.2.1
7.2.2. Ошибка авторизации - подпись не совпадает. http://wiki.onpay.ru/doku.php?id=oshibki#7.2.2
7.2.3. Магазин возвращает неверные данные - pay_for не совпадает. http://wiki.onpay.ru/doku.php?id=oshibki#7.2.3
7.3.1. Магазин возвращает данные в некорректном формате (требуется XML или упрощенный текстовый формат). http://wiki.onpay.ru/doku.php?id=oshibki#7.3.1
7.3.2. Магазин возвращает неверные данные - отсутствует обязательный параметр (code). http://wiki.onpay.ru/doku.php?id=oshibki#7.3.2
7.3.3. Магазин возвращает неверные данные - отсутствует обязательный параметр (pay_for). http://wiki.onpay.ru/doku.php?id=oshibki#7.3.3
7.3.4. Магазин возвращает неверные данные - отсутствует обязательный параметр (md5). http://wiki.onpay.ru/doku.php?id=oshibki#7.3.4
7.3.5. Ошибка в параметрах запроса. http://wiki.onpay.ru/doku.php?id=oshibki#7.3.5
7.3.6. Ошибка авторизации. http://wiki.onpay.ru/doku.php?id=oshibki#7.3.6
7.3.7. Временная ошибка. http://wiki.onpay.ru/doku.php?id=oshibki#7.3.7
7.2.5. Если возвращен код отличный от 0, сообщение ошибки берется из поля «comment».