ONPAY Merchant API

Опубликовал: admin Пятница, Ноябрь 23, 2012 в категории AJAX, PHP | Пока нет комментариев

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

Чтобы позволить системе OnPay проверить действительность ID Клиента или ID заказа, за который платит Клиент, и получить извещение о полученном платеже, вам нужно:

активировать функцию "Уведомление по API" в разделе Мерчанта вашего профиля в OnPay;

выставить API URL в соответствии со скриптом API на вашем сервере;

установить секретный ключ для "уведомлений по API", который должен быть таким же, как в скрипте на вашем сервере, чтобы позволить генерацию подписей для проверок безопасности.

OnPay производит два вида запросов к API Мерчанта:

запрос "check" используется, чтобы получить разрешение от системы Мерчанта на прием платежа от Клиента. После удачного получения разрешения, OnPay одобрит платеж. С этого момента, если Клиент действительно производит платеж, Мерчант может видеть его в разделе "мой счет" на сайте OnPay;

запрос "pay" является, по сути, уведомлением для системы Мерчанта о том, что для него принят платеж. После получения уведомления, система Мерчанта может автоматически отправить заказанные товары или сервисы Клиенту.

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

клиент делает платеж Мерчанту;

OnPay отправляет "check" запрос в API Мерчанта, удостоверяясь, что система Мерчанта может (и разрешает) принять платеж;

система Мерчанта проверяет все параметры запроса (существуют ли в системе

ID Клиента и заказа, может ли Клиент платить и т. д.);

если API Мерчанта не позволяет перевод (любой итог, кроме получения кода 0

от системы Мерчанта) — платеж не будет принят от Клиента;

если API Мерчанта разрешает перевод (код 0) — OnPay разрешает Клиенту платить;

клиент производит оплату, OnPay сохраняет платеж со статусом "получен" и отправляет запрос типа "pay" в API Мерчанта с теми же параметрами, что и запрос "check", плюс ID платежа и дата/время момента, когда платеж был одобрен;

если API Мерчанта приняло уведомление (код 0), OnPay изменяет статус этого платежа с "получен" на "принят";

если API Мерчанта сообщает о некритичной ошибке, OnPay попробует известить API Мерчанта позже. OnPay будет посылать извещения с возрастающими временными интервалами, до тех пор пока API Мерчанта не примет уведомление или пока не пройдет 72 часа.

Платежи со статусами "получен" и "принят" могут быть просмотрены Мерчантом в разделе "Мой счет" на сайте OnPay. Мерчанты могут помечать платежи, как "принятые" вручную в разделе "Мой счет", если API не доступен.

Рис. 3.38. Схема обработки платежа

Схема обработки платежа (рис. 3.38) следующая:

клиент хочет оплатить заказ на сайте Мерчанта;

сайт Мерчанта перенаправляет Клиента (или Клиент просто переходит по ссылке на сайте Мерчанта) на платежную страницу системы OnPay (http://secure.onpay.ru/pay/{логин мерчанта});

клиент подтверждает сумму платежа и номер заказа на платежной странице системы OnPay и переходит на сайт Платежной системы (Webmoney, Yandex Money и т. п.);

когда Клиент успешно переводит свой платеж в Платежной системе, Платежная система автоматически уведомляет систему OnPay;

когда OnPay получает уведомление от Платежной системы, OnPay уведомляет об этом систему Мерчанта (по API и\или отправкой сообщений на e-mail администратора Мерчанта);

клиент может получить свой заказ от Мерчанта.

Параметры запросов

Параметры запросов OnPay в API Мерчанта приведены в табл. 3.4.

Таблица 3.4. Параметры запросов OnPay

Таблица 3.4 (окончание)

Формат даты/времени

Для определения даты OnPay использует один из форматов рекомендованных стандартом ISO8601:2000. Этот формат включен в "XML Schema Part 2: Datatypes" под именем dataTime:

MM-DDThh:mm:ss.fZZZZZ

Здесь:

YYYY — год, четыре цифры;

MM — месяц, две цифры (01 — Январь и т. д.);

DD — день, две цифры (от 01 до 31);

T — символ "T", верхний регистр;

hh — hours, две цифры (24-часовой формат, от 00 до 23);

mm — minutes, две цифры (от 00 до 59);

ss — seconds, две цифры (от 00 до 59);

f — от одной до шести цифр, доли секунды;

ZZZZZ — временная зона, в формате +чч:мм или –чч:мм от UTC. Установленный символ Z означает время UTC.

Примеры:

2006-03-24T19:00:00+03:00 — 19 часов 24 марта 2006 года, зона — UTC + 3 часа.

2006-03-24T16:00:00Z — та же дата, но в зоне UTC.

Формат подписи MD5 для "check"-запросов от системы OnPay: type;pay_for;order_amount;order_currency;secret_key_for_api_in Формат подписи MD5 для "pay"-запросов от системы OnPay:

type;pay_for;onpay_id;order_amount;order_currency;secret_key_for_api_in

Поддержка различных валют

Параметры order_amount и order_currency будут теми же, что и в ссылке для заказа на сайте Мерчанта, через которую Клиент отсылается на платежную страницу системы OnPay. Из этих параметров OnPay подсчитывает сумму платежа во всех других возможных валютах.

Параметры balance_amount и balance_currency — это реальная сумма в валюте, которая поступает на баланс Мерчанта.

При проверке заказа (чтобы убедиться, что заказ реально оплачивается требуемой суммой) необходимо сверять только order_amount и order_currency со стоимостью заказа в вашей системе. Параметры balance_amount и balance_currency обычно используются для уведомлений (отчетов).

Пример:

http://secure.onpay.ru/pay/merchant_login?pay_mode=fix&price=100¤cy= USD&pay_for=12

Ссылка с суммой заказа в 100 долларов США. Клиент платит в евро, курс обмена на момент создания заказа 1 долл. = 0,7658 евро. Сумма платежа в евро: 76,58 евро = 100 долл.

Система Мерчанта будет уведомлена о платеже со следующими параметрами:

order_amount=100;

order_currency=USD;

balance_amount=76.58;

balance_currency=EUR.

Когда Клиент платит той же валютой, которая указана в ссылке заказа, значения balance_amount и balance_currency будут такими же, как в order_amount и order_currency:

order_amount=100;

order_currency=USD;

balance_amount=100;

balance_currency=USD.

Примеры запросов типа "check"

Пример запроса от системы OnPay в систему Мерчанта иллюстрирует листинг 3.54.

Листинг 3.54

POST https://merchant_server/script order_amount=100.00 order_currency=USD

pay_for=123456 type=check md5=*

API Мерчанта отвечает системе OnPay, формат ответа XML приведен в листин-

ге 3.55.

Листинг 3.55

<?xml version="1.0" encoding="UTF-8"?>

<result>

<code>0</code>

<pay_for>123456</pay_for>

<comment>OK</comment>

<md5>*</md5>

</result>

Здесь:

code — код результата обработки операции;

comment — обычно это описание ошибки для внутреннего использования (например, протоколирования). Значение данного поля хранится в деталях платежа, в интерфейсе Мерчанта в OnPay;

md5 — MD5 подпись ответа системы Мерчанта для OnPay (не та же самая подпись, которая получена от OnPay!), cгенерированная из строки со следующими параметрами платежа: type;pay_for;order_amount; order_currency;code;secret_ key_api_in.

Ответ системы Мерчанта об ошибке обработки содержит листинг 3.56.

Листинг 3.56

<?xml version="1.0" encoding="UTF-8"?>

<result>

<code>2</code>

<pay_for>123456</pay_for>

<comment>User account doesn’t exist</comment>

<md5>*</md5>

</result>

Примеры запросов типа "pay"

Пример запроса от системы OnPay в систему Мерчанта иллюстрирует листинг 3.57.

Листинг 3.57

POST https://merchant_server/script onpay_id=12345

pay_for=123456 order_amount=100.00 order_currency=USD balance_amount=76.58 balance_currency=EUR exchange_rate=0.7658

paymentDateTime=2006-03-24T19:00:00+03:00 type=pay

md5=*

Ответ API системы Мерчанта системе OnPay содержит листинг 3.58.

Листинг 3.58

<?xml version="1.0" encoding="UTF-8"?>

<result>

<code>0</code>

<comment>OK</comment>

<onpay_id>12345</onpay_id>

<pay_for>123456</pay_for>

<order_id>98765</order_id>

<md5>*</md5>

</result>

Здесь:

onpay_id — ID транзакции (платежа), сохраненной в OnPay (должен быть таким же, как и в запросе от OnPay);

order_id — ID транзакции (заказа), сохраненный в системе Мерчанта (опциональный, для лучшего отслеживания платежей);

md5 — MD5 подпись ответа системы Мерчанта для OnPay (не та же самая подпись, которая получена от OnPay!), cгенерированная из строки со следующими параметрами платежа: type;pay_for;onpay_id;order_id; order_amount;order_ currency;code;secret_key_api_in.

Коды завершения операций API

Если API Мерчанта недоступно для "check"-запросов или возвращает какойлибо код кроме "0", OnPay не примет платеж от Клиента. Возможные коды завершения операции приведены в табл. 3.5.

Если API Мерчанта недоступно для "pay"-запросов, OnPay попробует достичь его повторяющимися запросами несколько раз в течение следующих 72 часов. Повторяющиеся запросы посылаются с увеличивающимися интервалами.

Пример запроса от OnPay в систему Мерчанта с ошибкой, возвращаемой из API

Мерчанта, приведен в листинге 3.59.

Листинг 3.59

POST https://merchant_server/script order_amount=100.00 order_currency=USD balance_amount=76.58 balance_currency=EUR exchange_rate=0.7658

pay_for=123456 type=check md5=*

Ответ API системы Мерчанта системе OnPay приведен в листинге 3.60.

Листинг 3.60

<?xml version="1.0" encoding="UTF-8"?>

<result>

<code>10</code>

<pay_for>123456</pay_for>

<comment>System in maintenance mode</comment>

<md5>*</md5>

</result>

Таблица 3.5. Возможные коды завершения операции

Таблица 3.5 (окончание)

Обработка повторных запросов

Если API Мерчанта получает запрос с тем же onpay_id, как в уже успешно сохраненной транзакции, то API Мерчанта возвращает результат предыдущего сохраненного запроса (обычно это код успешного завершения, 0), т. к. неудачные транзакции не должны сохраняться в системе Мерчанта (только в протоколах).

Пример ответа на повторный запрос системы OnPay к системе Мерчанта иллюстрирует листинг 3.61.

Листинг 3.61

<?xml version="1.0" encoding="UTF-8"?>

<result>

<code>0</code>

<comment>OK (существующая транзакция)</comment>

<onpay_id>123456</onpay_id>

<order_id>98765</order_id>

<md5>*</md5>

</result>

Источник: Петин В. А., Сайт на AJAX под ключ. Готовое решение для интернет-магазина. — СПб.: БХВ-Петербург, 2011. — 432 с.: ил. + CD-ROM — (Профессиональное программирование)

Похожие посты:

• 50 СПОСОБОВ ЗАСТАВИТЬ GOOGLE ЛЮБИТЬ ВАШ САЙТ (0)
• Оценка авторитетности контента (0)
• Влияние анкора ссылки (0)
• Принципы «любви» поисковой системы Google (0)
• Репутация (0)
• Тренога любви: Визуальная доступность, Релевантность и Репутация (0)
• Организация мировой информации (0)