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

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

Здесь и далее:

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

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

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

Настройка шлюза

Доступные настройки:

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

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

Название запроса	Описание	Особенности
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 - Маскированный номер карты, которая использовалась для оплаты.