Аудитория: разработчики кассы, webstore, мобильных приложений и других систем, подключающихся к Bars.PaymentProcessing.Service для оплаты через NewCas (GoodooPay / BankQR)
В Барс Администратор Web → «Внешние платежи» должен быть настроен эквайринг NewCas (тип 15).
| Параметр | Назначение для интегратора |
|---|---|
acquiringId |
Передаётся в POST api/Payments |
UrlGenerate, UrlCheckStatus |
Использует служба платежей, не внешняя система |
ApiKey, LS, Bank |
Попадают в newCasClientInit при Register (для SDK) |
PaymentTimeoutSeconds (обычно 120) |
Когда платёж может стать «Истёк» после появления QR |
StatusPollIntervalSeconds (обычно 1) |
Как часто служба опрашивает NewCas |
| Фискализация после оплаты | Чек формирует ППС Барс |
Интегратору от администратора нужны: базовый URL службы платежей и acquiringId эквайринга NewCas.
| Требование | Описание |
|---|---|
| Базовый URL | https://<хост>/api/Payments/... |
| Версия API | Опционально заголовок X-Bars-PaymentProcessing-Version (см. GET /api/Version) |
| CORS | Если оплата из браузера — origin фронта/checkout должен быть разрешён в службе |
| Клиент | NSwag-клиент (Bars.PaymentProcessing.Service.Client, Client.tsx в веб-модуле) или свой HTTP по тем же DTO |
Формат ответа: обёртка ServiceResponse — поля success, message, data.
Внешняя система показывает виджет и вызывает REST службы:
1. POST /api/Payments → создать платёж
2. POST /api/Payments/{id}/Register → newCasClientInit
3. SDK startPayment(init) → QR / оплата у пользователя
4. PATCH /api/Payments/{id} → { "newCasQrTransactionId": "..." }
5. GET /api/Payments/{id} → polling до Confirmed / Canceled / Expired
Служба в фоне вызывает NewCas /checkstaus и выполняет фискализацию.
POST api/Paymentshttps://<хост-checkout>/pay/{guid}SPA goodoopay-checkout выполняет Register → SDK → PATCH → опрос статуса.
POST api/PaymentsPOST api/Payments/{id}/Register с телом { "newCasServerSideQr": true }newCasGenerateResponseJson (QR, диплинки; qrTransactionId уже в платеже)GET api/Payments/{id} или GET .../Check?force=true до Confirmed| Шаг | Метод | Назначение |
|---|---|---|
| 1 | POST api/Payments |
Создать платёж |
| 2 | POST api/Payments/{id}/Register |
Регистрация в эквайринге; для NewCas — newCasClientInit |
| 3 | PATCH api/Payments/{id} |
Привязка qrTransactionId после SDK (только это поле в запросе) |
| 4 | GET api/Payments/{id} |
Опрос currentStatus |
| 5 | POST api/Payments/{id}/Cancel |
Отмена (локально в службе) |
| опц. | GET api/Payments/{id}/Check?force=true |
Принудительная синхронизация с NewCas |
Повторный Register: POST Register с { "newCasServerSideQr": true }, если SDK не вернул transactionId, а во ExternalId ещё заглушка (Guid заказа).
{id} — числовой id или guid платежа.
POST /api/Payments
Content-Type: application/json
{
"acquiringId": 123,
"sum": 100.00,
"check": "{...}",
"externalId": "ваш-id-заказа"
}
POST /api/Payments/{id}/Register?returnUrl=...
Content-Type: application/json
{
"comment": "опционально",
"newCasServerSideQr": false
}
{
"newCasServerSideQr": true
}
PATCH /api/Payments/{id}
Content-Type: application/json
{
"newCasQrTransactionId": "<из callback SDK>"
}
{
"success": true,
"data": {
"payment": {
"guid": "...",
"currentStatus": "Registered",
"externalId": "..."
},
"newCasClientInit": {
"apiKey": "...",
"ls": "...",
"bank": "...",
"amount": 100,
"availableMethods": ["bank", "qr"],
"paymentTimeoutSeconds": 120,
"statusPollIntervalSeconds": 1
},
"newCasGenerateResponseJson": null
}
}
При серверном QR newCasGenerateResponseJson содержит JSON ответа /generate (urlContent, urlLink…, qrTransactionId).
| Требование | Детали |
|---|---|
| Пакет | @yastreb_220/goodoopay-react-sdk |
| Входные данные | Поля из newCasClientInit ответа Register |
| После оплаты | transactionId / qrTransactionId из callback → PATCH в службу |
| Успех для бизнес-логики | Только currentStatus = Confirmed от службы, не только callback SDK |
Демо и документация SDK: https://www.npmjs.com/package/@yastreb_220/goodoopay-react-sdk
currentStatus |
Действие интегратора |
|---|---|
Registered |
Ожидание оплаты; QR может быть ещё не привязан |
Confirmed |
Успех: закрыть заказ, показать чек |
Canceled |
Отмена (Cancel API или CANCELLED от NewCas) |
Expired |
Таймаут после появления qrTransactionId |
Declined |
Отказ |
Важно: до привязки qrTransactionId статус «Истёк» не выставляется, даже если прошло много времени с Register.
Таймаут ожидания оплаты (по умолчанию 120 с) отсчитывается с момента появления QR (bind, серверный /generate или Register с newCasServerSideQr), не с Register.
Рекомендуемый polling на стороне клиента: интервал ≈ statusPollIntervalSeconds, UI-таймаут ≈ paymentTimeoutSeconds из newCasClientInit.
| Операция | API | Примечание |
|---|---|---|
| Отмена до/во время ожидания | POST api/Payments/{id}/Cancel |
Без вызова BankQR; QR у банка может остаться активным |
| Возврат после оплаты | POST api/Payments/{id}/Refund |
Только внутри ППС Барс |
| Поле | До bind (SDK) | После bind / server QR |
|---|---|---|
ExternalId |
payment.Guid (32 hex, формат N) |
qrTransactionId |
ExternalId2 |
— | при необходимости — прежняя заглушка |
Пока ExternalId — заглушка Guid, служба не вызывает /checkstaus у NewCas.
| Не делать | Почему |
|---|---|
Вызывать GoodooPay /generate и /checkstaus со своего бэкенда |
Это делает служба платежей |
| Ждать отдельный webhook NewCas | Статус — через GET платежа или Check |
Использовать устаревший POST …/NewCas/BindTransaction |
Только PATCH с newCasQrTransactionId |
Считать оплату успешной по callback SDK без PATCH и Confirmed |
Обязательны bind и серверная верификация |
| Дата | Изменение |
|---|---|
| 2026-05-18 | Первоначальная версия для внешних интеграторов |