Описание интерфейса PayMaster

Версия 23.07.2014

Описание интерфейса PayMaster

Язык платежной формы

Форма заказа платежа

Автопараметры

Диапазон IP-адресов

Invoice Confirmation

Payment Notification

Payment Status Notification.

Проверка подлинности запроса

Страницы возврата

Страница успешного и неуспешного платежа

Настройки учетной записи продавца

Средства проверки статуса платежа

Встроенные платежи

Примеры ответов

Значения результатов (result)

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

Автоматизированное выставление счетов

Коды ошибок

Платежные формы

Схема работы:

Компания (продавец) взаимодействует с PayMaster следующим образом:

1. Продавец генерирует (или запрашивает) форму заказа платежа для PayMaster.
2. Покупатель отправляет эту форму на платежную страницу PayMaster.
3. На сайте PayMaster покупатель выбирает способ платежа.
4. Продавцу отправляется предзапрос Invoice Confirmation.
5. Покупатель завершает платеж, продавцу приходит оповещение о платеже Payment Notification.
6. Покупатель возвращается на сайт продавца, на страницу Success или Fail.

Язык платежной формы

В первую очередь язык платежной формы определяется по кукам, сохраненным на компьютере покупателя. Если кука отсутствует, то язык определяется настройкой браузера покупателя. Если язык в настройках браузера отсутствует или указан неподдерживаемый системой язык, то устанавливается английский язык. Языком по умолчанию является английский.

Форма заказа платежа

Эта форма отправляется из браузера покупателя (методом GET или POST) на страницу https://paymaster.ru/Payment/Init для инициации платежа.

Внимание: В соответствии с условиями договора, назначение платежа должно быть детализированным: следует указывать название конкретной предоставляемой услуги, номер лицевого (торгового) счета или аналогичную информацию, позволяющую установить оказываемую услугу или предоставляемый товар.

Автопараметры

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

Пользовательские параметры не участвуют в дальнейшем обмене.

Диапазон IP-адресов

Система PayMaster использует IP-адреса из следующих 2 подсетей класса C:

1. 91.200.28.* (91.200.28.0 маска 255.255.255.0 или в unix-нотации 91.200.28.0/24)
2. 91.227.52.* (91.227.52.0 маска 255.255.255.0 или в unix-нотации 91.227.52.0/24)

Самый простой способ предоставить доступ только к системе PayMaster - занести в список разрешенных адресов указанные подсети.

Invoice Confirmation

Этот HTTP POST запрос отправляется системой PayMaster на веб-сервер продавца, на URL, указанный в настройках, в тот момент, когда пользователь выбрал платежную систему и собирается производить платеж. В зависимости от настроек, продавец может игнорировать запрос, или обязан на него ответить. Запрос приходит в кодировке UTF-8.

Внимание: рекомендуем проверять, что платеж будет принят корректной/допустимой для данного сайта платежной системой, чтобы предотвратить возможное возникновение ошибки.

Для интеграторов: при передаче параметра LMI_SHOP_ID рекомендуем проверять соответствие передаваемого и возвращаемого значения параметра, чтобы избежать подделки формы пользователем.

В качестве ответа на запрос веб-сайта продавца может выдать пустой документ или текст "YES" (case-insensitive) - это означает, что продавец согласен принять платеж.

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

Внимание: не следует возвращать HTML в ответ на этот запрос, возвращайте сообщение об ошибке в plain text.

Внимание: при использовании встроенных платежей не рекомендуется использовать запрос Invoice Confirmation, так как это может привести к оплате счета от которого продавец отказался. СМС или USSD-запрос пользователю присылается раньше запроса Invoice Confirmation.

Payment Notification

Этот HTTP POST запрос отправляется продавцу системой PayMaster в том случае, когда платеж успешно проведен. Важно понимать, что запрос Payment Notification - это единственный запрос, при обработке которого продавцу необходимо учитывать принятый платеж (оказывать услугу и т.п.)

Если продавец по каким-то причинам не смог корректно обработать Payment Notification, то он будет иметь дело с пользователем, который заплатил деньги, но не получил от продавца обещанного товара или услуги.

В системе имеется опция повторения посылки Payment Notification с теми же значениями ключевых параметров в случае, если первый вызов завершился неудачно.

Вне зависимости от настройки этой опции в личном кабинете продавца, следует проверять уникальность параметров LMI_PAYMENT_NO, LMI_SYS_PAYMENT_ID и т.п. в присылаемом системой PayMaster оповещении и не допускать повторного оказания услуг (отгрузки товаров) в случае получения PaymentNotification с одними и теми же параметрами.

К тому же, система PayMaster предоставляет продавцу возможность проверки статуса платежа по номеру платежа, дате и т.д. (как интерактивные, так и программные).

Внимание: если для сайта установлен признак "Пользователь должен вернуться на сайт", то Payment Notification будет отправлен только после возвращения пользователя и отправки его на сайт мерчанта. До этого платеж будет находиться в статусе "Оплачен". Платежи в этом статусе оплачиваются мерчанту и включаются в реестр перечислений к оплате, но не включаются в реестр ежедневных платежей.

В качестве ответа на данный запрос продавец может возвращать что угодно: ответ игнорируется системой PayMaster.

В личном кабинете есть возможность настроить повторную отправку запроса, если произошел сетевой сбой при доставке.

Payment Status Notification.

Нотификации о статусе операции в настоящий момент настраиваются администраторами системы PayMaster индивидуально для некоторых продавцов. На данную страницу приходят нотификации о постановке платежа на холд и об отмене холда.

Присылаемые параметры остаются те же, что и для PaymentNotification, с добавлением параметра LMI_PAYMENT_STATUS, который может принимать одно из следующих значений: HOLD и HOLD_CANCELLED. Первое означает постановку холда, второе - отмену. Если по платежу устанавливается холд, то его можно завершить или отменить, используя соответствующий Rest-интерфейс.

Проверка подлинности запроса

Для обеспечения целостности запроса, система PayMaster формирует контрольную подпись запроса Payment Notification по следующему правилу:

1. Следующие параметры записываются в одну строчку, разделенные символом ‘;’:
   LMI_MERCHANT_ID, LMI_PAYMENT_NO, LMI_SYS_PAYMENT_ID, LMI_SYS_PAYMENT_DATE, LMI_PAYMENT_AMOUNT, LMI_CURRENCY, LMI_PAID_AMOUNT, LMI_PAID_CURRENCY, LMI_PAYMENT_SYSTEM, LMI_SIM_MODE
   
   При этом, если параметр отсутствует, вместо него пишется пустая строка. Обратите внимание, что LMI_SIM_MODE в рабочем(!) режиме всегда рассматривается пустым. 
   
2. Если запрос представляет собой нотификацию о статусе операции, что к параметрам через точку с запятой добавляется LMI_PAYMENT_STATUS.
   
3. К строке добавляется еще один символ ‘;’ и секретное слово, указанное в настройках сайта
   
4. Полученная строка рассматривается как массив байтов в кодировке UTF-8, и от нее вычисляется хеш MD5 или SHA1 (в зависимости от того, какой метод указан в настройках продавца).
   
5. Этот хеш (последовательность байт) преобразовывается в Base64-строку. Эта строка и есть значение параметра LMI_HASH.

Рекомендуем использовать инструмент формирования подписи для проверки правильности алгоритма.

Замечание для разработчиков на PHP: если $str - строка параметров, то хеш считается как base64_encode(md5($str, true)). Для PHP версии 4: base64_encode(pack("H*", md5($str)))

В случае SHA256: base64_encode(hash('sha256', $string, true)).

Страницы возврата

Страница успешного и неуспешного платежа

Когда платеж успешно завершен, пользователь отправляется на сайт продавца на страницу, указанную как Success URL. Если платеж отменен или неуспешен, то пользователь отправляется на страницу Fail URL.

В обоих случаях выполняется POST или GET (в зависимости от настроек сайта) запрос с указанными ниже полями.

Замечение 1: этот запрос отправляется через браузер покупателя, поэтому продавцу не следует в обработчиках страниц Success и Fail выполнять какие-либо действия по подтверждению платежа. Никто не гарантирует, что пользователь пришел на страницу Success / Fail URL именно с сайта PayMaster, и именно после успешного/неуспешного платежа. Только корректная обработка запроса Payment Notification является гарантией успешного платежа!

Замечание 2: если по каким-либо причинам (сбой сайта продавца, сбой сети) системе PayMaster не удалось отправить запрос Payment Notification на сайт продавца, то покупатель все равно будет перенаправлен на Success URL. Продавцу следует учесть, что, теоретически, Payment Notification может прийти после того, как пользователь откроет Success URL.

Настройки учетной записи продавца

Продавец может изменять следующие параметры своих сайтов:

* Сайт может находиться в одном из пяти состояний:

• Тестовый режим, ожидает проверки
• Тестовый режим
• Рабочий режим
• Отключен
• Заблокирован

После создания и ввода данных о сайте продавцом, он ожидает проверки. После проверки сайта сотрудником PayMaster он переводится в "Тестовый режим". Далее сотрудники продавца, имеющие соответствующие полномочия, могут перевести его в "Рабочий режим".

При совершении действий, нарушающих условия договора или при других непредвиденных обстоятельствах сайт может быть переведен сотрудником PayMaster в состояние "Заблокирован". После решения сложившейся ситуации сайт переводится в состояние "Отключен" из которого сотрудник продавца может самостоятельно перевести сайт в "Тестовый режим" или "Рабочий режим".

Средства проверки статуса платежа

Система PayMaster предоставляет следующие средства проверки статуса платежа по его номеру:

• Вручную на сайте PayMaster, в личном кабинете продавца
• Посредством отправки REST HTTP запроса к серверу PayMaster. Детально о REST-интерфейсах можно прочитать здесь
• Поиском платежа в файле успешных платежей. Ежедневно сервис отправляет в адрес продавца (настраивается опционально) e-mail со списком проведенных платежей (тех, по которым был сформирован и отправлен Payment Notification) и проведенных возвратов за прошедший период.

Встроенные платежи

Встроенные платежи - это платежи, которые проводятся без отправки пользователя на сайт PayMaster, путем использования REST HTTP запросов к PayMaster.

Схема работы

1.        Запуск платежа через отправку запроса на https://paymaster.ru/BuiltinPayment/Init. Параметры запроса остаются те же, что и в обычной форме запроса платежа, со следующими отличиями:

a. (важно!) добавляется обязательный параметр authhash, содержащий подпись запроса. Необходимо использовать тип подписи (sha1\sha256\md5) указанный в настройках сайта в ЛК. При запуске платежа в подписи участвуют параметры LMI_MERCHANT_ID, LMI_PAYMENT_AMOUNT (с отделением дробной части через точку и обязательными двумя знаками после точки), LMI_CURRENCY, SecretKey (значение настраивается в личном кабинете). Во всех последующих запросах участвуют PaymentUrl, записанный в нижнем регистре, и SecretKey. Значения этих полей записываются в одну строчку через точку с запятой (;), затем от полученной UTF8-строки считается SHA1(\sha256\md5, в зависимости от настройки "Тип подписи" сайта)-хеш, который затем кодируется base64. PHP код формирования хеша в случае использования SHA1: $authhash = base64_encode(sha1($str, true)), где $str - строка параметров. Обратите внимание, что base64 вычисяется от байт-массива результата хеша, а не его hex представления.

b. (важно!) LMI_PAYMENT_METHOD - обязательный параметр, значение должно быть указано. Использовавшийся ранее параметр LMI_PAYMENT_SYSTEM также принимается и  обрабатывается;

c. добавляется необязательный параметр json. Если он равен 1, то ответ возвращается в виде JSON, иначе ответ возвращается в виде Xml.

d. добавляется необязательный параметр currencyID, означающий в какой валюте будет платить пользователь (не путать с LMI_CURRENCY, которая означает, в какой валюте продавец получит оплату);

e. добавляется необязательный параметр culture, в который можно передать значение LCID языка, на котором нужно выдавать информационные сообщения.

f. добавляются параметры вида values[<ValueName>], означающие заполненные пользователем параметры платежа (аналогично автопараметрам). На первом шаге заполнение параметров возможно только если продавец заранее знает, какие параметры попросит ввести платежная система.

2.         Получение ответа в виде JSON или Xml (Xsd схему можно взять тут).

3.         В зависимости от кода возврата возможны следующие действия:

a. успешное завершение платежа, показ пользователю сообщения об этом и, если указано, дополнительной информации о совершенном платеже;

b. неуспешное завершение платежа, показ пользователю сообщения об ошибке;

c. показ пользователю сообщения. В этом случае нужно через некоторое время повторить пустой запрос на Url, указанную в ответе, и снова перейти к шагу 2;

d. ввод пользовательских параметров. В этом случае продавец должен будет отправить значения введенных пользователем реквизитов на PaymentUrl, указанную в ответе. Параметры отправляются согласно описанию в 1.e. Также можно передать значения из 1.c - 1.d. После отправки параметров действовать согласно шагу 2 и т.д.;

e. ожидание статуса платежа. В этом случае нужно через некоторое время повторить пустой запрос на Url, указанную в ответе, и снова перейти к шагу 2.

f. перенаправление пользователя на внешнюю страницу оплаты. Некоторые платежные системы требуют перенаправления пользователя на свои платежные страницы. В этом случае продавцу сообщается Url для перенаправления;

g. сообщение о невозможности прочитать запрос.

Примеры ответов

1. Успешное завершение платежа (https://paymaster.ru/BuiltinPayment/ResponseExample/Success):

Разъяснение полей:

• pm.response/result - код возврата. 0 - платеж успешно завершен;
• pm.response/id - номер платежа в PayMaster;
• pm.response/lastupdate - дата проведения фактического транзакции;
• pm.response/paymentUrl - Url платежа;
• pm.response/amounts/invoice - сумма, полагающаяся продавцу;
• pm.response/amounts/topay - сумма, которую оплатит пользователь;
• pm.response/messages - список сообщений с дополнительной информацией, которые надо показать пользователю. title - заголовок сообщения, body - html тело сообщения.

2. Неуспешное завершение платежа (https://paymaster.ru/BuiltinPayment/ResponseExample/Fail):

Разъяснение полей:

• pm.response/result - код возврата. 1-99 - не удалось провести платеж;
• pm.response/id - номер платежа в PayMaster;
• pm.response/lastupdate - дата получения ошибки;
• pm.response/suberrorcode - код ошибки, см. раздел "Коды ошибок";
• pm.response/paymentUrl - Url платежа;
• pm.response/amounts/invoice - сумма, полагающаяся продавцу;
• pm.response/amounts/topay - сумма, которую оплатит пользователь;
• pm.response/messages - список сообщений с описанием ошибки

3. Показ сообщения пользователю (https://paymaster.ru/BuiltinPayment/ResponseExample/ShowMessage):
   

Разъяснение полей:

• pm.response/result - код возврата. 100 - пользователю нужно показать сообщение и дожидаться изменения статуса платежа;
• pm.response/id - номер платежа в PayMaster;
• pm.response/lastupdate - дата генерации сообщения;
• pm.response/paymentUrl - Url, по которой надо отправить следующий запрос. Запрос должен быть пустой;
• pm.response/amounts/invoice - сумма, полагающаяся продавцу;
• pm.response/amounts/topay - сумма, которую оплатит пользователь;
• pm.response/messages - список сообщений, которые надо показать
  
  

4. Ввод пользовательских параметров (https://paymaster.ru/BuiltinPayment/ResponseExample/Requisites):

Разъяснение полей:

• pm.response/result - код возврата. 101 - необходимо прислать параметры, введенные пользователем;
• pm.response/id - номер платежа в PayMaster;
• pm.response/lastupdate - дата генерации запрашиваемых параметров;
• pm.response/paymentUrl - Url платежа, на который надо отправлять следующий запрос, содержащий параметры вида values[<ValueName>];
• pm.response/amounts/invoice - сумма, полагающаяся продавцу;
• pm.response/amounts/topay - сумма, которую оплатит пользователь;
• pm.response/amounts/maychoosetopay - валюты, которые пользователь может выбрать к оплате и суммы в этих валютах. Выбранную валюту нужно передавать в параметре currencyID, о котором говорилось выше;
• pm.response/amounts/approximateothertopay - валюты, которые пользователь не может выбрать к оплате, но информация о них ему может понадобиться (к примеру, в результате обмена, пользователь потратит примерно X фунтов со своего предоплаченного ваучера, номинированного в фунтах, но оплата все равно по факту будет проводиться в евро) и суммы в этих валютах. Это чисто информационное поле;
• pm.response/requisites/items - пользовательские параметры, которые необходимо ввести. У каждого параметра есть аттрибут name, который надо передавать в качестве <ValueName> в параметрах values[<ValueName>], о которых говорилось выше. Параметры бывают следующих типов:

• textinput - текстовое значение. title - название поля для показа пользователю, eg - пример заполнения, regex - регулярное выражение, которому должно удовлетворять значение, required - является ли поле обязательным к заполнению;
• check - значение типа "галочка". title - название поля для показа пользователю, required - обязан ли пользователь выставить галочку для продолжения платежа, checked - стоит ли галочка по умолчанию. Значение передается в виде "true" или "false";
• enum - выбор из списка, title - название поля для показа пользователю, options - список опций в списке, option/value - значение опции, option/title - название опции для показа пользователю. К примеру, если в вышеукаазанном ответе пользователь выбрал вторую опцию, то нужно будет передать на paymaster в следующем запросе параметр values[Choose]=option2.
• label - просто текст для показа. title - заголовок текста, html - тело. На paymaster можно не передавать этот параметр назад;
• proceed - авто-параметр. Его надо передать в значении "true", если пользователь готов продолжить платеж;

• pm.response/requisites/requirementgroups - список групп параметров, для которых требуется заполнение одного из них. Для вышеприведенного примера это означает, что пользователю нужно заполнить либо параметр EMail, либо параметр Phone. description - описание требования для показа пользователю.

5. Ожидание статуса платежа (https://paymaster.ru/BuiltinPayment/ResponseExample/Pending):

Разъяснение полей:

• pm.response/result - код возврата. 200 - необходимо повторить запрос через некоторое время (без пользовательских параметров). Если поле CustomTrackPaymentText не пустое, то надо транслировать его;
• pm.response/id - номер платежа в PayMaster;
• pm.response/lastupdate - дата перехода в статус "ожидание";
• pm.response/paymentUrl - Url платежа, на который надо отправлять следующий запрос. Запрос должен быть пустым;
• pm.response/amounts/invoice - сумма, полагающаяся продавцу;
• pm.response/amounts/topay - сумма, которую оплатит пользователь;

6. Перенаправление пользователя на внешнюю страницу (https://paymaster.ru/BuiltinPayment/ResponseExample/Redirect):

Разъяснение полей:

• pm.response/result - код возврата. 2 - необходимо перенаправить пользователя на внешнюю страницу оплаты;
• pm.response/id - номер платежа в PayMaster;
• pm.response/paymentUrl - Url, куда надо перенаправить пользователя;
• pm.response/redirectdata/@method - HTTP метод перенаправления;
• pm.response/redirectdata/param - параметры, с которыми надо выполнить перенаправление;

7. Сообщение о невозможности прочитать запрос (https://paymaster.ru/BuiltinPayment/ResponseExample/UnableToParse):

Разъяснение полей:

• pm.response/result - код возврата. <0 - не удалось прочитать запрос;
• pm.response/paymentUrl - страница с пояснением причин, по которым запрос не был прочитан;

Значения результатов (result)

• -1 - неверная подпись запроса;
• -2 - неподдерживаемая валюта;
• -3 - дублированный номер счета;
• -4 - неподдерживаемая кодировка;
• -5 - неподдерживаемая платежная система;
• -6 - некорректная сумма платежа;
• -7 - нет разрешения выставлять счета на открытые суммы;
• -8 - некорректный номер счета;
• -9 - нет доступа к интерфейсу;
• -10 - пустое примечание к платежу;
• -11 - неверный PaymentUrl;
• -100 - невозможно прочитать поле запроса;
• -101 - невозможно прочитать весь запрос;
• -500 - неизвестная ошибка, следует обратиться в техподдержку, если она воспроизводится регулярно;
• 1 - платеж сорвался (причины см. в поле suberrorcode, значения которого определяются из таблицы Коды ошибок);
• 2 - необходимо перенаправить пользователя на указанную страницу;
• 100 - необходимо показать пользователю указанное сообщение;
• 101 - необходимо запросить у пользователя указанные реквизиты;
• 200 - платеж обрабатывается, необходимо повторить запрос без пользовательских параметров (не забудьте включить AuthHash) на PaymentUrl через некоторое время; если поле CustomTrackPaymentText не пустое, то надо транслировать его. Если поле пустое, то это просто ожидание платежа;
• 0 - платеж успешно проведен;

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

См. Запуск платежа Webmoney X20 посредством PayMaster

Автоматизированное выставление счетов на оплату товара/услуги

PayMaster предоставляет возможность компаниям/продавцам  принимать оплату через выставление счетов,  что значительно  упрощает  взаимодействие с плательщиками.

 Данный способ подходит для мерчантов, чей бизнес предусматривает проверку наличия товара до его оплаты.

Схема работы

1.           Формирование счета на оплату осуществляется через отправку запроса на https://paymaster.ru/BuiltinPayment/initonly.  Параметры запроса остаются те же, что и в обычной форме запроса платежа, со следующими отличиями:

a. (важно!) добавляется обязательный параметр authhash, содержащий подпись запроса. Необходимо использовать тип подписи (sha1\sha256\md5) указанный в настройках сайта в ЛК.
При формировании счета на оплату в подписи участвуют параметры LMI_MERCHANT_ID, LMI_PAYMENT_AMOUNT (с отделением дробной части через точку и обязательными двумя знаками после точки), LMI_CURRENCY, SecretKey (значение настраивается в личном кабинете). Значения этих полей записываются в одну строчку через точку с запятой (;), затем от полученной UTF8-строки считается SHA1(\sha256\md5, в зависимости от настройки "Тип подписи" сайта)-хеш, который затем кодируется base64. PHP код формирования хеша в случае использования SHA1:
$authhash = base64_encode(sha1($str, true)), где $str - строка параметров. Обратите внимание, что base64 вычисяется от байт-массива результата
хеша, а не его hex представления.

b. (важно!) LMI_PAYMENT_METHOD - обязательный параметр, значение должно быть указано. Использовавшийся ранее
параметр LMI_PAYMENT_SYSTEM также принимается и  обрабатывается;

c. добавляется необязательный параметр json. Если он равен 1, то ответ возвращается в виде JSON, иначе ответ возвращается в виде Xml.

2.           Получение ответа в виде JSON или Xml (Xsd схему можно взять тут).

        В параметре paymentUrl содержится короткая ссылка, на которую следует  

        отправлять плательщика для проведения платежа.

Коды ошибок