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

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

Версия 18:47, 7 апреля 2020

Универсальный 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 - Маскированный номер карты, которая использовалась для оплаты.
Источник — https://support.nemo.travel/index.php?title=Интеграция_сервиса_приёма_платежей_с_помощью_Payment_Gateway_API&oldid=16888