Интеграция сервиса приёма платежей с помощью Payment Gateway API
Универсальный API для подключения платежных шлюзов обеспечивает единый протокол, с помощью которого вы можете с минимальными затратами времени и ресурсов подключить любой существующий платежный шлюз, используя одну универсальную схему подключения.
Содержание
Порядок подключения модуля PAYMENT GATEWAY API
Модуль PAYMENT GATEWAY API является дополнительным. Чтобы подключиться к Nemo.travel по данному протоколу, обратитесь в коммерческий отдел по адресу connect@nemo.travel
Особенности
Сервис не поддерживает фискализацию платежей.
Настройка платёжного шлюза в Nemo.Travel
- В разделе Финансы и платежи → Платежные методы → Доступ с способам оплаты откройте доступ к способу оплаты для пользователей/групп/компаний
- В разделе Финансы и платежи → Платежные методы → Управление шлюзами создайте метод оплаты "UniversalNemoPay"
- Откройте раздел "Реквизиты" созданного платёжного метода и задайте настройки доступа к платёжному шлюзу:
- 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.
Порядок взаимодействия Системы Немо и Сервиса
Оплата с преавторизацией
- При инициировании оплаты Система Немо отправляет Запрос регистрации заказа 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
Параметры запроса: 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 | Состояние заказа в платежной системе. |
|
cardAuthInfo | Тэг с атрибутами платежа. |
|