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

Материал из Центр поддержки системы бронировании
Версия от 11:29, 8 апреля 2020; Мария Горшенева (обсуждение | вклад) (→‎Настройка платёжного шлюза в {{NameSystem}})
Перейти к навигации Перейти к поиску

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


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

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

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

  1. Оставить заявку на подключение в коммерческий отдел Nemo.Travel по адресу connect@nemo.travel, подписать документы на эксплуатацию сервиса
  2. Создать тикет в проектном трекере Nemo.Travel на подключение сервиса
  3. Провести интеграцию с Nemo.Travel по протоколу Payment Gateway API, используя техническую документацию по интеграции (Техническая документация по интеграции с сервисом Payment Gateway API)
  4. Выполнить настройку метода оплаты (Настройка платёжного шлюза)
  5. Протестировать подключение перед началом боевой эксплуатации

Особенности

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

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

  1. В разделе Финансы и платежи → Платежные методы → Доступ с способам оплаты откройте доступ к способу оплаты UniversalNemoPay для пользователей/групп/компаний (подробнее о настройке см. Платежные методы в Nemo.travel)
  2. В разделе Финансы и платежи → Платежные методы → Управление шлюзами создайте метод оплаты "UniversalNemoPay" (подробнее о настройке см. Платежные методы в Nemo.travel)
  3. Откройте раздел "Реквизиты" созданного платёжного метода и задайте настройки доступа к платёжному шлюзу (подробнее о настройке см. Платежные методы в Nemo.travel):
    • 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 - Маскированный номер карты, которая использовалась для оплаты.

См.также

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

Источник — https://support.nemo.travel/index.php?title=Интеграция_сервиса_приёма_платежей_с_помощью_Payment_Gateway_API&oldid=16906