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

    Это старая версия API. Переходите на новую версию API.

    Схема работы

    Компания (продавец) взаимодействует с 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_SHOP_IDДа (только для интеграторов)Идентификатор суб-мерчанта. Необходимо передавать, если вы работаете как агрегатор платежей.
    LMI_PAYMENT_METHODНетИдентификатор платежного метода, выбранный пользователем. Отсутствие означает, что пользователь будет выбирать платежный метод на странице оплаты PayMaster. Платежный метод указан в настройках сайта в квадратных cкобках рядом с названием платежной системы (Например: Webmoney [WebMoney]).
    Параметры фискализацииНетПри использовании онлайн-кассы необходимо передавать дополнительные параметры с данными по позициям чека.
    Дополнительные параметры продавцаНетВсе поля формы, не имеющие в названии префикса "LMI_" и " AP_" обрабатываются системой PayMaster автоматически и передаются на веб-сайт продавца после выполнения платежа.

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

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

    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_ADDRESSIP адрес плательщика.
    LMI_PAYMENT_SYSTEMИдентификатор шлюза.
    Дополнительные параметры продавцаОпределяются продавцом. Сюда входят все дополнительные поля формы заказа платежа.

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

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

    Payment Status Notification

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

    Присылаемые параметры остаются те же, что и для 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 URLURL, на которую следует отсылать запрос Payment Notification
    Invoice Confirmation URLURL, на которую следует отсылать запрос Invoice Confirmation. Если этот параметр не задан, то он считается равным Result URL (т.е. запрос будет отправлен на Result URL с флагом LMI_PREREQUEST=1)
    Success URL, methodURL страницы успешного платежа, а также способ запроса (GET, POST)
    Failure URL, methodURL страницы неуспешного платежа, а также способ запроса (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 представления.

    Онлайн-касса

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

    Допускается до 100 позиций в чеке. Нумерация позиций должна начинаться с 0.

    ПараметрОписаниеОбязательный
    LMI_SHOPPINGCART.ITEMS[N].NAMEНаименование позиции в чеке.Да
    LMI_SHOPPINGCART.ITEMS[N].QTYКол-во товара. Три знака в дробной части, разделитель - точка.Да
    LMI_SHOPPINGCART.ITEMS[N].PRICEСтоимость одной единицы. Два знака в дробной части, разделитель - точка.Да
    LMI_SHOPPINGCART.ITEMS[N].TAXСтавка НДС.Да
    LMI_SHOPPINGCART.ITEMS[N].AGENT.TYPEПризнак агента по предмету расчета.Нет
    LMI_SHOPPINGCART.ITEMS[N].METHODПризнак способа расчета, по умолчанию "1".Нет
    LMI_SHOPPINGCART.ITEMS[N].SUBJECTПризнак предмета расчета, по умолчанию "1".Нет
    LMI_SHOPPINGCART.ITEMS[N].SUPPLIER.NAMEИмя поставщикаНет
    LMI_SHOPPINGCART.ITEMS[N].SUPPLIER.INNИНН поставщикаНет
    LMI_SHOPPINGCART.ITEMS[N].SUPPLIER.PHONES[0]Телефон поставщика в формате 79001234567Нет
    LMI_SHOPPINGCART.PAYER.INNИНН покупателяНет
    LMI_SHOPPINGCART.PAYER.NAMEИмя покупателяНет
    LMI_SHOPPINGCART.ITEMS[N].UNITЕдиница измерения предмета расчетаНет
    LMI_SHOPPINGCART.ITEMS[N].EXCISEАкциз. Два знака в дробной части, разделитель - точка.Нет
    LMI_SHOPPINGCART.ITEMS[N].PRODUCT.CODEКод товарной номенклатуры.Нет
    LMI_SHOPPINGCART.ITEMS[N].PRODUCT.COUNTRYКод страны происхождения товара, ISO-alpha2.Нет
    LMI_SHOPPINGCART.ITEMS[N].PRODUCT.DECLARATIONНомер таможенной декларации.Нет

    Значения НДС

    ЗначениеОписание
    vat20НДС 20%
    vat10НДС 10%
    vat120НДС по формуле 20/120
    vat110НДС по формуле 10/110
    vat0НДС 0%
    no_vatНДС не облагается

    Признак агента по предмету расчета

    ЗначениеОписание
    0Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом банковским платежным агентом
    1Оказание услуг покупателю (клиенту) пользователем, являющимся банковским платежным агентом банковским платежным субагентом
    2Оказание услуг покупателю (клиенту) пользователем, являющимся платежным агентом
    3Оказание услуг покупателю (клиенту) пользователем, являющимся платежным субагентом
    4Осуществление расчета с покупателем (клиентом) пользователем, являющимся поверенным
    5Осуществление расчета с покупателем (клиентом) пользователем, являющимся комиссионером
    6Осуществление расчета с покупателем (клиентом) пользователем, являющимся агентом и не являющимся банковским платежным агентом (субагентом), платежным агентом (субагентом), поверенным, комиссионером

    Признак способа расчета

    ЗначениеОписание
    1Полная предварительная оплата до момента передачи предмета расчета
    2Частичная предварительная оплата до момента передачи предмета расчета
    3Аванс
    4Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета
    5Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит
    6Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит
    7Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита)

    Признак предмета расчета

    ЗначениеОписание
    1Товар
    2Подакцизный товар
    3Работа
    4Услуга
    5Ставка азартной игры
    6Выигрыш азартной игры
    7Лотерейный билет
    8Выигрыш лотереи
    9Предоставление РИД
    10Платеж
    11Агентское вознаграждение
    12Составной предмет расчета
    13Иной предмет расчета
    14Имущественное право
    15Внереализационный доход
    16Страховые взносы
    17Торговый сбор
    18Курортный сбор
    19Залог

    Приложения

    Коды ошибок

    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
    -26Неверный номер карты
    -27Истек срок действия карты
    -28Карта блокировна
    -29Превышен лимит по сумме платежа
    -30Превышен лимит по количеству платежей
    -31Недопустимая операция по карте