NAV
  • Общие сведения
  • Проверка платежа
  • Возвраты
  • Холды
  • Документы и выплаты
  • Справочники
  • Общие сведения

    Аутентификация запросов

    Запросы необходимо передавать по защищенному протоколу (https). Базовый адрес сервиса https://paymaster.ru

    Все запросы выполняются от имени пользователей созданных со способом входа "Автоматический доступ". Пользователям должна быть назначена роль Операционист (получение статуса платежа и списка платежей) или Бухгалтер (Операционист + возврат платежа + список возвратов + подтверждение и отмена холдов). Все запросы должны обязательно содержать три поля: login, nonce и hash, посредством которых осуществляется аутентификация запросов:

    Если подпись запроса (hash) сформирована неверно, PayMaster возвращает код ошибки -7 (см. Коды ошибок).

    Обратите внимание, что при формировании GET-строки запроса все параметры (особенно это касается hash) следует URL-кодировать!

    Формат ответа

    Пример ответа:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "IsTestPayment": false,
        "LastUpdateTime": "2013-05-22T18:08:52"
      }
    }
    

    В ответ на запрос PayMaster всегда выдает HTTP-код 200. Если выдается другой код, то произошла ошибка на сервере при разборе запроса. Ответы PayMaster выдает в формате JSON.

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

    Проверка платежа

    Проверка по идентификатору платежа

    Пример запроса:

    GET /api/v1/getpayment?login=TestLogin&nonce=74DF1SM&hash=***&paymentid=1 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Оплата по заказу №12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52",
        "ErrorCode": 0
      }
    }
    

    GET /api/v1/getPayment

    Этот запрос используется для получения информации о платеже по его номеру в системе PayMaster.

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

    Имя Описание
    paymentID Идентификатор платежа в системе PayMaster (поле LMI_SYS_PAYMENT_ID)

    Хешируемые параметры: login;password;nonce;paymentID

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

    Имя Описание
    State Cостояние платежа см. Список состояний платежа
    ErrorCode Код причины отказа см. Коды ошибок
    Amount Cумма счета
    CurrencyCode 3-буквенный ISO код валюты
    IsTestPayment Признак тестового платежа (платеж совершен в тестовом режиме)
    LastUpdate (LastUpdateTime для JSON) Время последнего обновления статуса. Для завершенных платежей - время завершения платежа
    PaymentAmount Cумма оплаты
    PaymentCurrencyCode Валюта оплаты
    PaymentID Идентификатор платежа
    PaymentMethod Способ оплаты
    Purpose Примечание к платежу
    SiteID Идентификатор сайта - получателя платежа
    SiteInvoiceID Номер счета (параметр LMI_PAYMENT_NO)
    UserIdentifier Идентификатор пользователя в платежной системе
    UserPhoneNumber Номер телефона плательщика

    Проверка по номеру счета

    Пример запроса:

    GET /api/v1/getpaymentbyinvoiceid?login=TestLogin&nonce=74DF1SM&hash=***&invoiceid=1&siteAlias=yyy HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Оплата по заказу №12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    GET /api/v1/getPaymentByInvoiceID

    Этот запрос используется для получения информации о платеже по его номеру в системе учета продавца.

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

    Имя Описание
    invoiceID Номер счета (поле LMI_PAYMENT_NO)
    siteAlias Идентификатор сайта (поле LMI_MERCHANT_ID)

    Хешируемые параметры: login;password;nonce;invoiceID;siteAlias

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

    См. Детали платежа

    Получение списка платежей

    Пример запроса:

    GET /api/v1/listpaymentsfilter?login=TestLogin&nonce=74DF1SM&hash=***&periodFrom=2011-12-01 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Response": {
        "Overflow": false,
        "Payments": [{
            "PaymentID": 1,
            "SiteInvoiceID": "12345",
            "SiteID": 1,
            "CurrencyCode": "RUB",
            "Amount": 100,
            "PaymentMethod": "BankCard",
            "PaymentCurrencyCode": "RUB",
            "PaymentAmount": 100,
            "State": "COMPLETE",
            "Purpose": "Оплата по заказу №12345",
            "IsTestPayment": false,
            "LastUpdateTime": "2017-05-22T18:08:52"
          }, {
            "PaymentID": 2,
            "SiteInvoiceID": "12346",
            "SiteID": 1,
            "CurrencyCode": "RUB",
            "Amount": 100,
            "PaymentMethod": "BankCard",
            "PaymentCurrencyCode": "RUB",
            "PaymentAmount": 100,
            "State": "COMPLETE",
            "Purpose": "Оплата по заказу №12346",
            "IsTestPayment": false,
            "LastUpdateTime": "2017-05-22T18:08:52"
          }
        ]
      }
    }
    

    GET /api/v1/listPaymentsFilter

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

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

    Имя Описание
    accountID номер учетной записи в системе PayMaster. Его можно узнать из URL страницы "Учетная запись" в личном кабинете. Параметр accountID можно не указывать, если у вас всего одна учетная запись
    siteAlias идентификатор сайта (LMI_MERCHANT_ID). Если указан, то будут возвращены только платежи данного сайта
    periodFrom начало периода (yyyy-MM-dd), часовой пояс UTC. Если указан, то будут возвращены платежи только после указанной даты
    periodTo конец периода (yyyy-MM-dd), часовой пояс UTC. Если указан, то будут возвращены платежи только до указанной даты
    invoiceID номер счета. Если указан, то будут возвращены платежи только с таким номером счета
    state Состояние платежа. Если указано, то будут возвращены только платежи с указанным состоянием

    Хешируемые параметры: login;password;nonce;accountID;siteAlias;periodFrom;periodTo;invoiceID;state

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

    Имя Описание
    Overflow "true", если в ответе приведены не все платежи, удовлетворяющие фильтру. Если вам нужны все платежи, сузьте область поиска
    Payments Список платежей (см. Детали платежа)

    Возвраты

    Возврат платежа

    Пример запроса:

    POST /api/v1/refundPayment HTTP/1.1
    Host: paymaster.ru
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=131212&amount=23.10
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Refund": {
        "RefundID": 1073969831,
        "ExternalID": null,
        "PaymentID": 131212,
        "Amount": 23.10,
        "ErrorCode": null,
        "ErrorDesc": null,
        "State": "EXECUTING"
      }
    }
    

    POST /api/v1/refundPayment

    Этот запрос используется для осуществления возврата по платежу.

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

    Имя Описание
    paymentID Идентификатор платежа в системе PayMaster
    amount Сумма возврата
    externalID Идентификатор возврата в системе продавца, не обязательный (допускается не уникальное значение)

    При использовании онлайн-кассы дополнительно передаются параметры по чеку возврата.

    Имя Описание
    shoppingcart.items[n].name Наименование позиции в чеке
    shoppingcart.items[n].qty Кол-во товара
    shoppingcart.items[n].price Стоимость одной единицы
    shoppingcart.items[n].tax Ставка НДС

    Хешируемые параметры: login;password;nonce;paymentID;amount;externalID

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

    Имя Описание
    ExternalID Идентификатор операции возврата
    PaymentID Идентификатор платежа
    Status Статус возврата, см. Список состояний возврата
    Amount Сумма возврата
    ErrorCode Код ошибки, если возврат неуспешен (может отсутствовать)
    ErrorDesc Текстовое описание ошибки. Описание также может отсутствовать, если конкретная причина отказа неизвестна.

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

    Пример запроса:

    GET /api/v1/listRefunds?login=TestLogin&nonce=74DF1SM&hash=***&paymentID=131212&periodFrom=2017-01-01&periodTo=2017-11-11 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Response": {
        "Overflow": false,
        "Refunds": [{
            "RefundID": 1234,
            "ExternalID": null,
            "PaymentID": 12345,
            "Amount": 10.2,
            "ErrorCode": null,
            "ErrorDesc": null,
            "LastUpdate": "2017-04-17T23:12:02",
            "State": "SUCCESS"
          }, {
            "RefundID": 1236,
            "ExternalID": null,
            "PaymentID": 12346,
            "Amount": 120,
            "ErrorCode": -15,
            "ErrorDesc": "we’ve been waiting for too long time",
            "LastUpdate": "2017-04-17T12:15:02",
            "State": "FAILURE"
          }
        ]
      }
    }
    

    GET /api/v1/listRefunds

    Этот запрос используется для получения списка возвратов за период.

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

    Имя Описание
    accountID Номер учетной записи в системе PayMaster
    paymentID Идентификатор платежа. Если присутствует, то выводятся возвраты только по этому платежу
    periodFrom Начало периода (yyyy-mm-dd). Если отсутствует, то ограничения снизу нет
    periodTo Конец периода, включительно (yyyy-mm-dd). Если отсутствует, то ограничения сверху нет
    externalID Идентификатор возврата в системе продавца, не обязательный

    Хешируемые параметры: login;password;nonce;accountID;paymentID;periodFrom;periodTo;externalID При этом, если параметр отсутствует, то в хешируемую строку вставляется пустая строка (т.е. будут две подряд точки с запятыми).

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

    Имя Описание
    ErrorCode Код ошибки запроса (см. Коды ошибок)
    Overflow true, если выдан не весь список возвратов. В этом случае следует указать более узкий диапазон для поиска
    Refunds Список возвратов. Каждый объект - такой же, как и объект Response первого запроса

    Холды

    Подтверждение платежа

    Пример запроса:

    POST /api/v1/ConfirmPayment HTTP/1.1
    Host: paymaster.ru
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=1232&amount=11
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Оплата по заказу №12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    POST /api/v1/confirmPayment

    Этот метод используется для завершения платежа, по которому были холдированы средства. В некоторых случаях возможно указать для списания меньшую (чем сумма холда) сумму.

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

    Имя Описание
    paymentID Идентификатор платежа в системе PayMaster (поле LMI_SYS_PAYMENT_ID)
    amount Реальная сумма списания

    Хешируемые параметры: login;password;nonce;paymentID;amount

    Отмена платежа

    Пример запроса:

    POST /api/v1/CancelPayment HTTP/1.1
    Host: paymaster.ru
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=1232&error=-8
    

    Пример ответа:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Оплата по заказу №12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    POST /api/v1/cancelPayment

    Этот запрос используется для отмены холда и разблокирования средств плательщика.

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

    Имя Описание
    paymentID Идентификатор платежа в системе PayMaster (поле LMI_SYS_PAYMENT_ID)
    error Опциональный параметр. Код ошибки из списка Коды ошибок

    Хешируемые параметры: login;password;nonce;paymentID;error

    Документы и выплаты

    Список документов

    Пример запроса:

    GET /api/v1/listDocuments?login=TestLogin&nonce=74DF1SM&hash=***&accountID=123&periodFrom=2005-02-17&periodTo=2013-06-17&xml=1 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers"xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ErrorCode>
            0
        </ErrorCode>
        <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST"i:type="a:RestDocumentList">
            <a:Documents>
                <a:RestDocumentInfo>
                    <a:Created>
                        2013-06-17T12:57:03.6470638Z
                    </a:Created>
                    <a:Description>
                        Акт выполненных работ за Март 2012 г
                    </a:Description>
                    <a:DocumentID>
                        123456
                    </a:DocumentID>
                    <a:FileName>
                        act_052012.xls
                    </a:FileName>
                </a:RestDocumentInfo>
                <a:RestDocumentInfo>
                    <a:Created>
                        2013-06-17T12:57:03.6470638Z
                    </a:Created>
                    <a:Description>
                        Invoice #1123 for 05/2012
                    </a:Description>
                    <a:DocumentID>
                        123456
                    </a:DocumentID>
                    <a:FileName>
                        doc_052012.xls
                    </a:FileName>
                </a:RestDocumentInfo>
            </a:Documents>
        </Response>
    </RestController.RestResponse>
    

    GET /api/v1/listDocuments

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

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

    Имя Описание
    accountID Номер учетной записи в системе PayMaster. Его можно узнать из URL страницы "Учетная запись" в личном кабинете
    periodFrom Начало периода (yyyy-MM-dd), часовой пояс UTC. Если указан, то будут возвращены документы, созданные только после указанной даты
    periodTo Конец периода (yyyy-MM-dd), часовой пояс UTC. Если указан, то будут возвращены документы, созданные только до указанной даты

    Хешируемые параметры: login;password;nonce;accountID;periodFrom;periodTo

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

    Имя Описание
    Created Дата создания документа
    Description Описание документа
    DocumentID Идентификатор для выгрузки содержимого
    FileName Имя файла

    Скачивание документа

    Пример запроса:

    GET /api/v1/getDocumentContent?login=TestLogin&nonce=74DF1SM&hash=***&documentID=123456 HTTP/1.1
    Host: paymaster.ru
    

    GET /api/v1/getDocumentContent

    Этот запрос используется для скачивания документа по его идентификатору. В ответe выдается содержимое документа.

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

    Имя Описание
    documentID Идентификатор документа

    Хешируемые параметры: login;password;nonce;documentID

    Получение списка выплат

    Пример запроса:

    GET /api/v1/listTransfers?login=TestLogin&nonce=74DF1SM&hash=***&accountID=123&periodFrom=2005-02-17&periodTo=2013-06-17&xml=1 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ErrorCode>
            0
        </ErrorCode>
        <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST" i:type="a:RestTransferList">
            <a:Transfers>
                <a:RestTransferInfo>
                    <a:Created>
                        2017-09-04T09:36:29.186576Z
                    </a:Created>
                    <a:CurrencyCode>
                        RUB
                    </a:CurrencyCode>
                    <a:PaymentOrderID>
                        11223/4
                    </a:PaymentOrderID>
                    <a:RegisterID>
                        54
                    </a:RegisterID>
                    <a:TransferAmount>
                        101150.00
                    </a:TransferAmount>
                </a:RestTransferInfo>
                <a:RestTransferInfo>
                    <a:Created>
                        2017-09-04T09:36:29.186576Z
                    </a:Created>
                    <a:CurrencyCode>
                        RUB
                    </a:CurrencyCode>
                    <a:PaymentOrderID>
                        11223/5
                    </a:PaymentOrderID>
                    <a:RegisterID>
                        55
                    </a:RegisterID>
                    <a:TransferAmount>
                        20000.00
                    </a:TransferAmount>
                </a:RestTransferInfo>
            </a:Transfers>
        </Response>
    </RestController.RestResponse>
    

    GET /api/v1/listTransfers

    Этот запрос используется для получения списка выплат за указанный период.

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

    Имя Описание
    accountID Номер учетной записи в системе PayMaster. Его можно узнать из URL страницы "Учетная запись" в личном кабинете
    periodFrom Начало периода (yyyy-MM-dd), часовой пояс UTC
    periodTo Начало периода (yyyy-MM-dd), часовой пояс UTC

    Хешируемые параметры: login;password;nonce;accountID;periodFrom;periodTo

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

    Имя Описание
    Created Дата совершения выплаты
    CurrencyCode Код валюты выплаты
    TransferAmount Сумма перечисления
    PaymentOrderID Номер платежного поручения
    RegisterID Идентификатор реестра

    Выгрузка реестра по выплате

    Пример запроса:

    GET /api/v1/getTransferRegister?login=TestLogin&nonce=74DF1SM&hash=***&registerID=123&xml=1 HTTP/1.1
    Host: paymaster.ru
    

    Пример ответа:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ErrorCode>
            0
        </ErrorCode>
        <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST" i:type="a:RestRegisterInfo">
            <a:Operations>
                <a:RestRegisterOperationInfo>
                    <a:CurrencyCode>
                        RUB
                    </a:CurrencyCode>
                    <a:InvoiceID>
                        SO223
                    </a:InvoiceID>
                    <a:OperationAmount>
                        1000.00
                    </a:OperationAmount>
                    <a:OperationID>
                        11022
                    </a:OperationID>
                    <a:Stamp>
                        2017-09-04T00:00:00Z
                    </a:Stamp>
                    <a:TransferAmount>
                        998.00
                    </a:TransferAmount>
                </a:RestRegisterOperationInfo>
                <a:RestRegisterOperationInfo>
                    <a:CurrencyCode>
                        RUB
                    </a:CurrencyCode>
                    <a:InvoiceID>
                        SO224
                    </a:InvoiceID>
                    <a:OperationAmount>
                        1500.00
                    </a:OperationAmount>
                    <a:OperationID>
                        11027
                    </a:OperationID>
                    <a:Stamp>
                        2017-09-04T00:00:00Z
                    </a:Stamp>
                    <a:TransferAmount>
                        1497.00
                    </a:TransferAmount>
                </a:RestRegisterOperationInfo>
            </a:Operations>
            <a:PeriodFrom>
                2017-09-03T00:00:00Z
            </a:PeriodFrom>
            <a:PeriodTo>
                2017-09-04T00:00:00Z
            </a:PeriodTo>
            <a:RegisterID>
                54
            </a:RegisterID>
            <a:RegisterNumber>
                540/44
            </a:RegisterNumber>
        </Response>
    </RestController.RestResponse>
    

    GET /api/v1/getTransferRegister

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

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

    Имя Описание
    registerID Идентификатор реестра.

    Хешируемые параметры: login;password;nonce;registerID

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

    Имя Описание
    PeriodFrom Начало периода
    PeriodTo Конец периода
    RegisterNumber Номер реестра
    Operations Список платежей и возвратов по реестру
    OperationID Идентификатор операции
    InvoiceID Номер счета мерчанта
    Stamp Дата операции
    CurrencyCode Код валюты операции
    OperationAmount Сумма операции
    TransferAmount Сумма выплаты по операции

    Справочники

    Коды ошибок

    Возможные значения поля ErrorCode ответа от PayMaster:

    Код Описание
    -1 Неизвестная ошибка. Сбой в системе PayMaster. Если ошибка повторяется, обратитесь в техподдержку
    -2 Сетевая ошибка. Сбой в системе PayMaster. Если ошибка повторяется, обратитесь в техподдержку
    -6 Нет доступа. Неверно указан логин, или у данного логина нет прав на запрошенную информацию
    -7 Неверная подпись запроса. Неверно сформирован хеш запроса
    -8 Платеж отклонен продавцом на этапе предзапроса.
    -9 Истек срок действия счета
    -10 Платеж отклонен платежной системой
    -13 Платеж не найден по номеру счета
    -14 Повторный запрос с тем же nonce
    -15 Срок жизни платежа истек, и платеж отменен
    -17 Пользователь отказался от оплаты
    -18 Неверное значение суммы (в случае возвратов имеется в виду значение amount)
    -19 У пользователя недостаточно средств для оплаты
    -22 Не удалось авторизоваться в платежной системе
    -25 3D Secure авторизация не пройдена
    -26 Неверный номер карты
    -27 Истек срок действия карты
    -28 Карта блокировна
    -29 Превышен лимит по сумме платежа
    -30 Превышен лимит по количеству платежей
    -31 Недопустимая операция по карте

    Статусы состояния платежа

    Имя Описание
    INITIATED Платеж начат
    PROCESSING Платеж проводится
    COMPLETE Платеж завершен успешно
    CANCELLED Платеж завершен неуспешно
    HOLD Средства захолдированы

    Статусы состояния возврата

    Имя Описание
    PENDING Поставлен в очередь на совершение операции возврата
    EXECUTING Проведение транзакции возврата платежа
    SUCCESS Возврат средств успешно завершен
    FAILURE Возврат средств не осуществлен