Общие сведения

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

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

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

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

login - логин пользователя. Этот логин не может использоваться для входа в личный кабинет: только для аутентификации REST-запросов.
password - пароль пользователя.
nonce - одноразовый тикет запроса. Это произвольная строка не более, чем из 255 символов, не содержащая символа ‘;’. Вам следует генерировать одноразовый тикет для каждого запроса. Это сделано для того, чтобы злоумышленник, даже перехватив однажды запрос, не смог его повторить.
hash - хеш полей запроса. В описании каждого запроса указано, какие поля подлежат хешированию. Значения этих полей записываются в одну строчку через точку с запятой, затем от полученной UTF8-строки считается SHA1-хеш, который кодируется base64. Если опциональный параметр не передается в запросе, но участвует в формировании хеша, то в хеш нужно вставлять вместо него пустую строку. PHP код формирования хеша: $hash = base64_encode(sha1($str, true)), где $str - строка параметров.

Если подпись запроса (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	Возврат средств не осуществлен