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

Материал из Центр поддержки системы бронировании
Перейти к навигации Перейти к поиску
Строка 1: Строка 1:
 
Универсальный API для подключения платежных шлюзов обеспечивает единый протокол, с помощью которого вы можете с минимальными затратами времени и ресурсов подключить любой существующий платежный шлюз, используя одну универсальную схему подключения.
 
Универсальный API для подключения платежных шлюзов обеспечивает единый протокол, с помощью которого вы можете с минимальными затратами времени и ресурсов подключить любой существующий платежный шлюз, используя одну универсальную схему подключения.
 
'''Здесь и далее:'''
 
*Система Немо - система бронирования Nemo Travel,
 
*Сервис - сервис по приему платежей.
 
  
  
Строка 9: Строка 5:
  
 
Модуль PAYMENT GATEWAY API является дополнительным. Чтобы подключиться к Nemo.travel по данному протоколу, обратитесь в коммерческий отдел по адресу connect@nemo.travel
 
Модуль PAYMENT GATEWAY API является дополнительным. Чтобы подключиться к Nemo.travel по данному протоколу, обратитесь в коммерческий отдел по адресу connect@nemo.travel
 +
 +
=Особенности=
 +
Сервис не поддерживает фискализацию платежей.
  
 
=Настройка шлюза=
 
=Настройка шлюза=
Строка 23: Строка 22:
 
* Высота фрэйма со страницей оплаты
 
* Высота фрэйма со страницей оплаты
  
=Описание запросов=
+
=Техническая документация по интеграции с сервисом PAYMENT GATEWAY API=
 +
 
 +
'''Здесь и далее:'''
 +
*Система Немо - система бронирования Nemo Travel,
 +
*Сервис - сервис по приему платежей.
 +
 
 +
 
 +
==Описание запросов==
 +
 
 
{| class="wikitable"
 
{| class="wikitable"
 
! Название запроса !! Описание !! Особенности
 
! Название запроса !! Описание !! Особенности
Строка 46: Строка 53:
 
* При необходимости возврата средств система Немо посылает запрос обновления заказа в платежный шлюз. Если полученный статус заказа - orderStatus=1, то посылается запрос reverse.do, если orderStatus=2, то посылается refund.do.
 
* При необходимости возврата средств система Немо посылает запрос обновления заказа в платежный шлюз. Если полученный статус заказа - orderStatus=1, то посылается запрос reverse.do, если orderStatus=2, то посылается refund.do.
  
=Порядок взаимодействия Системы Немо и Сервиса=
+
==Порядок взаимодействия Системы Немо и Сервиса==
  
==Оплата с предавторизацией==
+
===Оплата с предавторизацией===
 
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа registerPreAuth.do.
 
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа registerPreAuth.do.
 
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
 
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
Строка 58: Строка 65:
 
#Процедура оплаты завершена.
 
#Процедура оплаты завершена.
  
==Оплата без предавторизации==
+
===Оплата без предавторизации===
 
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа register.do.  
 
#При инициировании оплаты Система Немо отправляет Запрос регистрации заказа register.do.  
 
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
 
#Система Немо перенаправляет пользователя на url, который Сервис указал в ответе на запрос регистрации для совершения операции эквайринга на стороне Сервиса.
Строка 65: Строка 72:
 
#Если orderStatus=2 и errorCode=0, Система Немо выполняет оформление заказа.
 
#Если orderStatus=2 и errorCode=0, Система Немо выполняет оформление заказа.
  
==Возврат средств==
+
===Возврат средств===
 
Для возврата средств Система Немо направляет getOrderStatusExtended.do.
 
Для возврата средств Система Немо направляет getOrderStatusExtended.do.
 
*Если полученный статус заказа orderStatus=1, то посылается запрос reverse.do,  
 
*Если полученный статус заказа orderStatus=1, то посылается запрос reverse.do,  
 
*Если orderStatus=2, то посылается refund.do.
 
*Если orderStatus=2, то посылается refund.do.
  
==Замечания==
 
Сервис не поддерживает фискализацию платежей.
 
  
=Формат запросов/ответов=
+
==Формат запросов/ответов==
  
 
Универсальный API для подключения платежных шлюзов реализован с помощью HTTP запросов/ответов методом POST.
 
Универсальный API для подключения платежных шлюзов реализован с помощью HTTP запросов/ответов методом POST.

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

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


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

Модуль PAYMENT GATEWAY API является дополнительным. Чтобы подключиться к Nemo.travel по данному протоколу, обратитесь в коммерческий отдел по адресу connect@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 - Маскированный номер карты, которая использовалась для оплаты.

См.также

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