Барс предоставляет API для взаимодействия со Службой платежей.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов POST, PATCH, GET, DELETE.
В описании каждого запроса указаны требуемые метод и параметры.
POST и PATCH -запросы используют JSON-структуру, DELETE - и GET-запросы работают со строками запросов.
Ответ любого метода возвращает HTTP-код. Если при обработке запроса происходит ошибка, API дополнительно возвращает ее описание.
¶ API Службs платежей условно можно разделить на следующие блоки:
- Acquirings (Эквайринг или процессинг) - блок для настройки подключения к эквайрингам.
- Paylinks (Платежные ссылки ) - реализация работы с СБП через "кассовую платежную ссылку" (QRVariable).
- Payments (Платежи) - работа с платежами.
Актуальная API Swagger http://localhost:порт/index.html. Работа с API только при запущенной Службе платежей.
¶ Acquirings
¶ /api/Acquirings
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST | No parameters |
{ "type": integer, "name": "string", "options": "string" } |
Создать процессинг | метод предназначен для создания нового эквайринга. |
| GET | id | No body | Считать процессинги | метод позволяет считать все процессинги зарегистрированные в системе. |
| GET | id | No body | Получить процессинг | метод позволяет получить процессинг по идентификатору |
| PATCH | id |
{ "type": integer, "name": "string", "options": "string" } |
Обновить процессинг | метод позволяет редактировать существующий процессинг |
| POST | id |
{ "callbackUrl": "string" } |
Установка callback-адреса | метод позволяет настроить callback-адрес на который будут приходить уведомления об изменении статусов платежей |
Значение параметров запроса
| Параметр | Значение | Тип |
| id | идентификатор эквайринга | integer |
| type | тип эквайринга | integer |
| name | наименование эквайринга | string |
| options | параметры настроек эквайринга | string |
| callbackUrl | callback-адрес, на который будут приходить уведомления об изменении статусов платежей | string |
Значение параметров ответа
| Параметр | Значение | Тип |
| id | идентификатор эквайринга | integer |
| type | тип эквайринга | integer |
| name | наименование эквайринга | string |
| options | параметры настроек эквайринга | string |
| guid | глобальный, уникальных идентификатор эквайринга | string |
| state | статус/состояние эквайринга | string |
| success | результат выполнения запроса true или false | boolean |
| message | информационное сообщение | string |
| data | в поле передаётся callback-адрес | string |
¶ Paylinks
¶ api/Paylinks
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST | - |
{ "qr": string", "url": string", "name": string", "owner": string", "type": "string", "acquiringId":integer, "blocked": false } |
Регистрация существующей платёжной ссылки / генерация новой |
метод позволяет:
|
| GET |
id byType byAcquiring Ownerby HasOwner |
- | Получить список платежных ссылок | метод позволяет получить список платежных ссылок. При отсутствии параметров запроса возвращает все добавленные платежные ссылки. |
| GET | id | - | Получить платежную ссылку по ID | метод позволяет получить платежную ссылку по ее идентификатору |
| DELETE | id | - | Удалить платёжную ссылку | метод позволяет удалить платежную ссылку по ее идентификатору |
| PATCH | id |
{ "value": "string", "path": "string", "op": "string", "from": "string" } |
Изменить платежную ссылку | метод позволяет отредактировать существующую платежную ссылку |
Значение параметров запроса
| Параметр | Значение | Тип |
| qr | значение QR - присваивается банком при создании новой ссылки | string |
| url | Url-адрес регистрации QR кода | string |
| name | наименование платежной ссылки | string |
|
owner byOwner |
владелиц (резерв) ссылки | string |
|
type byType |
тип QR |
|
|
id acquiringId byAcquiring |
идентификатор эквайринга | integer |
| blocked | блокировка ссылки | boolean |
| byHasOwner | ссылка зарезервирована или нет | boolean |
Значение параметров ответа
| Параметр | Значение | Тип |
| id | идентификатор платежной ссылки | integer |
| qr | значение QR - присваивается банком при создании новой ссылки | string |
| url | Url-адрес регистрации QR кода | string |
| name | наименование платежной ссылки | string |
| owner | владелиц (резерв) ссылки | string |
| type | тип QR |
|
| acquiringId | идентификатор эквайринга | integer |
| blocked | блокировка ссылки | boolean |
¶ Payments
¶ api/Payments
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| GET |
acquiringId status dateFrom dateTo |
- | Список платежей | метод позволяет получить список совершенных платежей. |
| POST | - |
{ "acquiringId": 0, "sum": 0, "check": "string", "externalId": "string", "qrVariable": "string" } |
Создать платеж | метод позволяет создать новый платеж |
| GET | id | - | Получить платеж | метод позволяет получить данные платежа по идентификатору |
| PATCH | id | - | Изменить платеж | метод позволяет изменить данные платежа по его идентификатору |
Значение параметров запроса
| Параметр | Значение | Тип |
|
id
|
идентификатор платежа (в поле может быть передан guid платежа) | string |
| acquiringId | идентификатор эквайринга | integer |
| status | статус платежа |
Created - создан Registered - зарегистрирован Waiting - ожидает Hold - заморожен Declined - отклонен Confirmed - подтвержден Canceled - отменен Refunded - полный возврат PartialRefunded - частичный возврат CheckStatusFlag - статус ожидания ответа |
| sum | сумма платежа | целые и дробные числа |
| check | чек платежа | string |
| qrVariable | тип QR | string |
| dateFrom | начало выборки | string(date-time) |
| dateTo | конец выборки | string(date-time) |
Значение параметров ответа
| Параметр | Значение | Тип |
| guid | уникальный идентификатор платежа | string |
| acquiringId | идентификатор эквайринга | integer |
| sum | сумма платежа | целые и дробные числа |
| sumRefund | сумма возврата | целые и дробные числа |
| currentStatus | статус платежа | string |
| currentStatusTimestamp | дата и время присвоения статуса | string(date-time) |
| check | чек платежа | string |
| externalId | идентификатор платежа в системе Барс | string |
| externalId2 | идентификатор платежа в банке | string |
¶ /api/Payments/{id}/StatusHistory
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| GET | id | - | Получить историю платежа | метод позволяет получить историю состояний платежа по его идентификатору |
Значение параметров ответа
| Параметр | Значение | Тип |
| paymentId | идентификатор статуса платежа | integer |
| reason | причина изменения статуса платежа | string |
| date | дата и время получения статуса платежа | string(date-time) |
| notificationId | идентификатор уведомления | string |
¶ /api/Payments/{id}/SetStatus
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST | id |
{ "status": "Created", "reason": "string" } |
Установить статус платежа | метод позволяет установить статус состояния платежа по его идентификатору |
Значение параметров ответа
| Параметр | Значение | Тип |
| guid | уникальный идентификатор платежа | string |
| acquiringId | идентификатор эквайринга | integer |
| sum | сумма платежа | целые и дробные числа |
| sumRefund | сумма возврата | целые и дробные числа |
| currentStatus | статус платежа | string |
| currentStatusTimestamp | дата и время присвоения статуса | string(date-time) |
| check | чек платежа | string |
| externalId | идентификатор платежа в системе Барс | string |
| externalId2 | идентификатор платежа в банке | string |
¶ /api/Payments/{id}/Register
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST |
id returnUrl useHold urlLifeTime |
{ "comment": "string" } |
Регистрация платежа | метод позволяет зарегистрировать платеж в банке |
Значение параметров запроса
| Параметр | Значение | Тип |
| returnUrl | адрес переадресации после успешной оплаты | string |
| useHold | установка холдирования платежа | boolean |
| urlLifeTime | Время жизни платежной ссылки (в сек.) |
integer по умолчанию значение 0 (время задано эквайрингом) formUrl |
Значение параметров ответа
| Параметр | Значение | Тип |
| formUrl | адрес для перехода на платежную страницу эквайринга | string |
¶ /api/Payments/{id}/Cancel
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST | id | Отмена платежа | метод позволяет отменить платеж |
¶ /api/Payments/{id}/Refund
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST |
id partialAmount |
{ "comment": "string", "receiptPositionIds": [ 0 ] } |
Возврат платежа | метод позволяет осуществлять частичные и полные возвраты платежа |
Значение параметров запроса
| Параметр | Значение | Тип |
| partialAmount | сумма возврата | целое или дробное число |
| comment | комментарий | string |
| receiptPositionIds | идентификатор позиции в чеке | integer |
¶ /api/Payments/{id}/Confirm
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| POST | id | - | Подтверждение платежа | метод позволяет осуществлять подтверждение холдированного платежа |
¶ /api/Payments/{id}/Check
| Метод | Параметры | Request body | Назначение метода | Описание метода |
| GET |
id force |
- | Результат платежа | метод позволяет получить результат платежа |
Значение параметров запроса
| Параметр | Значение | Тип |
| force | Принудительная проверка статуса платежа на стороне банка | boolean |
¶ Схема переходов между статусами платежа
.jpg)
.jpg)
¶ Порядок выполнения операций:
¶ Одностадийный платеж:
- Created - Создать платеж (api/Payments)
- Registered - зарегистрировать платеж в банке (/api/Payments/{id}/Register)
3.1Для отмены одностадийного платежа в статусе Registered /api/Payments/{id}/Cancel
3.2 Проверить статус платежа api/Payments{id}
3.3 Статус платежа Declined для Сбербанк, для Райффайзенбанк Canceled. Остальные эквайринги не поддерживают отмену зарегистрированного платежа.
4. Оплатить платеж перейдя по ссылке. Параметр в теле ответа formUrl
5. Проверить статус платежа api/Payments{id}
6. Статус платежа Confirmed
7.1 Для отмены одностадийного платежа в статусе Confirmed /api/Payments/{id}/Cancel
7.2 Проверить статус платежа api/Payments{id}
7.3 Статус платежа Canceled, Только Сбербанк и Альфабанк. Остальные эквайринги не поддерживают отмену подтвержденного платежа.
8. Сделать частичный возврат /api/Payments/{id}/Refund
9. Проверить статус платежа api/Payments{id}
10. Статус платежа PartialRefunded
11. Сделать частичный возврат /api/Payments/{id}/Refund
12. Проверить статус платежа api/Payments{id}
13. Статус платежа Refunded
¶ Двухстадийный платеж:
- Created - Создать платеж (api/Payments)
- Registered - зарегистрировать платеж в банке (/api/Payments/{id}/Register)/ В параметрах регистрации указать значение useHold == true
3.1Для отмены платежа в статусе Registered /api/Payments/{id}/Cancel
3.2 Проверить статус платежа api/Payments{id}
3.3 Статус платежа Declined для Сбербанк Остальные эквайринги с духстадийной оплатой не поддерживают отмену зарегистрированного платежа.
4. Оплатить платеж перейдя по ссылке. Параметр в теле ответа formUrl
5. Проверить статус платежа api/Payments{id}
6. Статус платежа Hold
7.1 Для отмены платежа в статусе Hold /api/Payments/{id}/Cancel
7.2 Проверить статус платежа api/Payments{id}
7.3 Статус платежа Canceled.
8. Подтвердить платеж /api/Payments/{id}/Confirm. ( на тестовом стенде Юнителлер подтверждение платежа не доступно)
9. Проверить статус платежа api/Payments{id}
10. Статус платежа Confirmed
11.1 Для отмены одностадийного платежа в статусе Confirmed /api/Payments/{id}/Cancel
11.2 Проверить статус платежа api/Payments{id}
11.3 Статус платежа Canceled, Только Сбербанк и Альфабанк. Остальные эквайринги не поддерживают отмену подтвержденного платежа.
12. Сделать частичный возврат /api/Payments/{id}/Refund
13. Проверить статус платежа api/Payments{id}
14. Статус платежа PartialRefunded
15. Сделать частичный возврат /api/Payments/{id}/Refund
16. Проверить статус платежа api/Payments{id}
17. Статус платежа Refunded