Payments

Базовый префикс: /api/v1/payments/

Платежи

`POST /bookings/{id}/initiate-payment`

Старт оплаты через платёжный провайдер.

{
  "amount": 5000.00,
  "currency": "KGS",
  "return_url": "https://your-site.com/payment-result"
}

Response:

{
  "payment_id": "uuid",
  "payment_url": "https://provider.com/checkout/...",
  "redirect_url": "https://provider.com/checkout/...",
  "expires_at": "2026-04-28T12:30:00Z"
}

Перенаправьте пользователя на payment_url. После оплаты провайдер свяжется с NurCore через webhook и переведёт броню в статус CONFIRMED.

`POST /payments/webhooks/external`

Универсальный webhook для случая, когда оплата прошла через ваш собственный PSP (Kaspi, Mbank, Freedom Pay, Elsom, банковский эквайринг и т.д.), и вы хотите сообщить NurCore, что бронирование оплачено.

После успешного вызова: создаётся Payment(status=COMPLETED), бронирование переходит в payment_status=PAID + status=CONFIRMED, пассажиру отправляется email с подтверждением. Идемпотентность — по (provider, transaction_id).

Body:

{
  "booking_id": "<UUID нашего бронирования>",
  "amount": 5000.00,
  "currency": "KGS",
  "provider": "kaspi",                  // kaspi/mbank/freedompay/elsom/bank/...
  "transaction_id": "ext-tx-12345",     // ваш уникальный ID — нужен для идемпотентности
  "payment_method": "card",             // card / bank_transfer / mobile_wallet
  "payer_name": "ИВАН ПЕТРОВ",         // optional
  "payer_email": "ivan@example.com",    // optional
  "metadata": { "...": "..." }          // optional — служебные поля
}

Аутентификация: consumer-app secret key (sk_live_…) со scope payments:confirm-external через заголовок X-API-Key. Получить scope можно через свой контакт в авиакомпании.

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Дополнительно сервис проверяет ownership: бронь должна быть создана этим же api-ключом (booking.api_client_id == X-Client-Id). Если бронь была создана через другой ключ — endpoint вернёт 403 «бронирование принадлежит другому API-клиенту».

Брони, оформленные до 2026-05-28 (миграция origin-tracking), не имеют поля api_client_id — для них подтверждение оплаты через этот endpoint недоступно; обратитесь к support через свой контакт в авиакомпании.

Response (200):

{ "status": "created", "payment_id": "uuid" }

status может быть:

created — новый платёж принят;
already_processed — этот transaction_id уже подтверждён ранее;
updated — был старый платёж в нетерминальном статусе, поднят до COMPLETED.

Возможные ошибки:

Код	Когда
400	`booking_id` не UUID
403	Невалидный api-key / нет scope `payments:confirm-external` / чужая бронь / legacy-бронь без origin-tracking
404	Бронь не найдена
503	Сервис временно недоступен — повторите запрос с экспоненциальной задержкой

См. guide Payment Integration → Использовать свой PSP для curl-примеров и пошаговой инструкции.

`GET /` / `GET /{id}`

Список / детали платежей. B2B видит свои платежи, mobile-приложения — платежи через свой ключ.

Refund

`POST /{id}/refund`

Создать возврат на конкретный платёж.

{
  "amount": 1500.00,
  "reason": "Booking cancelled by passenger"
}

Validation: amount ≤ paid_amount - already_refunded.

Платежи

`POST /bookings/{id}/initiate-payment`

`POST /payments/webhooks/external`

`GET /` / `GET /{id}`

Refund

`POST /{id}/refund`

Partner wallet (только B2B `agency`)

`GET /partners/{partner_id}/wallets`

`GET /partners/{partner_id}/wallet/transactions?currency=USD`

Multi-currency

On this page