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

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

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

    Встроенные платежи - это платежи, которые проводятся без отправки пользователя на сайт 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/paymentUrlUrl платежа;
    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/paymentUrlUrl платежа;
    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/paymentUrlUrl, по которой надо отправить следующий запрос. Запрос должен быть пустой;
    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/paymentUrlUrl платежа, на который надо отправлять следующий запрос, содержащий параметры вида 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/paymentUrlUrl платежа, на который надо отправлять следующий запрос. Запрос должен быть пустым;
    <?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/paymentUrlUrl, куда надо перенаправить пользователя;
    pm.response/redirectdata/@methodHTTP метод перенаправления;
    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