NAV Navbar
  • Платежные формы
  • Страницы возврата
  • Настройки учетной записи
  • Средства проверки статуса платежа
  • Автоматизированное выставление счетов на оплату товара/услуги
  • Приложения
  • Платежные формы

    Схема работы

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

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

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

    alt text

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

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

    Параметр Обязательный Описание
    LMI_MERCHANT_ID Да Идентификатор сайта в системе PayMaster. Идентификатор можно увидеть в Личном Кабинете, на странице "Список сайтов", в первой колонке.
    LMI_PAYMENT_AMOUNT Да Сумма платежа, которую продавец желает получить от покупателя. Сумма должна быть больше нуля, дробная часть отделяется точкой.
    LMI_CURRENCY Да Идентификатор валюты платежа. Система понимает как текстовый 3-буквенный код валюты (RUB), так и целочисленный код (643) по ISO 4217.
    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% - не выполнены.
    LMI_PAYMENT_TYPE Нет HOLD - платеж с предавторизацией (холдированием). Сервис выполнит холдирование в случае, если платежная система это позволяет.
    LMI_INVOICE_CONFIRMATION_URL Нет Если присутствует, то запрос Invoice Confirmation будет отправляться по указанному URL (а не установленному в настройках). Этот параметр игнорируется, если в настройках сайта запрещена замена URL.
    LMI_PAYMENT_NOTIFICATION_URL Нет Если присутствует, то запрос Payment Notification будет отправляться по указанному URL (а не установленному в настройках). Этот параметр игнорируется, если в настройках сайта запрещена замена URL.
    LMI_SUCCESS_URL Нет Если присутствует, то при успешном платеже пользователь будет отправлен по указанному URL (а не установленному в настройках). Этот параметр игнорируется, если в настройках сайта запрещена замена URL.
    LMI_SUCCESS_METHOD Нет GET/POST, метод вызова SuccessUrl
    LMI_FAIL_URL Нет Если присутствует, то при отмене платежа пользователь будет отправлен по указанному URL (а не установленному в настройках). Этот параметр игнорируется, если в настройках сайта запрещена замена URL.
    LMI_FAIL_METHOD Нет GET/POST, метод вызова FailUrl
    LMI_PAYER_PHONE_NUMBER Нет Номер телефона покупателя в международном формате без ведущих символов + (например, 79031234567). Эти данные используются системой PayMaster для оповещения пользователя о статусе платежа. Кроме того, некоторые платежные системы требуют указания номера телефона.
    LMI_PAYER_EMAIL Нет E-mail покупателя. Эти данные используются системой PayMaster для оповещения пользователя о статусе платежа. Кроме того, некоторые платежные системы требуют указания e-mail.
    LMI_EXPIRES Нет Дата и время, до которого действует выписанный счет. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC. Система PayMaster приложит все усилия, чтобы отклонить платеж при истечении срока, но не может гарантировать этого.
    LMI_PAYMENT_METHOD Нет Идентификатор платежного метода, выбранный пользователем. Отсутствие означает, что пользователь будет выбирать платежный метод на странице оплаты PayMaster. Платежный метод указан в настройках сайта в квадратных cкобках рядом с названием платежной системы (Например: Webmoney [WebMoney]).
    Дополнительные параметры продавца Нет Все поля формы, не имеющие в названии префикса "LMI_" и " AP_" обрабатываются системой PayMaster автоматически и передаются на веб-сайт продавца после выполнения платежа.

    При использовании онлайн-кассы необходимо передавать дополнительные параметры с даннымы по позициям чека (до 100 позиций).

    Параметр Описание
    LMI_SHOPPINGCART.ITEMS[N].NAME Наименование позиции в чеке.
    LMI_SHOPPINGCART.ITEMS[N].QTY Кол-во товара.
    LMI_SHOPPINGCART.ITEMS[N].PRICE Стоимость одной единицы.
    LMI_SHOPPINGCART.ITEMS[N].TAX Ставка НДС, допустимые значения.

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

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

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

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

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

    Invoice Confirmation

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

    Параметры запроса

    Параметр Описание
    LMI_PREREQUEST Флаг предзапроса. Значение всегда "1"
    LMI_MERCHANT_ID Идентификатор сайта в системе PayMaster
    LMI_PAYMENT_AMOUNT Сумма платежа, заказанная продавцом. Дробное число с разделителем ".", не более 2 знаков после точки.
    LMI_CURRENCY Валюта платежа, заказанная продавцом.
    LMI_PAID_AMOUNT Сумма платежа в валюте, в которой покупатель производит платеж. Дробное число с разделителем ".", не более 2 знаков после точки.
    LMI_PAID_CURRENCY Валюта, в которой производится платеж. Строковый код валюты (не обязательно ISO).
    LMI_PAYMENT_METHOD Идентификатор платежного метода, выбранный пользователем.
    LMI_SIM_MODE Флаг тестового режима. Это поле присутствует только если платеж производится в тестовом режиме. Значения - те же, что и в форме заказа платежа.
    LMI_PAYMENT_DESC Описание платежа, как оно показывается пользователю. То есть, если в форме заказа платежа было указано LMI_PAYMENT_DESC64, то в этом запросе придет уже раскодированное из Base64 описание.
    Дополнительные параметры продавца Определяются продавцом. Сюда входят все дополнительные поля формы заказа платежа.

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

    Payment Notification

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

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

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

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

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

    Параметры запроса

    Параметр Описание
    LMI_MERCHANT_ID Идентификатор сайта в системе PayMaster.
    LMI_PAYMENT_NO Внутренний номер счета продавца, заданный в запросе платежа.
    LMI_SYS_PAYMENT_ID Идентификатор платежа в системе PayMaster. Продавцу рекомендуется сохранить этот идентификатор.
    LMI_SYS_PAYMENT_DATE Дата проведения платежа в системе PayMaster. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC.
    LMI_PAYMENT_AMOUNT Сумма платежа, заказанная продавцом. Дробное число с разделителем ".", не более 2 знаков после точки.
    LMI_CURRENCY Валюта платежа, заказанная продавцом.
    LMI_PAID_AMOUNT Сумма платежа в валюте, в которой покупатель производит платеж. Дробное число с разделителем ".", не более 2 знаков после точки.
    LMI_PAID_CURRENCY Валюта, в которой производится платеж. Строковый код валюты (не обязательно ISO).
    LMI_PAYMENT_METHOD Идентификатор платежного метода, выбранный пользователем..
    LMI_SIM_MODE Флаг тестового режима. Это поле присутствует только если платеж производится в тестовом режиме. Значения - те же, что и в форме заказа платежа.
    LMI_PAYMENT_DESC Описание платежа, как оно показывается пользователю. То есть, если в форме заказа платежа было указано LMI_PAYMENT_DESC64, то в этом запросе придет уже раскодированное из Base64 описание.
    LMI_HASH Контрольная подпись запроса, сформированная по правилам формирования контрольной подписи
    LMI_PAYER_IDENTIFIER Идентификатор плательщика в платежной системе (WMID, маскированный номер банковской карты и т.п.)
    LMI_PAYER_COUNTRY Код страны местонахождения плательщика, если платежная система его сообщает.
    LMI_PAYER_PASSPORT_COUNTRY Код страны гражданства плательщика, если платежная система его сообщает.
    LMI_PAYER_IP_ADDRESS IP адрес плательщика.
    Дополнительные параметры продавца Определяются продавцом. Сюда входят все дополнительные поля формы заказа платежа.

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

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

    Payment Status Notification

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

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

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

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

    Следующие параметры записываются в одну строчку, разделенные символом ‘;’:

    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 в рабочем(!) режиме всегда рассматривается пустым.

    Если запрос представляет собой нотификацию о статусе операции, что к параметрам через точку с запятой добавляется LMI_PAYMENT_STATUS.

    К строке добавляется еще один символ ‘;’ и секретное слово, указанное в настройках сайта. Полученная строка рассматривается как массив байтов в кодировке UTF-8, и от нее вычисляется хеш MD5 или SHA1 (в зависимости от того, какой метод указан в настройках продавца).

    Этот хеш (последовательность байт) преобразовывается в Base64-строку. Эта строка и есть значение параметра LMI_HASH.

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

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

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

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

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

    Параметры запроса

    Параметр Описание
    LMI_MERCHANT_ID Идентификатор сайта в системе PayMaster.
    LMI_PAYMENT_NO Внутренний номер счета продавца, заданный в запросе платежа.
    LMI_SYS_PAYMENT_ID Идентификатор платежа в системе PayMaster. Продавцу рекомендуется сохранить этот идентификатор.
    LMI_SYS_PAYMENT_DATE Дата проведения платежа в системе PayMaster. Формат YYYY-MM-DDThh:mm:ss, часовой пояс UTC.
    LMI_PAYMENT_AMOUNT Сумма платежа, заказанная продавцом. Дробное число с разделителем ".", не более 2 знаков после точки.
    LMI_CURRENCY Валюта платежа, заказанная продавцом.
    Дополнительные параметры продавца Определяются продавцом. Сюда входят все дополнительные поля формы заказа платежа.

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

    Настройки сайта

    Параметр Описание
    Состояние Состояние готовности сайта к приему тестовых или реальных платежей (*)
    Секретный ключ Секретное слово задается в личном кабинете самостоятельно (раздел "Технические параметры"), ключ не должен содержать кириллических символов, а также спец.символов, например, <, >,  . Секретное слово не передается по сети, и используется для формирования контрольной подписи запроса 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 Разрешено ипользовать адреса возврата, указанные в форме запроса платежа.
    Тип подписи Способ формирования хеша (контрольной подписи) - SHA1 или SHA256

    Состояния сайта

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

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

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

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

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

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

    Схема работы

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

    При формировании счета на оплату в подписи участвуют параметры 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 представления.

    Получение ответа в виде JSON или XML (XSD схему можно взять тут)

    Приложения

    Коды ошибок

    ErrorID Описание
    -1 Неизвестная ошибка
    -2 Неизвестная сетевая ошибка
    -5 Сетевая ошибка платежной системы
    -6 Доступ запрещен
    -7 Неверная подпись запроса
    -8 Продавец отказался от счета
    -9 Счет просрочен
    -10 Отказ платежной системы
    -11 Возврат невозможен
    -12 Превышена сумма возврата
    -13 Идентификатор платежа не найден
    -14 Идентификатор платежа уже существует
    -15 Истек период ожидания платежа
    -16 Симуляция ошибки по запросу продавца
    -17 Вы отказались от платежа
    -18 Недопустимая сумма платежа
    -19 Недостаточно средств для проведения операции
    -20 Внутренняя ошибка, обновите страницу
    -21 Предыдущий платеж не завершен
    -22 Отказ авторизации в платежной системе
    -23 Действие не соответствует статусу платежа
    -24 Платежная система временно отключена
    -25 Ошибка при авторизации 3Dsec

    Значения НДС

    Аргумент Значение
    vat18 НДС 18%
    vat10 НДС 10%
    vat118 НДС по формуле 18/118
    vat110 НДС по формуле 10/110
    vat0 НДС 0%
    no_vat НДС не облагается