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

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

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

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

Особенности

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

Настройка платёжного шлюза в Nemo.Travel

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

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

Используемые в разделе термины:

• Система Немо - система бронирования Nemo Travel,
• Сервис - сервис по приему платежей.

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

Название запроса	Описание	Особенности
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.

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

Оплата с преавторизацией

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

Оплата без преавторизации

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

Возврат средств

Для возврата средств Система Немо направляет getOrderStatusExtended.do.

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

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

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

• register.do

Параметры запроса: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams

Название параметра	Описание	Особенности
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"}

Параметры ответа: orderId, formUrl, errorCode, errorMessage.

Название параметра	Описание	Особенности
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-
formUrl	URL платежной формы, на который надо перенаправить браузер клиента.	-
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-

• registerPreAuth.do

Параметры запроса: userName, password, orderNumber, amount, returnUrl, currency, description, language, jsonParams

Название параметра	Описание	Особенности
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"}

Параметры ответа: orderId, formUrl, errorCode, errorMessage.

Название параметра	Описание	Особенности
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-
formUrl	URL платежной формы, на который надо перенаправить браузер клиента.	-
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-

• deposit.do

Параметры запроса: userName, password, orderId, amount.

Название параметра	Описание	Особенности
userName	API логин	Логин магазина, полученный при подключении
password	Пароль	Пароль магазина, полученный при подключении
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-
amount	Сумма к оплате	Сумма платежа в копейках (или центах)

Параметры ответа: errorCode, errorMessage.

Название параметра	Описание	Особенности
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-

• reverse.do

Параметры запроса: userName, password, orderId.

Название параметра	Описание	Особенности
userName	API логин	Логин магазина, полученный при подключении
password	Пароль	Пароль магазина, полученный при подключении
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-

Параметры ответа: errorCode, errorMessage.

Название параметра	Описание	Особенности
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-

• refund.do

Параметры запроса: userName, password, orderId.

Название параметра	Описание	Особенности
userName	API логин	Логин магазина, полученный при подключении
password	Пароль	Пароль магазина, полученный при подключении
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-

Параметры ответа: errorCode, errorMessage.

Название параметра	Описание	Особенности
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-

• getOrderStatusExtended.do

Параметры запроса: userName, password, orderId, language, orderNumber.

Название параметра	Описание	Особенности
userName	API логин	Логин магазина, полученный при подключении
password	Пароль	Пароль магазина, полученный при подключении
orderId	Номер заказа в платежной системе. Уникален в пределах системы.	-
orderNumber	Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы	Номер биллинга
language	Язык в кодировке ISO 639-1.	Пример: "ru".

Параметры ответа: errorCode, errorMessage, orderStatus и cardAuthInfo(expiration, cardholderName, approvalCode, pan).

Название параметра	Описание	Особенности
errorCode	Код ошибки.	Любое значение отличное от "0" воспринимается нашей системой как неуспешный ответ.
errorMessage	Описание ошибки на языке, переданном в параметре language в запросе.	-
orderStatus	Состояние заказа в платежной системе.	0 - Заказ зарегистрирован, но не оплачен 1 - Предавторизованная сумма захолдирована (для двухстадийных платежей) 2 - Проведена полная авторизация суммы заказа 6 - Авторизация отклонена
cardAuthInfo	Тэг с атрибутами платежа.	expiration - Срок истечения действия карты в формате YYYYMM. cardholderName - Имя держателя карты. approvalCode - Код авторизации платежа. Поле фиксированной длины (6 символов), может содержать цифры и латинские буквы. pan - Маскированный номер карты, которая использовалась для оплаты.

См.также

Платежный шлюз