NAV Navbar
  • Встроенные платежи
  • Значения результатов (result)
  • Коды ошибок
  • Встроенные платежи

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

    Схема работы

    1. Запуск платежа через отправку запроса на https://paymaster.ru/builtinpayment/init. Параметры запроса остаются те же, что и в обычной форме запроса платежа, со следующими отличиями:
      • добавляется обязательный параметр 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 представления.
      • LMI_PAYMENT_METHOD - обязательный параметр, значение должно быть указано;
      • добавляется необязательный параметр json. Если он равен 1, то ответ возвращается в виде JSON, иначе ответ возвращается в виде Xml.
      • добавляется необязательный параметр currencyID, означающий в какой валюте будет платить пользователь (не путать с LMI_CURRENCY, которая означает, в какой валюте продавец получит оплату);
      • добавляется необязательный параметр culture, в который можно передать значение LCID языка, на котором нужно выдавать информационные сообщения.
      • добавляются параметры вида values[name], означающие заполненные пользователем параметры платежа (аналогично автопараметрам). На первом шаге заполнение параметров возможно только если продавец заранее знает, какие параметры попросит ввести платежная система.
    2. Получение ответа в виде JSON или Xml.
    3. В зависимости от кода возврата возможны следующие действия:
      • успешное завершение платежа, показ пользователю сообщения об этом и, если указано, дополнительной информации о совершенном платеже;
      • неуспешное завершение платежа, показ пользователю сообщения об ошибке;
      • показ пользователю сообщения. В этом случае нужно через некоторое время повторить пустой запрос на Url, указанную в ответе, и снова перейти к шагу 2;
      • ввод пользовательских параметров. В этом случае продавец должен будет отправить значения введенных пользователем реквизитов на PaymentUrl, указанную в ответе. Параметры отправляются согласно описанию на шаге 1.После отправки параметров действовать согласно шагу 2 и т.д.;
      • ожидание статуса платежа. В этом случае нужно через некоторое время повторить пустой запрос на Url, указанную в ответе, и снова перейти к шагу 2.
      • перенаправление пользователя на внешнюю страницу оплаты. Некоторые платежные системы требуют перенаправления пользователя на свои платежные страницы. В этом случае продавцу сообщается Url для перенаправления;
      • сообщение о невозможности прочитать запрос.

    Типы параметров

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

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

    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>0</result>
        <id>123</id>
        <lastupdate>2017-10-04T12:28:45</lastupdate>
        <paymentUrl>https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e</paymentUrl>
        <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/messages список сообщений с дополнительной информацией, которые надо показать пользователю.
    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>1</result>
        <id>123</id>
        <paymentUrl>https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e</paymentUrl>
        <suberrorcode>-17</suberrorcode>
        <messages>
            <message>
                <title>Ошибка</title>
                <body>Истек срок ожидания оплаты</body>
            </message>
        </messages>
    </pm.response>
    

    Завершение платежа с ошибкой

    Поле Описание
    pm.response/result код возврата. 1-99 - не удалось провести платеж;
    pm.response/id номер платежа в PayMaster;
    pm.response/suberrorcode код ошибки, см. раздел "Коды ошибок";
    pm.response/paymentUrl Url платежа;
    pm.response/messages список сообщений с описанием ошибки
    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>100</result>
        <id>123</id>
        <paymentUrl>https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e</paymentUrl>
        <messages>
            <message>
                <title>Завершение оплаты</title>
                <body>Вам был выписан счет.&lt;br/&gt;Пожалуйста, оплатите его</body>
            </message>
        </messages>
    </pm.response>
    

    Сообщение для плательщика

    Поле Описание
    pm.response/result код возврата. 1-99 - не удалось провести платеж;
    pm.response/id номер платежа в PayMaster;
    pm.response/paymentUrl Url, по которой надо отправить следующий запрос. Запрос должен быть пустой;
    pm.response/messages список сообщений, которые надо показать
    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>101</result>
        <id>123</id>
        <paymentUrl>https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e</paymentUrl>
        <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>
            </items>
            <requirementgroups>
                <group>
                    <description>Пожалуйста, укажите E-mail и/или телефон</description>
                    <names>
                        <name>EMail</name>
                        <name>Phone</name>
                    </names>
                </group>
            </requirementgroups>
        </requisites>
    </pm.response>
    

    Ввод данных

    Поле Описание
    pm.response/result код возврата. 101 - необходимо прислать параметры, введенные пользователем;
    pm.response/id номер платежа в PayMaster;
    pm.response/paymentUrl Url платежа, на который надо отправлять следующий запрос, содержащий параметры вида values[name];
    pm.response/requisites/items пользовательские параметры, которые необходимо ввести. У каждого параметра есть аттрибут name, который надо передавать в качестве name в параметрах values[name], о которых говорилось выше.
    pm.response/requisites/requirementgroup список групп параметров, для которых требуется заполнение одного из них. Для вышеприведенного примера это означает, что пользователю нужно заполнить либо параметр EMail, либо параметр Phone. description - описание требования для показа пользователю.
    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>200</result>
        <id>123</id>
        <paymentUrl>https://paymaster.ru/builtinpayment/process/d011b332-72d5-4626-8237-309ce90f718e</paymentUrl>
    </pm.response>
    

    Ожидание статуса платежа

    Поле Описание
    pm.response/result код возврата. 200 - необходимо повторить запрос через некоторое время (без пользовательских параметров). Если поле CustomTrackPaymentText не пустое, то надо транслировать его;
    pm.response/id номер платежа в PayMaster;
    pm.response/paymentUrl Url платежа, на который надо отправлять следующий запрос. Запрос должен быть пустым;
    <?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>
    </pm.response>
    

    Перенаправление пользователя на внешнюю страницу

    Поле Описание
    pm.response/result код возврата. 2 - необходимо перенаправить пользователя на внешнюю страницу оплаты;
    pm.response/id номер платежа в PayMaster;
    pm.response/paymentUrl Url, куда надо перенаправить пользователя;
    pm.response/redirectdata/@method HTTP метод перенаправления;
    pm.response/redirectdata/param параметры, с которыми надо выполнить перенаправление;
    <?xml version="1.0" encoding="utf-8"?>
    <pm.response>
        <result>-101</result>
        <paymentUrl> https://paymaster.ru/bultinpayment/error/-101</paymentUrl>
    </pm.response>
    

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

    Поле Описание
    pm.response/result код возврата. -101 - не удалось прочитать запрос;
    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 платеж успешно проведен;

    Коды ошибок

    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