Copy page

Бронь и оплата

Возвраты

Главное

• Возврат — только по заявке. Ваша CRM подаёт заявку, деньги не двигаются, пока её не одобрит сотрудник лагеря с правом «Одобрять возвраты». Одобрить заявку или «вернуть сразу» через API нельзя никогда.
• Возвращается только оплата по счёту Kaspi, который выставила система лагеря. Деньги уходят обратно тому, кто платил, через тот же Kaspi.
• Оплату другим способом (наличные, перевод на карту, банковский перевод) возвращает только лагерь вручную.
• Деньги возвращаются с того же юрлица (ИП или ТОО), которое их приняло. Деньги одной брони между юрлицами не делятся.
• Отмена брони сама по себе деньги не возвращает. Отменили бронь, по которой платили, — подайте заявку на возврат.

Путь заявки

Code
requested ──► approved ──► sending ──► done      деньги у плательщика
    │                          │
    │                          ├──► failed       Kaspi отказал, денег не ушло
    │                          │
    │                          └──► needs_check  Kaspi не ответил — лагерь проверяет вручную
    │
    ├──► rejected   лагерь отклонил (причина в reject_reason)
    └──► cancelled  заявку отозвали

Список состояний может пополняться.

Подать заявку

POST /bookings/{id}/refund-requests с Idempotency-Key, право bookings:

Code
curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/bookings/15230/refund-requests \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Idempotency-Key: 8e4b0d2a-c7f1-4a39-b6e5-0f2d9a7c3b18" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "9120",
    "amount": "50000",
    "reason": "Ребёнок заболел, семья отказалась от поездки"
  }'

Ответ 201:

Code
{
  "id": "41",
  "booking_id": "15230",
  "payment_id": "9120",
  "invoice_id": "731",
  "amount": { "amount": "50000.00", "currency": "KZT" },
  "reason": "Ребёнок заболел, семья отказалась от поездки",
  "state": "requested",
  "reject_reason": null,
  "by_api": true,
  "created_at": "2027-06-02T08:12:40.551023Z",
  "decided_at": null,
  "finished_at": null,
  "refund_payment_id": null,
  "version": "2027-06-02T08:12:40.551023Z"
}

by_api: true — заявку подало ваше подключение (а не сотрудник лагеря).

Можно вернуть часть оплаты. Можно подать несколько заявок по одной оплате — вместе они не превысят её суммы, даже если поданы одновременно.

Следить за заявкой

• GET /bookings/{id}/refund-requests — заявки по брони;
• GET /refund-requests/{id} — одна заявка;
• события refund_request.created, refund_request.approved, refund_request.rejected, refund_request.cancelled, refund_request.done, refund_request.failed. В object события — заявка целиком.

Когда деньги ушли (done), приходит и событие payment.refunded: у брони появился платёж с type: refund и отрицательной суммой, paid уменьшилось, debt вырос.

Отказы