Агентский API Оплата

Материал из Центр поддержки системы бронировании
Версия от 14:34, 5 февраля 2016; Мария Горшенева (обсуждение | вклад) (→‎Общий формат запроса / ответа)
Перейти к навигации Перейти к поиску

Подключение

Это сервис внутри Nemo, который предназначен для выполнения различных операций, относящихся к оплате заказов.

Для подключения к данной веб-службе необходимо открыть доступ нужному пользователю. Это можно сделать в разделе «Администрирование» ⇨ «Веб-служба. Авторизация».

После добавления пользователя, ему будут присвоены Номер (ClientId) и API ключ клиента, которые нужно использовать для подключения.


Фиксация оплаты внешним запросом

Сервис предназначен для приема информации о получении оплаты и простановки статуса «Оплачено» для определенного заказа.

Сервис вызывается следующим образом: http://CLIENT_DOMAIN/index.php?go=payment/bill

Подпись запроса

Подпись sig сверяется c md5($booking_id.$secret)

$booking_id - Id заказа в системе Nemo,

$secret - значение настройки в разделе «Администрирование» ⇨ «Настройки агентства» ⇨ «Ключ безопасности для сервиса выставления оплаты и получения XML выгрузки»

Пример: 

Если

booking_id: 263330
ключ безопасности: 12345

То

sig=md5(26333012345) = a439a4492131f4b866ed1a17d018d3a6

Для фиксации оплаты получается такая ссылка: http://CLIENT_DOMAIN/index.php?go=payment/bill&booking_id=263330&sig=a439a4492131f4b866ed1a17d018d3a6

Дополнительная информация в статье Интеграция


Получение списка доступных способов оплаты

WSDL находится по адресу: http://CLIENT_DOMAIN/wsdev/wsdl.php?version=1.0&for=PaymentInitialization На данный момент метод доступен для платежных шлюзов Юнителлер и Рапида.

Для получения результата необходим параметр — «OrderId» — Id забронированного заказа, который необходимо оплатить.

Данный запрос позволяет получить список платёжных шлюзов, через которые есть возможность оплатить указанный заказ. По каждому платёжному шлюзу возвращается следующая информация:

  • id способа оплаты
  • имя платежного шлюза
  • дополнительную наценку, которая добавляется к заказу при проведении оплаты через данный шлюз
  • URL, перенаправляющий пользователя непосредственно на страницу оплаты через данный платёжный шлюз
  • в случае отправки запроса с мобильной платформы может дополнительно возвращается URL, на который происходит перенаправление пользователя для оплаты

Общий формат запроса / ответа

Запрос

 1 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DPaymentInitialization">
 2    <soapenv:Header/>
 3    <soapenv:Body>
 4       <ver:InitPayment>
 5          <RequestBin>
 6             <Request>
 7                <OrderId>?</OrderId>
 8              <!--OrderId — Id забронированного заказа в системе Nemo--> 
 9                <!--Optional:--> 
10                <ReturnUrlToCatch>?</ReturnUrlToCatch> <!--необязательный--> 
11                <!--ReturnUrlToCatch - Признак возвращать ли адрес, на который будет перенаправлен пользователь после оплаты: true(возвращать)/false(не возвращать)-->
12                <!--Optional:--> 
13             </Request>
14             <Source>
15                <ClientId>?</ClientId>
16         <!--ClientId — ID клиента в системе Nemo. Можно посмотреть/добавить в разделе "Администрирование" - "Веб-служба. Авторизация".--> 
17                <APIKey>?</APIKey>
18          <!--APIKey — секретный ключ доступа к API Nemo. Можно посмотреть/добавить в разделе "Администрирование" - "Веб-служба. Авторизация".--> 
19                <Language>?</Language>
20         <!--Language — язык, например: RU--> 
21                <Currency>?</Currency>
22         <!-- Currency — валюта, например: RUB, EUR--> 
23             </Source>
24          </RequestBin>
25       </ver:InitPayment>
26    </soapenv:Body>
27 </soapenv:Envelope>

Ответ

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DPaymentInitialization">
 2    <SOAP-ENV:Body>
 3       <ns1:InitPaymentResponse>
 4          <ResponseBin>
 5             <Response>
 6                <Gateways>
 7                   <Gateway>
 8                      <PaymentMethodId>?</PaymentMethodId>
 9                       <!--PaymentMethodId - ID способа оплаты. Необходим при использовании запроса SelectPayment (см. ниже)-->
10                      <GatewayName>?</GatewayName>
11                      <!--GatewayName — имя платежного шлюза. Например: Uniteller -->
12                      <PaymentCharge Currency="?">?</PaymentCharge>
13 	          <!--PaymentCharge — наценка, которая добавляется к заказу при оплате через данный шлюз, Currency — код валюты (из запроса)-->
14                      <RedirectUrl>?</RedirectUrl>
15                      <!--RedirectUrl — URL, по которому происходит перенаправление пользователя непосредственно на страницу оплаты через данный платежный шлюз-->
16                      <UrlToCatch>?</UrlToCatch>
17 	          <!--UrlToCatch — URL для перехвата и дальнейшей обработки в случае отправки запроса с мобильной платформы, ведущий на страницу заказа-->
18                   </Gateway>
19                </Gateways>
20                <Error>
21                  <NewPrice/>
22                  <Message>Сообщение об ошибке</Message>
23                </Error>
24             </Response>
25          </ResponseBin>
26       </ns1:InitPaymentResponse>
27    </SOAP-ENV:Body>
28 </SOAP-ENV:Envelope>

Примеры использования

Запрос

 1 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DPaymentInitialization">
 2    <soapenv:Header/>
 3    <soapenv:Body>
 4       <ver:InitPayment>
 5          <RequestBin>
 6             <Request>
 7                <OrderId>276965</OrderId>
 8                <ReturnUrlToCatch>true</ReturnUrlToCatch>
 9             </Request>
10             <Source>
11                <ClientId>---</ClientId>
12                <APIKey>---</APIKey>
13                <Language>RU</Language>
14                <Currency>RUB</Currency>
15             </Source>
16          </RequestBin>
17       </ver:InitPayment>
18    </soapenv:Body>
19 </soapenv:Envelope>

Ответ

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DPaymentInitialization">
 2    <SOAP-ENV:Body>
 3       <ns1:InitPaymentResponse>
 4          <ResponseBin>
 5             <Response>
 6                <Gateways>
 7                   <Gateway>
 8                      <PaymentMethodId>1075</PaymentMethodId>
 9                      <GatewayName>Uniteller</GatewayName>
10                      <PaymentCharge Currency="RUB">81.54</PaymentCharge>
11                      <RedirectUrl>http://CLIENT_DOMAIN/payment__select_outside?booking_id=276965&amp;one_time_booking_code=PZ7981&amp;method=27</RedirectUrl>
12                      <!--Пример ссылки-->
13                      <UrlToCatch>http://CLIENT_DOMAIN/poffice__bookinfo?&amp;booking_id=276965</UrlToCatch>
14                      <!--Пример ссылки-->
15                   </Gateway>
16                  <Gateway>
17                      <PaymentMethodId>1079</PaymentMethodId>
18                      <GatewayName>Rapida</GatewayName>
19                      <PaymentCharge Currency="RUB">123</PaymentCharge>
20                      <RedirectUrl/>
21                      <UrlToCatch xsi:nil="true"/>
22                   </Gateway>
23                </Gateways>
24             </Response>
25          </ResponseBin>
26       </ns1:InitPaymentResponse>
27    </SOAP-ENV:Body>
28 </SOAP-ENV:Envelope>

Ответ с ошибкой

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://release.mlsd.ru/wsdev/?version%3D1.0%26for%3DPaymentInitialization">
 2    <SOAP-ENV:Body>
 3       <ns1:InitPaymentResponse>
 4          <ResponseBin>
 5             <Error>
 6                <NewPrice/>
 7                <Message>Unknown order status: Problematic</Message>
 8             </Error>
 9          </ResponseBin>
10       </ns1:InitPaymentResponse>
11    </SOAP-ENV:Body>
12 </SOAP-ENV:Envelope>

Примечание: если параметр RedirectUrl в ответе отсутствует, для инициализации оплаты необходимо использовать метод SelectPayment.

Выбор конкретного способа оплаты

WSDL находится по адресу: http://CLIENT_DOMAIN/wsdev/wsdl.php?version=1.0&for=SelectPayment

На данный момент этот веб-метод доступен только для платежного шлюза Рапида.

Запрос позволяет выбрать конкретный способ оплаты и получить платежный код для оплаты заказа, таймлимит на оплату и описание, заданное в настройках ПШ Рапида (содержимое поля "Сообщение пользователю").

Общий формат запроса / ответа

Запрос

 1 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DSelectPayment">
 2   <soapenv:Header/>
 3   <soapenv:Body>
 4     <ver:SelectPayment>
 5       <RequestBin>
 6         <Request>
 7           <OrderId>?</OrderId>
 8            <!--OrderId — Id забронированного заказа в системе Nemo. Обязательный параметр-->
 9           <PaymentMethodId>?</PaymentMethodId>
10           <!--PaymentMethodId - ID данного способа оплаты, приходит в ответе на запрос PaymentInitialization response. Обязательный параметр-->
11         </Request>
12         <Source>
13           <ClientId>?</ClientId>
14            <!--ClientId — ID клиента в системе Nemo. Можно посмотреть/добавить в разделе "Администрирование" - "Веб-служба. Авторизация". Обязательный параметр.-->
15           <APIKey>?</APIKey>
16            <!--APIKey — секретный ключ доступа к API Nemo. Можно посмотреть/добавить в разделе "Администрирование" - "Веб-служба. Авторизация". Обязательный параметр.-->
17           <Language>?</Language>
18           <!--Язык — пример: RU-->
19           <Currency>?</Currency>
20           <!-- Валюта — примеры: RUB, EUR-->
21         </Source>
22       </RequestBin>
23     </ver:SelectPayment>
24   </soapenv:Body>
25 </soapenv:Envelope>

Ответ

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DSelectPayment">
 2   <SOAP-ENV:Body>
 3       <ns1:SelectPaymentResponse>
 4          <ResponseBin>
 5             <Response>
 6                <TransactionId>?</TransactionId>
 7                <!--TransactionId - ID платежной транзакции в системе Немо-->
 8                <PaymentParameters>
 9                   <PaymentParameter>
10                      <Key>Code</Key>
11                      <Value>?</Value>
12                      <!--Value - платежный код, приходит от платежного шлюза Рапида-->
13                   </PaymentParameter>
14                   <PaymentParameter>
15                      <Key>Timelimit</Key>
16                      <Value>?</Value>
17                      <!--Value - таймлимит на оплату заказа-->
18                   </PaymentParameter>
19                   <PaymentParameter>
20                      <Key>Description</Key>
21                      <Value>?</Value>
22                      <!--Value - краткое сообщение пользователю. Может содержать упомянутые выше платежный код, таймлимит и др. информацию. Настраивается в настройках реквизитов ПШ Рапида в соответствующем поле.-->
23                   </PaymentParameter>
24                </PaymentParameters>
25                <Error>
26                  <NewPrice/>
27                  <Message>Сообщение об ошибке</Message>
28                </Error>
29             </Response>
30          </ResponseBin>
31       </ns1:SelectPaymentResponse>
32    </SOAP-ENV:Body>
33 </SOAP-ENV:Envelope>

Примеры использования

Запрос

 1 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ver="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DSelectPayment">
 2   <soapenv:Header/>
 3   <soapenv:Body>
 4     <ver:SelectPayment>
 5       <RequestBin>
 6         <Request>
 7           <OrderId>279712</OrderId>
 8           <PaymentMethodId>1079</PaymentMethodId>
 9         </Request>
10         <Source>
11           <ClientId>--</ClientId>
12           <APIKey>--</APIKey>
13           <Language>RU</Language>
14           <Currency>RUB</Currency>
15         </Source>
16       </RequestBin>
17     </ver:SelectPayment>
18   </soapenv:Body>
19 </soapenv:Envelope>

Ответ

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://CLIENT_DOMAIN/wsdev/?version%3D1.0%26for%3DSelectPayment">
 2   <SOAP-ENV:Body>
 3       <ns1:SelectPaymentResponse>
 4          <ResponseBin>
 5             <Response>
 6                <TransactionId>117608085</TransactionId>
 7                  <PaymentParameters>
 8                   <PaymentParameter>
 9                      <Key>Code</Key>
10                      <Value>a117608085a0CGN73</Value>
11                   </PaymentParameter>
12                   <PaymentParameter>
13                      <Key>Timelimit</Key>
14                      <Value>23:59 20.01.2015</Value>
15                   </PaymentParameter>
16                   <PaymentParameter>
17                      <Key>Description</Key>
18                      <Value>Ваш платежный код - a117608085a0CGN73. Оплатить заказ необходимо до 23:59 20.01.2015</Value>              
19                   </PaymentParameter>
20                </PaymentParameters>
21             </Response>
22          </ResponseBin>
23       </ns1:SelectPaymentResponse>
24    </SOAP-ENV:Body>
25 </SOAP-ENV:Envelope>

Ответ с ошибкой

 1 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://release.mlsd.ru/wsdev/?version%3D1.0%26for%3DSelectPayment">
 2    <SOAP-ENV:Body>
 3       <ns1:SelectPaymentResponse>
 4          <ResponseBin>
 5             <Error>
 6                <NewPrice/>
 7                <Message>Unknown order status: Problematic</Message>
 8             </Error>
 9          </ResponseBin>
10       </ns1:SelectPaymentResponse>
11    </SOAP-ENV:Body>
12 </SOAP-ENV:Envelope>

См. также

Источник — https://support.nemo.travel/index.php?title=Агентский_API_Оплата&oldid=8138