Просмотр кода страницы Интеграция сервиса приёма платежей с помощью Payment Gateway API

[[Категория:Модули]]
[[Категория:Дополнительные модули‎]]
Payment Gateway API представляет собой протокол для подключения платежных шлюзов. Сервис позволяет с минимальными затратами времени и ресурсов подключить любой существующий платежный шлюз, используя единую схему подключения. Преимущество метода в том, что работы по разработке интеграции заказчик выполняет на своей стороне, а значит, самостоятельно планирует сроки интеграции и независимо управляет ресурсом.


=Порядок подключения модуля Payment Gateway API=

Модуль Payment Gateway API является дополнительным. Чтобы подключиться к Nemo.travel по данному протоколу, обратитесь в коммерческий отдел по адресу connect@nemo.travel

Для подключения платёжного сервиса по представленному методу агентству необходимо:

# Создать тикет в проектном трекере {{NameSystem}} на подключение сервиса. Тикет будет передан сотрудниками технической поддержки в коммерческий отдел для согласования условий подключения и эксплуатации сервиса. После согласования будет открыт доступ к сервису "UniversalNemoPay" в разделе "Доступ к способам оплаты" (доступно только администраторам системы {{NameSystem}} )
# Провести интеграцию с {{NameSystem}} по протоколу Payment Gateway API, используя техническую документацию по интеграции ([[Интеграция сервиса приёма платежей с помощью Payment Gateway API#Техническая документация по интеграции с сервисом Payment Gateway API|Техническая документация по интеграции с сервисом Payment Gateway API]])
# Выполнить настройку метода оплаты ([[Интеграция сервиса приёма платежей с помощью Payment Gateway API#Настройка платёжного шлюза в {{NameSystem}}|Настройка платёжного шлюза]]) и сообщить в тикете реквизиты для взаимодействия {{NameSystem}} и платёжного шлюза (комплект: URL, логин, пароль) для завершения настройки платёжного метода технической поддержкой {{NameSystem}}
# Протестировать подключение перед началом боевой эксплуатации
# Сообщить в тикете о готовности перехода в продуктовый режим. Предоставить контакты службы поддержки сервиса по приёму платежей и тестовые реквизиты для дальнейшей поддержки сервиса


==Особенности==
Сервис не поддерживает фискализацию платежей по ФЗ 54.

==Настройка платёжного шлюза в {{NameSystem}}==

# В разделе '''Финансы и платежи → Платежные методы → Доступ к способам оплаты''' откройте доступ к способу оплаты UniversalNemoPay для пользователей/групп/компаний (подробнее о настройке см. [[Платежные методы в Nemo.travel]])
# В разделе '''Финансы и платежи → Платежные методы → Управление шлюзами''' создайте метод оплаты "UniversalNemoPay" (подробнее о настройке см. [[Платежные методы в Nemo.travel]])
# Откройте раздел "Реквизиты" созданного платёжного метода и задайте настройки доступа к платёжному шлюзу (подробнее о настройке см. [[Платежные методы в Nemo.travel]]):
#* ''URL клиентского сервера для запросов'' - адрес запросов для доступа к Сервису, например http://test.com/test
#* ''API логин'' - реквизит доступа к платёжному шлюзу, выдаётся платёжным шлюзом
#* ''Пароль'' - реквизит доступа к платёжному шлюзу, выдаётся платёжным шлюзом
#* ''Валюта'' - валюта по договору с платёжным шлюзом
#* ''Использовать двухстадийную оплату'' - если параметр включен, будет использована схема запросов с преавторизацией. Если выключен - схема запросов без преавторизации.
#* ''Разрешить оплату только картами Visa Electron и MasterCard Maestro''
#* ''Добавить локатор в начало идентификатора платежа при передаче в платежный шлюз'' - в orderNumber будет добавлен префикс с локатором.
#* ''Отображать фрэйм со страницей оплаты на странице информации о заказе '' - для оплаты во фрейме на странице заказа без перехода на странцу платёжного шлюза
#* ''Высота фрэйма со страницей оплаты'' - задайте высоту фрейма

=Техническая документация по интеграции с сервисом Payment Gateway API=

'''Используемые в разделе термины:''' 
*''Система Немо'' - система бронирования Nemo Travel,
*''Сервис'' - сервис по приему платежей.


==Описание запросов==

{| class="wikitable"
! Название запроса !! Описание !! Особенности
|-
| register.do || Запрос  регистрации заказа (без преавторизации)|| -
|-
| registerPreAuth.do || Запрос регистрации заказа c преавторизацией || -
|-
| deposit.do || Запрoс завершения oплаты заказа || -
|-
| reverse.do || Запрос отмены оплаты заказа || -
|-
| refund.do || Запрос возврата средств оплаты заказа || -
|-
| getOrderStatusExtended.do ||  Расширенный запрос состояния заказа || -
|-
|}

* Запросы, использующиеся при двухстадийной оплате (с преавторизацией): registerPreAuth.do, deposit.do.
* Запросы, использующиеся при одностадийной оплате (без преавторизации): register.do.
* Запросы reverse.do, refund.do и getOrderStatusExtended.do могут быть использованы при любой схеме оплаты.
* При необходимости возврата средств система Немо посылает запрос обновления заказа в платежный шлюз. Если полученный статус заказа - orderStatus=1, то посылается запрос reverse.do, если orderStatus=2, то посылается refund.do.

==Порядок взаимодействия Системы Немо и Сервиса==

===Оплата с преавторизацией===
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа registerPreAuth.do.
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
#Периодически Система Немо отправляет запрос getOrderStatusExtended.do для получения состояния заказа до тех пор, пока Сервис не укажет в качестве orderStatus 1 или 6 при нулевом значении errorCode. При получении orderStatus = 6 процедура оплаты в Системе Немо завершается как неуспешная. Если orderStatus =1, процедура продолжается.
#Параллельно с завершением транзакции Сервис переадресует клиента обратно на страницу заказа (returnUrl в запросе registerPreAuth.do). В результате операции Система Немо дополнительно направляет запрос getOrderStatusExtended для получения актуального статуса оплаты. При получении orderStatus = 6 процедура оплаты в Системе Немо завершается как неуспешная. Если orderStatus =1, процедура продолжается.
#Система Немо выполняет оформление заказа.
##Если оформление прошло успешно, Система Немо инициирует запрос deposit.do для завершения операции эквайринга на стороне Сервиса;
##Если оформление прошло неуспешно, Система Немо инициирует запрос reverse.do;
#Процедура оплаты завершена.

===Оплата без преавторизации===
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа register.do.	 
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
#Периодически Система Немо отправляет запрос getOrderStatusExtended.do для получения состояния заказа до тех пор, пока Сервис не укажет в качестве orderStatus 2 или 6 при нулевом значении errorCode. При получении orderStatus = 6 процедура оплаты в Системе Немо завершается как неуспешная. Если orderStatus =2, процедура продолжается.
#Параллельно с завершением транзакции Сервис переадресует клиента обратно на страницу заказа (returnUrl в запросе register.do). В результате операции Система Немо дополнительно направляет запрос getOrderStatusExtended для получения актуального статуса оплаты.
#Если orderStatus=2 и errorCode=0, Система Немо выполняет оформление заказа.

===Возврат средств===
Для возврата средств Система Немо направляет getOrderStatusExtended.do.
*Если полученный статус заказа orderStatus=1, то Система Немо направляет запрос reverse.do, 
*Если orderStatus=2, то Система Немо направляет запрос refund.do.

==Формат запросов/ответов==

Универсальный API для подключения платежных шлюзов реализован с помощью HTTP запросов/ответов методом POST.

* register.do
<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderNumber || Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы || Номер биллинга
|-
| amount || Сумма к оплате || Сумма платежа в копейках (или центах)
|-
| returnUrl || Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Значение должно представлять собой абсолютную ссылку. || Пример: "http://test.com/universal_nemo_pay__after_authorisation?billing_id=111111111".
|-
| currency || Валюта || Код валюты платежа ISO 4217.
|-
| description || Описание заказа в свободной форме || Пример: "Оплата заказа №586578 (1X96WD) с сайта http://test.com".
|-
| language || Язык в кодировке ISO 639-1. || Пример: "ru".
|-
| jsonParams || Блок для передачи дополнительных параметров мерчанта.  || Пример данных передаваемых Немо: {"onlyMaestro":"false","email":"test@mutelab.com","phone":"79270099000"}
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: orderId, formUrl, errorCode, errorMessage.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
| formUrl || URL платежной формы, на который надо перенаправить браузер клиента. || -
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
|}
</div></div>

* registerPreAuth.do
<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderNumber || Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы || Номер биллинга
|-
| amount || Сумма к оплате || Сумма платежа в копейках (или центах)
|-
| returnUrl || Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Значение должно представлять собой абсолютную ссылку. || Пример: "http://test.com/universal_nemo_pay__after_authorisation?billing_id=111111111".
|-
| currency || Валюта || Код валюты платежа ISO 4217.
|-
| description || Описание заказа в свободной форме || Пример: "Оплата заказа №586578 (1X96WD) с сайта http://test.com".
|-
| language || Язык в кодировке ISO 639-1. || Пример: "ru".
|-
| jsonParams || Блок для передачи дополнительных параметров мерчанта.  || Пример данных передаваемых Немо: {"onlyMaestro":"false","email":"test@mutelab.com","phone":"79270099000"}
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: orderId, formUrl, errorCode, errorMessage.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
| formUrl || URL платежной формы, на который надо перенаправить браузер клиента. || -
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
|}
</div></div>

* deposit.do

<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderId, amount.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
| amount || Сумма к оплате || Сумма платежа в копейках (или центах)
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: errorCode, errorMessage.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
|}
</div></div>

* reverse.do

<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderId.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: errorCode, errorMessage.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
|}
</div></div>

* refund.do

<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderId.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: errorCode, errorMessage.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
|}
</div></div>

* getOrderStatusExtended.do

<div class="toccolours mw-collapsible mw-collapsed">
Параметры запроса: userName, password, orderId, language, orderNumber.
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| userName || API логин  || Логин магазина, полученный при подключении
|-
| password || Пароль || Пароль магазина, полученный при подключении
|-
| orderId || Номер заказа в платежной системе. Уникален в пределах системы.   || -
|-
| orderNumber || Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы || Номер биллинга
|-
| language || Язык в кодировке ISO 639-1. || Пример: "ru".
|-
|}
</div></div>

<div class="toccolours mw-collapsible mw-collapsed">
Параметры ответа: errorCode, errorMessage, orderStatus и cardAuthInfo(expiration, cardholderName, approvalCode, pan).
<div class="mw-collapsible-content">
{| class="wikitable"
! Название параметра !! Описание !! Особенности
|-
| errorCode || Код ошибки. || Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
|-
| errorMessage || Описание ошибки на языке, переданном в параметре language в запросе. || -
|-
| orderStatus  || Состояние заказа в платежной системе. || 
* 0 - Заказ зарегистрирован, но не оплачен
* 1 - Предавторизованная сумма захолдирована (для двухстадийных платежей)
* 2 - Проведена полная авторизация суммы заказа
* 6 - Авторизация отклонена
|-
| cardAuthInfo || Тэг с атрибутами платежа. ||
* expiration - Срок истечения действия карты в формате YYYYMM.
* cardholderName - Имя держателя карты.
* approvalCode - Код авторизации платежа. Поле фиксированной длины (6 символов), может содержать цифры и латинские буквы.
* pan - Маскированный номер карты, которая использовалась для оплаты.
|-
|}
</div></div>

=См.также=
*[[Платежный шлюз]]
*[[Платежные методы в Nemo.travel]]