Общие сведения
Если вы искали устаревшую версию API, то она доступна по ссылке HTTP-протокол.
Взаимодействие осуществляется по протоколу HTTPS с использованием методов GET/POST/PUT. API использует REST-архитектуру:
- POST и PUT -запросы используют JSON-аргументы;
- GET-запросы работают со строками запросов;
- API всегда возвращает ответ в формате JSON, независимо от типа запроса;
Заголовки запроса:
curl --request POST 'https://paymaster.ru/api/v2/invoices' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
- В заголовках всех запросов и ответов передается
Content-type: application/json; - В заголовках всех запросов передается:
Authorization: Bearer {token}; - В заголовках POST-запросов может передаваться
Idempotency-Key: {key_string}- ключ идемпотентности запроса;
В случае возникновения ошибки, ответ содержит код и причину (code, message), также ответ может содержать секции с дополнительными подробностями.
Пример ответа с ошибкой:
{
"code": "validation_error",
"message": "One or many validation errors. See 'errors' list.",
"errors": [
"Specify required MerchantId value."
]
}
В запросах обязательные параметры выделены жирным шрифтом.
Аутентификация запросов
Запросы необходимо передавать по защищенному протоколу (https). Базовый адрес сервиса: https://paymaster.ru
Поддерживаются следующие способы аутентификации запросов:
- Bearer: Токен для сайта можно сгенерировать в Личном кабинете мерчанта. Требуется добавлять в заголовок
Authorizationкаждого запроса.
Типы данных
В запросах используются следующие типы данных:
- Строки (
string) - Числа с дробной частью (
numeric) - Даты (
date). Для передачи в запросах используется форматISO 8601
Для кодирования валют используется трехбуквенный код по ISO 4217
Работа со списками
Выгрузка списков (платежи, возвраты и пр.) происходит постранично: если в ответе присутствует указатель на следующую страницу (cursor), то необходимо запросить следующую порцию данных. Для этого нужно повторить запрос с добавлением значения cursor к списку параметров.
Платежи
Ссылка на оплату
POST /api/v2/invoices
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/invoices' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "cf128151-127b-44ed-bde5-26c531cad20d",
"invoice": {
"description": "test payment",
"params": {
"BT_USR": "34"
}
},
"amount": {
"value": 10.50,
"currency": "RUB"
},
"paymentMethod": "BankCard"
}'
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| dualMode | bool | Флаг DMS платежа (по-умолчанию false) |
| testMode | bool | Флаг тестового платежа (по-умолчанию false) |
| tokenization | Параметры токенизации | |
| type | string | Тип платежного токена (cof / recurring) |
| purpose | string | Описание подписки |
| callbackUrl | string | url для нотификаций по статусу токена |
| invoice | Детали счета | |
| description | string | Назначение платежа |
| orderNo | string | Номер заказа в системе магазина |
| expires | date | Срок действия счета |
| params | Дополнительные параметры | |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| paymentMethod | string | Способ оплаты |
| protocol | Параметры протокола | |
| returnUrl | string | Страница, на которую нужно направить пользователя после оплаты |
| callbackUrl | string | url для нотификации об оплате |
| customer | Данные пользователя | |
| string | e-mail пользователя | |
| phone | string | Телефон пользователя (в международном формате без знака +) |
| ip | string | IP-адрес пользователя |
| account | string | Аккаунт пользователя в магазине |
| receipt | Данные чека | |
| client | Данные покупателя | |
| items | Перечисление позиций чека |
Пример ответа:
{
"paymentId": "12769",
"url": "https://paymaster.ru/cpay/a62beecb68c84778b2424294f635b370"
}
Ответ:
| Параметр | Тип | Описание |
| paymentId | string | Идентификатор платежа |
| url | string | Адрес страницы оплаты, на которую нужно направить пользователя |
Создание платежа
POST /api/v2/payments
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/payments' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "cf128151-127b-44ed-bde5-26c531cad20d",
"invoice": {
"description": "test payment",
"params": {
"BT_USR": "34"
}
},
"amount": {
"value": 10.50,
"currency": "RUB"
},
"paymentData": {
"paymentMethod": "BankCard",
"card": {
"pan": "4**********0540",
"expiry": "10/22",
"cvc": "***"
}
}
}'
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| dualMode | bool | Флаг DMS платежа (по-умолчанию false) |
| testMode | bool | Флаг тестового платежа (по-умолчанию false) |
| tokenization | Параметры токенизации | |
| type | string | Тип платежного токена (cof / recurring) |
| purpose | string | Описание подписки |
| callbackUrl | string | url для нотификаций по статусу токена |
| invoice | Детали счета | |
| description | string | Назначение платежа |
| orderNo | string | Номер заказа в системе магазина |
| expires | date | Срок действия счета |
| params | Дополнительные параметры | |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| paymentData | Платежные данные | |
| paymentMethod | string | Способ оплаты |
| card | Данные карты | |
| pan | string | Номер карты |
| expiry | string | Срок действия |
| cvc | string | CVV/CVC2 |
| dsrp | ||
| type | string | Тип (ApplePay / GooglePay) |
| cryptogram | string | Cryptogram |
| eci | string | ECI |
| authorizationCode | string | Код авторизации платежа |
| account | string | Логин/аккаунт |
| phone | string | Номер телефона |
| token | Платежный токен | |
| id | string | Идентификатор токена |
| stickerId | string | Идентификатор стикера (кассовой ссылки) |
| protocol | Параметры протокола | |
| returnUrl | string | Страница, на которую нужно направить пользователя после оплаты |
| callbackUrl | string | url для нотификации об оплате |
| threeDSCompleteUrl | string | threeDSCompleteUrl при работе по сценарию 3DSecure Challenge Flow |
| customer | Данные пользователя | |
| string | e-mail пользователя | |
| phone | string | Телефон пользователя |
| ip | string | IP-адрес пользователя |
| account | string | Аккаунт пользователя в магазине |
| device | Сведения об устройстве пользователя | |
| language | string | Язык |
| acceptHeader | string | Значение заголовка Accept |
| userAgent | string | Значение заголовка UserAgent |
| colorDepth | string | Глубина цветовой палитры в битах |
| screenHeight | string | Высота экрана в пикселах |
| screenWidth | string | Ширина экрана в пикселах |
| utcOffsetMinutes | string | Смещение от UTC в минутах |
| receipt | Данные чека | |
| client | Данные покупателя | |
| items | Перечисление позиций чека |
Параметры, необходимые для проведения платежа, зависят от выбранного способа оплаты.
Пример ответа:
{
"id": "12769",
"created":"2021-09-01T08:20:00Z",
"testMode": false,
"status": "Confirmation",
"resultCode": "Success",
"merchantId": "96e809e9-8bce-40fd-86cb-d34db39b4668",
"amount": {
"value": 10.5000,
"currency": "RUB"
},
"invoice": {
"description": "test payment",
"params": {
"BT_USR": "34"
}
},
"paymentData": {
"paymentMethod": "BankCard"
},
"confirmation": {
"type": "ThreeDSv1",
"acsUrl": "https://paymaster.ru/acs/pareq",
"PAReq": "eJxVUtuO0...v4BOrji7g=="
}
}
Ответ
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
| created | date | Дата платежа |
| testMode | bool | Флаг тестового платежа |
| status | string | Статус платежа |
| resultCode | string | Код результата |
| message | string | Описание результата авторизации |
| merchantId | string | Идентификатор магазина |
| invoice | Детали счета | |
| description | string | Назначение платежа |
| orderNo | string | Номер заказа в системе магазина |
| expires | date | Срок действия счета |
| params | Дополнительные параметры | |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| customer | Данные пользователя | |
| ip | string | IP-адрес пользователя |
| paymentData | Платежные данные | |
| paymentMethod | string | Способ оплаты |
| paymentInstrumentTitle | string | Идентификатор плательщика (номер карты, телефон и пр.) |
| agreement | string | Признак договора |
| cardInfo | Данные по BIN-у карты | |
| brand | string | Название платежной системы |
| issuer | string | Название банка |
| country | string | ISO-код страны |
| type | string | Тип карты (кредитная, дебетовая) |
| category | string | Категория карты (gold, classic) |
| confirmation | Способ подтверждения платежа | |
| type | string | Тип подтверждения |
| *** | Параметры подтверждения | |
| paymentToken | Данные платежного токена | |
| id | string | Идентификатор токена |
| expires | date | Срок жизни токена |
| title | string | Отображаемое название |
В процессе проведения платежа может потребоваться дополнительное подтверждение (или несколько подтверждений).
Подтверждение платежа во внешней системе
| Параметр | Тип | Описание |
| type | string | Тип подтверждения External |
| paymentUrl | string | Адрес страницы подтвердения, на который нужно направить пользователя |
| universalLink | bool | Признак платежной ссылки |
| instruction | string | Инструкция по совершению оплаты |
Подтверждение платежа одноразовым кодом
| Параметр | Тип | Описание |
| type | string | Тип подтверждения SmsOtp |
| maskedPhone | string | Номер телефона, на который был выслан код подтверждения |
Сценарий 3DS Method
| Параметр | Тип | Описание |
| type | string | Тип подтверждения ThreeDSMethod |
| methodUrl | string | Адрес ACS страницы для прохождения сценария |
| transactionId | string | Идентификатор транзакции аутентификации |
Сценарий 3DS Challenge Flow
| Параметр | Тип | Описание |
| type | string | Тип подтверждения ThreeDSChallenge |
| acsUrl | string | Адрес ACS страницы для прохождения сценария |
| creq | string | Challenge request |
Сценарий 3DS v1
| Параметр | Тип | Описание |
| type | string | Тип подтверждения ThreeDSv1 |
| acsUrl | string | Адрес ACS страницы для прохождения сценария |
| PAReq | string | Payer Authentication request |
Подтверждение платежа
PUT /api/v2/payments/{id}/complete
Пример запроса:
curl --request PUT 'https://paymaster.ru/api/v2/payments/12769/complete' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Content-Type: application/json' \
--data-raw '{
"PARes": "eJx7v3u...IxsAwA="
}'
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
| code | string | Код подтвеждения |
| threeDSCompInd | string | 3DS Method complete indicator |
| cres | string | Challenge response |
| PARes | string | Payer Authentication response |
В ответ сервис возвращает детали платежа.
Завершение платежа (capture)
PUT /api/v2/payments/{id}/confirm
Пример запроса:
curl --request PUT 'https://paymaster.ru/api/v2/payments/12769/confirm' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": {
"value": 10.50,
"currency": "RUB"
}
}'
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
| amount | Сумма списания | |
| value | decimal | Сумма списания |
| currency | string | Код валюты |
| receipt | Данные чека | |
| client | Данные покупателя | |
| items | Перечисление позиций чека |
При успешном выполнении запроса сервис возвращает пустой ответ с HTTP-статусом 200.
Отмена платежа
PUT /api/v2/payments/{id}/cancel
Пример запроса:
curl --request PUT 'https://paymaster.ru/api/v2/payments/12769/cancel' \
--header 'Authorization: Bearer QdvdwiXKFm='
При успешном выполнении запроса сервис возвращает пустой ответ с HTTP-статусом 200.
Получение данных по платежу
GET /api/v2/payments/{id}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/payments/12769' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
В ответ сервис возвращает данные платежа.
Список платежей
GET /api/v2/payments?merchantId={merchantId}&start={start}&end={end}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/payments?merchantId=cf128151-127b-44ed-bde5-26c531cad20d&start=2021-08-01T06:00:00Z&end=2021-08-01T06:30:00Z' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| start | date | Начало периода |
| end | date | Конец периода |
Пример ответа:
{
"items": [
{
"id": "9755",
"status": "Settled",
"created":"2021-08-01T06:15:00Z",
"merchantId": "96e809e9-8bce-40fd-86cb-d34db39b4668",
"amount": {
"value": 10.0000,
"currency": "RUB"
},
"invoice": {
"description": "test"
},
"paymentData": {
"paymentMethod": "BankCard",
"paymentInstrumentTitle": "410000XXXXXXX0000"
}
}
]
}
Ответ:
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
| created | date | Дата платежа |
| status | string | Статус платежа |
| merchantId | string | Идентификатор магазина |
| invoice | Детали счета | |
| description | string | Назначение платежа |
| orderNo | string | Номер заказа в системе магазина |
| expires | date | Срок действия счета |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| paymentData | Платежные данные | |
| paymentMethod | string | Способ оплаты |
| paymentInstrumentTitle | string | Идентификатор плательщика |
Возвраты
Создание возврата
POST /api/v2/refunds
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/refunds' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentId": "12870",
"amount": {
"value": 5.5,
"currency": "RUB"
}
}'
Запрос:
| Параметр | Тип | Описание |
| paymentId | string | Идентификатор платежа |
| amount | Сумма возврата | |
| value | decimal | Сумма возврата |
| currency | string | Код валюты |
| receipt | Данные чека | |
| client | Данные покупателя | |
| items | Перечисление позиций чека |
Пример ответа:
{
"id": "1276",
"created": "2021-10-01T06:23:02.273Z",
"status": "Pending",
"paymentId": "12870",
"amount": {
"value": 5.5,
"currency": "RUB"
}
}
Ответ
| Параметр | Тип | Описание |
| id | string | Идентификатор возврата |
| created | date | Дата возврата |
| paymentId | string | Идентификатор платежа |
| amount | Сумма возврата | |
| value | decimal | Сумма возврата |
| currency | string | Код валюты |
| status | string | Статус возврата |
| resultCode | string | Код результата |
Получение данных по возврату
GET /api/v2/refunds/{id}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/refunds/1276' \
--header 'Authorization: Bearer QdvdwiXKFm='
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор возврата |
В ответ сервис возвращает данные возврата
Список возвратов
GET /api/v2/refunds?merchantId={merchantId}&start={start}&end={end}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/refunds?merchantId=cf128151-127b-44ed-bde5-26c531cad20d&start=2021-08-01T06:00:00Z&end=2021-08-01T06:30:00Z' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| start | date | Начало периода |
| end | date | Конец периода |
Пример ответа:
{
"items": [
{
"id": "1276",
"created": "2021-10-01T06:23:02.273Z",
"status": "Pending",
"paymentId": "12870",
"amount": {
"value": 5.5,
"currency": "RUB"
}
}
]
}
Ответ:
| Параметр | Тип | Описание |
| id | string | Идентификатор возврата |
| created | date | Дата возврата |
| paymentId | string | Идентификатор платежа |
| amount | Сумма возврата | |
| value | decimal | Сумма возврата |
| currency | string | Код валюты |
| status | string | Статус возврата |
Платежные токены
Ссылка на привязку
POST /api/v2/tokenization
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/tokenization' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "cf128151-127b-44ed-bde5-26c531cad20d",
"type": "recurring",
"purpose": "Тестовая подписка"
"paymentMethod": "bankcard",
"customer": {
"account": "47733000003"
}
}'
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| testMode | bool | Флаг тестового режима (по-умолчанию false) |
| type | string | Тип платежного токена (recurring) |
| purpose | string | Описание подписки |
| paymentMethod | string | Способ оплаты |
| callbackUrl | string | url для нотификаций по статусу токена |
| returnUrl | string | url для возврата пользователя |
| customer | Данные пользователя | |
| account | string | Аккаунт пользователя в магазине |
| string | e-mail пользователя |
Пример ответа:
{
"tokenId": "8cd9991b47ab42018f0bb56ca0fbdba0",
"url": "https://paymaster.ru/cpay/tokenization/f3da06b158924a6c8da280a8b49c2996"
}
Ответ:
| Параметр | Тип | Описание |
| tokenId | string | Идентификатор токена |
| url | string | Адрес страницы, на которую нужно направить пользователя |
Создание токена
POST /api/v2/paymenttokens
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/paymenttokens' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "cf128151-127b-44ed-bde5-26c531cad20d",
"type": "recurring",
"purpose": "Тестовая подписка"
"paymentData": {
"paymentMethod": "sbp"
},
"customer": {
"account": "47733000003"
}
}'
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| testMode | bool | Флаг тестового режима (по-умолчанию false) |
| type | string | Тип платежного токена (recurring) |
| purpose | string | Описание подписки |
| paymentData | Платежные данные | |
| paymentMethod | string | Способ оплаты |
| protocol | Параметры протокола | |
| returnUrl | string | Страница, на которую нужно направить пользователя после завершения сценария |
| callbackUrl | string | url для нотификации по статусу токена |
| threeDSCompleteUrl | string | threeDSCompleteUrl при работе по сценарию 3DSecure Challenge Flow |
| customer | Данные пользователя | |
| account | string | Аккаунт пользователя в магазине |
| string | e-mail пользователя |
Параметры, необходимые для создания токена, зависят от выбранного способа оплаты.
Пример ответа:
{
"id": "8cd9991b47ab42018f0bb56ca0fbdba0",
"status": "Created",
"confirmation": {
"type": "External",
"universalLink": true,
"paymentUrl": "https://paymaster.ru/cpay/mock/sbp/subscription/8cd9991b47ab42018f0bb56ca0fbdba0",
"instruction": "Для привязки счета:\r\n* Откройте приложение Вашего банка\r\n* Выберите Сканировать QR\r\n* Подтвердите привязку"
}
}
Ответ
| Параметр | Тип | Описание |
| id | string | Идентификатор токена |
| status | string | Статус токена (Active / Revoked) |
| title | string | Наименование токена |
| expires | date | Срок действия токена |
| cardInfo | Данные по BIN-у карты | |
| brand | string | Название платежной системы |
| issuer | string | Название банка |
| country | string | ISO-код страны |
| type | string | Тип карты (кредитная, дебетовая) |
| category | string | Категория карты (gold, classic) |
| confirmation | Способ подтверждения | |
| type | string | Тип подтверждения |
| *** | Параметры подтверждения |
В процессе создания токена может потребоваться дополнительное подтверждение (или несколько подтверждений).
Подтверждение привязки во внешней системе
| Параметр | Тип | Описание |
| type | string | Тип подтверждения External |
| paymentUrl | string | Адрес страницы подтверждения, на который нужно направить пользователя |
| universalLink | bool | Признак платежной ссылки |
| instruction | string | Инструкция для пользователя |
Получение данных по токену
GET /api/v2/paymenttokens/{id}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/paymenttokens/8cd9991b47ab42018f0bb56ca0fbdba0' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор токена |
В ответ сервис возвращает данные токена.
Отзыв токена
PUT /api/v2/paymenttokens/{id}/revoke
Пример запроса:
curl --request PUT 'https://paymaster.ru/api/v2/paymenttokens/8cd9991b47ab42018f0bb56ca0fbdba0/revoke' \
--header 'Authorization: Bearer QdvdwiXKFm='
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор токена |
Статус HTTP 200 означает успешное выполнение запроса.
Чеки
Создание чека
POST /api/v2/receipts
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/receipts' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentId": "13167",
"amount": {
"value": 10,
"currency": "RUB"
},
"type": "Payment",
"client": {
"email": "customer@gmail.com"
},
"items": [{
"name": "Яблоки",
"quantity": 1,
"price": 10,
"vatType": "Vat120",
"paymentSubject": "Commodity",
"paymentMethod": "FullPrepayment"
}
]
}'
Запрос
| Параметр | Тип | Описание |
| paymentId | string | Идентификатор платежа |
| amount | Сумма по чеку | |
| value | decimal | Сумма |
| currency | string | Код валюты |
| type | string | Тип чека |
| client | Данные покупателя | |
| string | e-mail покупателя | |
| phone | string | Телефон покупателя |
| name | string | Наименование компании |
| inn | string | ИНН компании |
| items | Перечисление позиций чека | |
| name | string | Наименования |
| quantity | decimal | Количество |
| price | decimal | Цена |
| measure | string | Единица измерения товара |
| excise | decimal | Акциз |
| product | ||
| country | string | Код страны происхождения |
| declaration | string | Номер таможенной декларации |
| vatType | string | Ставка НДС |
| paymentSubject | string | Предмет расчета |
| paymentMethod | string | Способ расчета |
| marking | Данные маркировки | |
| code | string | Код товара |
| quantity | Дробное количество маркированного товара | |
| numerator | int | Числитель |
| denominator | int | Знаменатель |
| agentType | string | Признак агента |
| supplier | Данные поставщика | |
| name | string | Наименование поставщика |
| inn | string | ИНН поставщика |
| phone | string | Телефон поставщика |
Пример ответа:
{
"id": "1860",
"created": "2021-11-02T09:54:35.45Z",
"paymentId": "13167",
"amount": {
"value": 10.0,
"currency": "RUB"
},
"type": "Payment",
"status": "Pending"
}
Ответ
| Параметр | Тип | Описание |
| id | string | Идентификатор чека |
| created | date | Дата создания |
| paymentId | string | Идентификатор платежа |
| amount | Сумма чека | |
| value | decimal | Сумма |
| currency | string | Код валюты |
| type | string | Тип чека |
| status | string | Статус регистрации чека |
Получение данных по чеку
GET /api/v2/receipts/{id}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/receipts/1860' \
--header 'Authorization: Bearer QdvdwiXKFm='
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор чека |
В ответ сервис возвращает данные чека
Список чеков
GET /api/v2/receipts?paymentId={paymentId}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/receipts?paymentId=22504' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| paymentId | string | Идентификатор платежа |
В ответ сервис возвращает список с данными чеков
Стикеры
Регистрация стикера
POST /api/v2/stickers
Пример запроса:
curl --request POST 'https://paymaster.ru/api/v2/stickers' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Idempotency-Key: 86cf125c' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "cf128151-127b-44ed-bde5-26c531cad20d",
"stickerType": "Sbp",
"productCode": "product-1234",
"paymentPurpose": "Оплата товара",
"description": "Продукт #1234",
"amount": {
"value": 39.90,
"currency": "RUB"
}
}'
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
| stickerType | string | Тип стикера (например, Sbp) |
| cashlink | bool | Признак кассовой ссылки |
| description | string | Описание стикера |
| productCode | string | Код продукта |
| paymentPurpose | string | Назначение платежа |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| callbackUrl | string | url для нотификации об оплате |
Пример ответа:
{
"id": "24cc565dea08",
"stickerType": "Sbp",
"productCode": "product-1234",
"paymentPurpose": "Оплата товара",
"description": "Продукт #1234",
"amount": {
"value": 39.90,
"currency": "RUB"
},
"status": "Active",
"payload": "https://qr.nspk.ru/AS****G0?type=01&sum=3990&cur=RUB&crc=ZZZZ"
}
Ответ
| Параметр | Тип | Описание |
| id | string | Идентификатор стикера |
| stickerType | string | Тип стикера |
| cashlink | bool | Признак кассовой ссылки |
| productCode | string | Код продукта |
| paymentPurpose | string | Назначение платежа |
| description | string | Описание стикера |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| status | string | Статус стикера |
| payload | string | Контент (платежная ссылка) |
Активация / деактивация стикера
PUT /api/v2/stickers/{id}
Пример запроса:
curl --request PUT 'https://paymaster.ru/api/v2/stickers/24cc565dea08' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
--header 'Content-Type: application/json' \
--data-raw '{
"active": true
}'
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор стикера |
| active | bool | Статус стикера |
Статус HTTP 200 означает успешное выполнение запроса.
Получение данных по стикеру
GET /api/v2/stickers/{id}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/stickers/24cc565dea08' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор стикера |
В ответ сервис возвращает данные стикера
Список стикеров
GET /api/v2/stickers?merchantId={merchantId}
Пример запроса:
curl --request GET 'https://paymaster.ru/api/v2/stickers?merchantId=cf128151-127b-44ed-bde5-26c531cad20d' \
--header 'Authorization: Bearer QdvdwiXKFm=' \
Запрос:
| Параметр | Тип | Описание |
| merchantId | string | Идентификатор магазина |
Пример ответа:
{
"items": [
{
"id": "24cc565dea08",
"stickerType": "Sbp",
"productCode": "product-1234",
"paymentPurpose": "Оплата товара",
"description": "Продукт #1234",
"amount": {
"value": 39.90,
"currency": "RUB"
},
"status": "Active",
"payload": "https://qr.nspk.ru/AS****G0?type=01&sum=3990&cur=RUB&crc=ZZZZ"
}
]
}
Ответ:
| Параметр | Тип | Описание |
| items | array | Список стикеров |
Нотификации
Статус платежа
POST {callbackUrl}
Пример запроса:
curl --request POST 'https://merchant-site.com/payments/result' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "12769",
"created":"2021-09-01T08:20:00Z",
"testMode": false,
"status": "Settled",
"merchantId": "96e809e9-8bce-40fd-86cb-d34db39b4668",
"amount": {
"value": 10.5000,
"currency": "RUB"
},
"invoice": {
"description": "test payment",
"params": {
"BT_USR": "34"
}
},
"paymentData": {
"paymentMethod": "BankCard",
"paymentInstrumentTitle": "410000XXXXXXX0000"
}
}'
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор платежа |
| created | date | Дата платежа |
| testMode | bool | Флаг тестового платежа |
| status | string | Статус платежа |
| merchantId | string | Идентификатор магазина |
| invoice | Детали счета | |
| description | string | Назначение платежа |
| orderNo | string | Номер заказа в системе магазина |
| expires | date | Срок действия счета |
| params | Дополнительные параметры | |
| amount | Стоимость | |
| value | decimal | Сумма к оплате |
| currency | string | Код валюты |
| paymentData | Платежные данные | |
| paymentMethod | string | Способ оплаты |
| paymentInstrumentTitle | string | Идентификатор плательщика (номер карты, телефон и пр.) |
Статус платежного токена
POST {callbackUrl}
Пример запроса:
curl --request POST 'https://merchant-site.com/tokens/result' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": "8cd9991b47ab42018f0bb56ca0fbdba0",
"status": "Active",
"title": "410000XXXXXX0001",
"expires": "2022-10-31T23:59:59Z"
}'
Запрос:
| Параметр | Тип | Описание |
| id | string | Идентификатор токена |
| status | string | Статус токена (Active / Revoked) |
| title | string | Наименование токена |
| expires | date | Срок действия токена |
Способы оплаты
| Код | Название |
| bankcard | Банковская карта |
| sbp | Система быстрых платежей (СБП) |
| qiwi | QIWI |
Коды и справочники
Код ошибки
| Код | Описание |
| validation_error | Некорректный запрос (неверный формат) |
| not_authorized | Недостаточно прав для выполнения операции |
| idempotency_key_violation | Нарушение уникальности ключа (дублирование запроса) |
| invalid_operation | Запрос отклонен |
| payment_token_revoked | Платежный токен отозван |
| payment_token_blocked | Платежный токен временно заблокирован |
Статус платежа
| Код | Описание |
| Authorized | Платеж авторизован |
| Settled | Платеж проведен |
| Cancelled | Платеж отменен |
| Rejected | Платеж отклонен |
| Confirmation | Требуется дополнительное подтверждение |
| Pending | Платеж выполняется |
Статус возврата
| Код | Описание |
| Success | Возврат проведен успешно |
| Rejected | Запрос на возврат отклонен |
| Pending | Возврат выполняется |
Код авторизации
| Код | Описание |
| TransactionDeclined | Авторизация отклонена |
| IssuerUnavailable | Эмитент недоступен |
| RejectedByFraud | Отклонено фрод-мониторингом |
| InvalidAmount | Недопустимая сумма |
| InvalidAccount | Неверный номер карты / карта не существует |
| BlockedAccount | Карта заблокирована (утеряна) |
| OperationNotAllowed | Операция недоступна |
| InsufficientFunds | Недостаточно средств |
| ExpiredAccount | Срок действия карты истек / неверный срок действия |
| PaymentLimitExceeded | Превышен лимит на сумму |
| PaymentCountExceeded | Превышено кол-во попыток |
| CardNotEnrolled | Карта не подписана на 3DS |
| ThreeDSecureFailed | 3DS аутентификация не пройдена |
| CancelledByUser | Платеж отклонен пользователем |
| PaymentExpired | Истек срок |
Статус регистрации чека
| Код | Описание |
| Success | Чек зарегистрирован успешно |
| Rejected | Отказ регистрации чека |
| Cancelled | Регистрация чека отменена |
| Pending | Выполняется регистрация |
Тип чека
| Код | Описание |
| Payment | Приход |
| Refund | Возврат прихода |
Ставка НДС
| Код | Описание |
| None | Без НДС |
| Vat0 | НДС 0% |
| Vat10 | НДС 10% |
| Vat20 | НДС 20% |
| Vat110 | НДС по формуле 10/110 |
| Vat120 | НДС по формуле 20/120 |
Признак агента
| Код | Описание |
| BankPaymentAgent | Банковский платежный агент |
| BankPaymentSubagent | Банковский платежный субагент |
| PaymentAgent | Платежный агент |
| PaymentSubagent | Платежный субагент |
| Attorney | Поверенный |
| Commissioner | Комиссионер |
| Agent | Агент |
Признак предмета расчета
| Код | Описание |
| Commodity | Товар |
| Excise | Акциз |
| Job | Работа |
| Service | Услуга |
| Gambling | Ставка в азартной игре |
| Lottery | Лотерейный билет |
| IntellectualActivity | Интеллектуальная деятельность |
| Payment | Платеж |
| AgentFee | Вознаграждение агента |
| PropertyRights | Имущественные права |
| NonOperatingIncome | Внереализационный доход |
| InsurancePayment | Страховой сбор |
| SalesTax | Торговый сбор |
| ResortFee | Курортный сбор |
| Other | Другое |
Признак способа расчета
| Код | Описание |
| FullPrepayment | Полная предоплата |
| PartialPrepayment | Частичная предоплата |
| Advance | Аванс |
| FullPayment | Полный расчет |
| PartialPayment | Частичный расчет |
| Credit | Кредит |
Единица измерения
| Код | Описание |
| Piece | Штука |
| Gram | Грамм |
| Kilogram | Килограмм |
| Tonne | Тонна |
| Centimeter | Сантиметр |
| Decimeter | Дециметр |
| Meter | Метр |
| SquareCentimeter | Квадратный сантиметр |
| SquareDecimeter | Квадратный дециметр |
| SquareMeter | Квадратный метр |
| Millilitre | Миллилитр |
| Litre | Литр |
| QubicMeter | Кубический метр |
| KilowattHour | Киловатт * час |
| Gigacal | Гигакалория |
| Day | День |
| Hour | Час |
| Minute | Минута |
| Second | Секунда |
| Kilobyte | Килобайт |
| Megabyte | Мегабайт |
| Gigabyte | Гигабайт |
| Terabyte | Терабайт |
| Other | Другое |