RU / en

Описание интерфейса 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

Обязательный?

Описание 

Идентификатор продавца

LMI_MERCHANT_ID

Да

Идентификатор сайта в системе PayMaster. Идентификатор можно увидеть в Личном Кабинете, на странице "Список сайтов", в первой колонке.

Сумма платежа

LMI_PAYMENT_AMOUNT

Да

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

Валюта платежа

LMI_CURRENCY

Да

Идентификатор валюты платежа. Система PayMaster понимает как текстовый 3-буквенный код валюты (RUB), так и ISO-код (643). (см. http://www.currency-iso.org/en/home/tables/table-a1.html)

Внутренний номер счета продавца

LMI_PAYMENT_NO

Нет

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

Назначение платежа

LMI_PAYMENT_DESC

Нет (*)

Описание товара или услуги. Формируется продавцом. Максимальная длина - 255 символов.

*Внимание: одно из полей LMI_PAYMENT_DESC или LMI_PAYMENT_DESC_BASE64 должно обязательно присутствовать!

Назначение платежа

LMI_PAYMENT_DESC_BASE64

Нет (*)

Описание товара или услуги в UTF-8 и далее закодированное алгоритмом Base64. Формируется продавцом. Если присутствует, то результат раскодирования будет подставлен вместо LMI_PAYMENT_DESC. Позволяет не зависеть от кодировки на сайте продавца.

*Внимание: одно из полей LMI_PAYMENT_DESC или LMI_PAYMENT_DESC_BASE64 должно обязательно присутствовать!

Режим тестирования

LMI_SIM_MODE

Нет

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

0 или отсутствует: Для всех тестовых платежей сервис будет имитировать успешное выполнение;

1: Для всех тестовых платежей сервис будет имитировать выполнение с ошибкой (платеж не выполнен);

2: Около 80% запросов на платеж будут выполнены успешно, а 20% - не выполнены.

Замена Invoice Confirmation URL

LMI_INVOICE_CONFIRMATION_URL

Нет

Если присутствует, то запрос Invoice Confirmation будет отправляться по указанному URL (а не установленному в настройках).

Этот параметр игнорируется, если в настройках сайта запрещена замена URL.

Замена Payment Notification URL

LMI_PAYMENT_NOTIFICATION_URL

Нет

Если присутствует, то запрос Payment Notification будет отправляться по указанному URL (а не установленному в настройках).

Этот параметр игнорируется, если в настройках сайта запрещена замена URL.

Замена Success URL

LMI_SUCCESS_URL

Нет

Если присутствует, то при успешном платеже пользователь будет отправлен по указанному URL (а не установленному в настройках).

Этот параметр игнорируется, если в настройках сайта запрещена замена URL.

Замена Failure URL

LMI_FAILURE_URL

Нет

Если присутствует, то при отмене платежа пользователь будет отправлен по указанному URL (а не установленному в настройках).

Этот параметр игнорируется, если в настройках сайта запрещена замена URL.

Телефон покупателя

LMI_PAYER_PHONE_NUMBER

Нет

Номер телефона покупателя в международном формате без ведущих символов + (например, 79031234567). Эти данные используются системой PayMaster для оповещения пользователя о статусе платежа. Кроме того, некоторые платежные системы требуют указания номера телефона.

E-mail покупателя

LMI_PAYER_EMAIL

Нет

E-mail покупателя. Эти данные используются системой PayMaster для оповещения пользователя о статусе платежа. Кроме того, некоторые платежные системы требуют указания e-mail.

Срок истечения счета

LMI_EXPIRES

Нет

Дата и время, до которого действует выписанный счет. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC.

Внимание: система PayMaster приложит все усилия, чтобы отклонить платеж при истечении срока, но не может гарантировать этого.

Идентификатор платежного метода

LMI_PAYMENT_METHOD

Нет

Идентификатор платежного метода, выбранный пользователем. Отсутствие означает, что пользователь будет выбирать платежный метод на странице оплаты PayMaster.

Платежный метод указан в настройках сайта в квадратных скобках рядом с названием платежной системы (Например: Webmoney [WebMoney]).

Рекомендуется поменять параметр LMI_PAYMENT_SYSTEM на LMI_PAYMENT_METHOD.

Но LMI_PAYMENT_SYSTEM по-прежнему принимается и обрабатывается системой.

Внешний идентификатор магазина в платежной системе

LMI_SHOP_ID

Да (Только для интеграторов)

Внешний идентификатор магазина, передаваемый интегратором в платежную систему. Указывается только при явном определении платежной системы (Указан параметр LMI_PAYMENT_SYSTEM). Для каждой платежной системы формат согласовывается отдельно .

Дополнительные параметры продавца

Определяются продавцом

Нет

Все поля формы, не имеющие в названии префикса "LMI_" и " AP_" обрабатываются системой PayMaster автоматически и передаются на веб-сайт продавца после выполнения платежа.

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

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

При передаче параметров запроса, заранее зная, какие параметры запросит у пользователя платежная система, можно задать их значения. Принцип именования параметров следующий: если вы хотите передать пользовательский параметр с именем 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 рекомендуем проверять соответствие передаваемого и возвращаемого значения параметра, чтобы избежать подделки формы пользователем.

Название

Name

Описание

Флаг предзапроса

LMI_PREREQUEST

Значение всегда 1.

Идентификатор продавца

LMI_MERCHANT_ID

Идентификатор сайта в системе PayMaster

Внутренний номер счета продавца

LMI_PAYMENT_NO

Номер счета, заданный в запросе платежа

Сумма платежа, заказанная продавцом

LMI_PAYMENT_AMOUNT

Дробное число с разделителем ".", не более 2 знаков после точки.

Валюта платежа, заказанная продавцом

LMI_CURRENCY

Это всегда 3-буквенный код валюты (http://www.currency-iso.org/iso_index/iso_tables/iso_tables_a1.htm)

Сумма платежа в валюте, в которой покупатель производит платеж

LMI_PAID_AMOUNT

Дробное число с разделителем ".", не более 2 знаков после точки.

Валюта, в которой производится платеж

LMI_PAID_CURRENCY

Строковый код валюты (не обязательно ISO).

Идентификатор платежного метода

LMI_PAYMENT_METHOD

Идентификатор платежного метода, выбранный пользователем.

Платежный метод указан в настройках сайта в квадратных скобках рядом с названием платежной системы (Например: Webmoney [WebMoney]).

Флаг тестового режима

LMI_SIM_MODE

Это поле присутствует только если платеж производится в тестовом режиме. Значения - те же, что и в форме заказа платежа.

Назначение платежа

LMI_PAYMENT_DESC

Описание платежа, как оно показывается пользователю. То есть, если в форме заказа платежа было указано LMI_PAYMENT_DESC64, то в этом запросе придет уже раскодированное из Base64 описание.

Внешний идентификатор магазина в платежной системе

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 будет отправлен только после возвращения пользователя и отправки его на сайт мерчанта. До этого платеж будет находиться в статусе "Оплачен". Платежи в этом статусе оплачиваются мерчанту и включаются в реестр перечислений к оплате, но не включаются в реестр ежедневных платежей.

Название

Name

Описание 

Идентификатор продавца

 LMI_MERCHANT_ID

Идентификатор сайта в системе PayMaster

Внутренний номер счета продавца

LMI_PAYMENT_NO

Номер счета, заданный в запросе платежа

Номер платежа в системе PayMaster

LMI_SYS_PAYMENT_ID

Идентификатор платежа в системе PayMaster. Продавцу рекомендуется сохранить этот идентификатор.

Дата платежа

LMI_SYS_PAYMENT_DATE

Дата проведения платежа в системе PayMaster. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC.

Сумма платежа, заказанная продавцом

LMI_PAYMENT_AMOUNT

Дробное число с разделителем ".", не более 2 знаков после точки.

Валюта платежа, заказанная продавцом

LMI_CURRENCY

Это всегда 3-буквенный код валюты (http://www.currency-iso.org/iso_index/iso_tables/iso_tables_a1.htm)

Сумма платежа в валюте, в которой покупатель производит платеж

LMI_PAID_AMOUNT

Дробное число с разделителем ".", не более 2 знаков после точки.

Валюта, в которой производится платеж

LMI_PAID_CURRENCY

Строковый код валюты, не обязательно ISO.

Идентификатор платежного метода

LMI_PAYMENT_METHOD

Идентификатор платежного метода, выбранный пользователем.

Платежный метод указан в настройках сайта в квадратных скобках рядом с названием платежной системы (Например: Webmoney [WebMoney]).

Флаг тестового режима

LMI_SIM_MODE

Это поле присутствует только если платеж производится в тестовом режиме. Значения - те же, что и в форме заказа платежа.

Назначение платежа

LMI_PAYMENT_DESC

Описание платежа, как оно показывается пользователю. То есть, если в форме заказа платежа было указано LMI_PAYMENT_DESC64, то в этом запросе придет уже раскодированное из Base64 описание.

Контрольная подпись запроса

LMI_HASH

Контрольная подпись запроса, сформированная по правилам формирования контрольной подписи

Идентификатор плательщика в платежной системе

LMI_PAYER_IDENTIFIER

Идентификатор плательщика в платежной системе (WMID, маскированный номер банковской карты и т.п.)

Внешний идентификатор магазина в платежной системе

LMI_SHOP_ID

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

Страна местонахождения плательщика

LMI_PAYER_COUNTRY

Двухбуквенный код страны, если платежная система ее сообщает

Страна документа плательщика

LMI_PAYER_PASSPORT_COUNTRY

Двухбуквенный код страны, если платежная система ее сообщает

IP адрес плательщика

LMI_PAYER_IP_ADDRESS

IP адрес плательщика

Дополнительные параметры продавца

Определяются продавцом

Все дополнительные поля формы заказа платежа

В качестве ответа на данный запрос продавец может возвращать что угодно: ответ игнорируется системой 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 (в зависимости от настроек сайта) запрос с указанными ниже полями.

Название

Name

Описание 

Идентификатор продавца

 LMI_MERCHANT_ID

Идентификатор сайта в системе PayMaster

Внутренний номер счета продавца

LMI_PAYMENT_NO

Номер счета, заданный в запросе платежа

Номер платежа в системе PayMaster

LMI_SYS_PAYMENT_ID

(только для Success URL) Идентификатор платежа в системе PayMaster. Продавцу рекомендуется сохранить этот идентификатор.

Дата платежа

LMI_SYS_PAYMENT_DATE

(только для Success URL) Дата проведения платежа в системе PayMaster. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC.

Сумма платежа, заказанная продавцом

LMI_PAYMENT_AMOUNT

Дробное число с разделителем ".", не более 2 знаков после точки.

Валюта платежа, заказанная продавцом

LMI_CURRENCY

Это всегда 3-буквенный код валюты (http://www.currency-iso.org/iso_index/iso_tables/iso_tables_a1.htm)

Дополнительные параметры продавца

Определяются продавцом

Все дополнительные поля формы заказа платежа

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

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

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

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

Название

Описание

Роли пользователей

Администратор - изменение состояния сайта, управление сайтами, управление пользователями + права роли Бухгалтер и Программист.

Программист - просмотр и редактирование настроек сайта, просмотр списка платежей, сетевого обмена по платежам.

Бухгалтер - просмотр списка платежей и возвратов, информации о сайте, документов, списка перечислений, статистики по платежам, осуществление возвратов, выставление счетов на оплату.

Операционист - просмотр списка платежей, выставление счетов на оплату.

Состояние

Состояние готовности сайта к приему тестовых или реальных платежей (*)

Секретный ключ

Секретное слово задается в личном кабинете самостоятельно (раздел "Технические параметры"), ключ не должен содержать кириллических символов, а также спец.символов, например, &#060, &#062, &#160.

Секретное слово не передается по сети, и используется для формирования контрольной подписи запроса Payment Notification.

Проверять уникальность номера счета

Если этот параметр установлен, то система PayMaster не будет позволять посылать запросы на платеж с повторяющимися (или отсутствующими) LMI_PAYMENT_NO. Система будет сразу выдавать пользователю ошибку "неверный номер платежа" и возвращать его на Failure URL

Пользователь должен вернуться на сайт

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

Повторно отправлять Payment Notification при сбоях

Если этот параметр установлен, то Payment Notification будет отправлен повторно при сетевых сбоях. Перед включением: убедитесь, что не будет выполнено автоматическое повторное начисление средств плательщику (исполнение обязательств по платежу) при повторном получении Payment Notification!

Result URL

URL, на которую следует отсылать запрос Payment Notification

Invoice Confirmation URL

URL, на которую следует отсылать запрос Invoice Confirmation. Если этот параметр не задан, то он считается равным Result URL (т.е. запрос будет отправлен на Result URL с флагом LMI_PREREQUEST=1)

Success URL, method

URL страницы успешного платежа, а также способ запроса (GET, POST)

Failure URL, method

URL страницы неуспешного платежа, а также способ запроса (GET, POST)

Разрешена замена URL

Позволяет ли продавец указывать замененные URL в запросе платежа. Если этот параметр установлен, то в качестве замененных URL принимаются только URL из фиксированного множества (также задаваемого продавцом)

Тип подписи

Способ формирования хеша (контрольной подписи) - MD5 или SHA1

Методы использования платежных систем

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

Веб Оплата - оплата на странице PayMaster

Встроенный платеж - оплата на сайте продавца

Безакцептное списание - платеж по выданному доверию, без участия пользователя. Интерфейс Direct.

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

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

После создания и ввода данных о сайте продавцом, он ожидает проверки. После проверки сайта сотрудником 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):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        0
    </result>
    <id>
        123
    </id>
    <lastupdate>
        2012-05-04T12:28:45
    </lastupdate>
    <paymentUrl>
        https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e
    </paymentUrl>
    <amounts>
        <invoice id="643" abbr="RUB" amount="10" minamount="0" maxamount="0"/>
        <topay id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
    </amounts>
    <suberrorcode>
        0
    </suberrorcode>
    <messages>
        <message>
            <title>
                Дополнительно
            </title>
            <body>
                Вам был выдан ваучер сдачи,&lt;br/&gt;его реквизиты: &lt;b&gt;1231, 213&lt;/b&gt;.
            </body>
        </message>
    </messages>
</pm.response>

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

  • 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 тело сообщения.

  1. Неуспешное завершение платежа (https://paymaster.ru/BuiltinPayment/ResponseExample/Fail):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        1
    </result>
    <id>
        123
    </id>
    <lastupdate>
        2012-05-04T12:28:45
    </lastupdate>
    <paymentUrl>
        https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e
    </paymentUrl>
    <amounts>
        <invoice id="643" abbr="RUB" amount="10" minamount="0" maxamount="0"/>
        <topay id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
    </amounts>
    <suberrorcode>
        -17
    </suberrorcode>
    <messages>
        <message>
            <title>
                Ошибка
            </title>
            <body>
                Истек срок ожидания оплаты
            </body>
        </message>
    </messages>
</pm.response>

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

  • 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 - список сообщений с описанием ошибки

  1. Показ сообщения пользователю (https://paymaster.ru/BuiltinPayment/ResponseExample/ShowMessage):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        100
    </result>
    <id>
        123
    </id>
    <lastupdate>
        2012-05-04T12:28:45
    </lastupdate>
    <paymentUrl>
        https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e
    </paymentUrl>
    <amounts>
        <invoice id="643" abbr="RUB" amount="10" minamount="0" maxamount="0"/>
        <topay id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
    </amounts>
    <suberrorcode>
        0
    </suberrorcode>
    <messages>
        <message>
            <title>
                Завершение оплаты
            </title>
            <body>
                Вам был выписан счет.&lt;br/&gt;Пожалуйста, оплатите его
            </body>
        </message>
    </messages>
</pm.response>

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

  • 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 - список сообщений, которые надо показать

  1. Ввод пользовательских параметров (https://paymaster.ru/BuiltinPayment/ResponseExample/Requisites):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        101
    </result>
    <id>
        123
    </id>
    <lastupdate>
        2012-05-04T12:28:45
    </lastupdate>
    <requisites>
        <items>
            <textinput required="false">
                <name>
                    EMail
                </name>
                <title>
                    E-mail
                </title>
                <eg>
                    abc@abc.ru
                </eg>
                <regex>
                    [a-zA-Z0-9._%-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}
                </regex>
            </textinput>
            <textinput required="false">
                <name>
                    Phone
                </name>
                <title>
                    Телефон
                </title>
                <eg>
                    79161231231
                </eg>
                <regex>
                    [1-9]\d{10,13}
                </regex>
            </textinput>
            <check required="true" checked="false">
                <name>
                    CheckOption
                </name>
                <title>
                    Поставьте галочку
                </title>
            </check>
            <enum required="false">
                <name>
                    Choose
                </name>
                <title>
                    Выберите из списка
                </title>
                <options>
                    <option>
                        <value>
                            option1
                        </value>
                        <title>
                            Опция 1
                        </title>
                    </option>
                    <option>
                        <value>
                            option2
                        </value>
                        <title>
                            Опция 2
                        </title>
                    </option>
                </options>
            </enum>
            <label required="false">
                <name>
                    label1
                </name>
                <title>
                    Просто заголовок
                </title>
                <html>Просто
                    <br/>текст
                </html>
            </label>
            <proceed required="false">
                <name>
                    proceed
                </name>
                <title>
                    Сим удостоверяю, что перевод запускаем
                </title>
            </proceed>
        </items>
        <requirementgroups>
            <group>
                <description>
                    Пожалуйста, укажите E-mail и/или телефон
                </description>
                <names>
                    <name>
                        EMail
                    </name>
                    <name>
                        Phone
                    </name>
                </names>
            </group>
        </requirementgroups>
    </requisites>
    <paymentUrl>
        https://paymaster.ru/beta/builtinpayment/Process/sdf87987sdf878sdf
    </paymentUrl>
    <amounts>
        <invoice id="643" abbr="RUB" amount="10" minamount="0" maxamount="0"/>
        <topay id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
        <maychoosetopay>
            <currency id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
            <currency id="840" abbr="USD" amount="0.31" minamount="0" maxamount="0"/>
            <currency id="978" abbr="EUR" amount="0.2" minamount="0" maxamount="0"/>
        </maychoosetopay>
        <approximateothertopay>
            <currency id="980" abbr="UAH" amount="2" minamount="0" maxamount="0"/>
            <currency id="974" abbr="BYR" amount="10000" minamount="0" maxamount="0"/>
        </approximateothertopay>
    </amounts>
    <suberrorcode>
        0
    </suberrorcode>
</pm.response>

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

  • 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 - описание требования для показа пользователю.

  1. Ожидание статуса платежа (https://paymaster.ru/BuiltinPayment/ResponseExample/Pending):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        200
    </result>
    <id>
        123
    </id>
    <lastupdate>
        2012-05-04T12:28:45
    </lastupdate>
    <paymentUrl>
        https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e
    </paymentUrl>
    <amounts>
        <invoice id="643" abbr="RUB" amount="10" minamount="0" maxamount="0"/>
        <topay id="643" abbr="RUB" amount="10.9" minamount="0" maxamount="0"/>
    </amounts>
    <suberrorcode>
        0
    </suberrorcode>
</pm.response>

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

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

  1. Перенаправление пользователя на внешнюю страницу (https://paymaster.ru/BuiltinPayment/ResponseExample/Redirect):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        2
    </result>
    <id>
        123
    </id>
    <paymentUrl>
        http://redirectsite.ru/redirectpath
    </paymentUrl>
    <redirectdata method="post">
        <param name="key1">
            value1
        </param>
        <param name="key2">
            value2
        </param>
    </redirectdata>
    <suberrorcode>
        0
    </suberrorcode>
</pm.response>

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

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

  1. Сообщение о невозможности прочитать запрос (https://paymaster.ru/BuiltinPayment/ResponseExample/UnableToParse):
<?xml version="1.0" encoding="utf-8"?>
<pm.response>
    <result>
        -101
    </result>
    <paymentUrl>
        https://paymaster.ru/BultinPayment/Error/-101
    </paymentUrl>
    <suberrorcode>
        0
    </suberrorcode>
</pm.response>

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

  • 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 содержится короткая ссылка, на которую следует  

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

Коды ошибок

ErrorID

LiteralValue

-1

Неизвестная ошибка

-2

Неизвестная сетевая ошибка

-5

Сетевая ошибка платежной системы

-6

Доступ запрещен

-7

Неверная подпись запроса

-8

Продавец отказался от счета

-9

Счет просрочен

-10

Отказ платежной системы

-11

Возврат невозможен

-12

Превышена сумма возврата

-13

Идентификатор платежа не найден

-14

Идентификатор платежа уже существует

-15

Истек период ожидания платежа

-16

Симуляция ошибки по запросу продавца

-17

Вы отказались от платежа

-18

Недопустимая сумма платежа

-19

Недостаточно средств для проведения операции

-20

Внутренняя ошибка, обновите страницу

-21

Предыдущий платеж не завершен

-22

Отказ авторизации в платежной системе

-23

Действие не соответствует статусу платежа

-24

Платежная система временно отключена

-25

Ошибка при авторизации 3Dsec