Płatności online

Usługa może wymagać płatności online przy rezerwacji. API tworzy wtedy rezerwację w statusie awaiting_payment i zwraca adres płatności w bramce organizacji. Klient płaci na stronie bramki i wraca na Twój return_url.

Kiedy rezerwacja jest płatna online

Sprawdź pole payment usługi:

payment	Znaczenie	Co wysłać
none	brak płatności online	nic
optional	klient może zapłacić online albo na miejscu	pay_online: true i return_url, jeśli klient płaci online
required	pełna płatność z góry	zawsze return_url
deposit	zaliczka z góry	zawsze return_url

Brak return_url przy rezerwacji płatnej online daje 422 return_url_required i rezerwacja nie powstaje. pay_online: true przy usłudze bez płatności online (none) nie jest błędem — rezerwacja powstaje z płatnością na miejscu.

Przygotowanie klucza

return_url musi mieć schemat https i host z domen powrotu klucza. Domeny ustawiasz przy tworzeniu klucza — zobacz Uwierzytelnianie. Inny adres daje 422 return_url_not_allowed.

Przepływ

1. Rezerwacja z return_url

curl -X POST https://api.rezeri.com/v1/bookings \
  -H "Authorization: Bearer $REZERI_API_KEY" \
  -H "Idempotency-Key: 6c0f4a52-order-1002" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "…",
    "staff_id": "…",
    "start": "2026-10-21T10:00:00+02:00",
    "client": {"name": "Jan Testowy", "email": "[email protected]"},
    "return_url": "https://shop.example.com/rezerwacja/wynik"
  }'

Odpowiedź 201 ma status: "awaiting_payment" i otwartą sesję płatności:

{
  "id": "4b1c…",
  "status": "awaiting_payment",
  "payment": {"required": true, "status": "pending", "amount": "90.00", "url": "https://…"}
}

2. Przekierowanie klienta

Przekieruj klienta na payment.url. Płaci na stronie bramki płatności organizacji.

Jeśli bramka nie otworzy sesji, rezerwacja i tak powstaje (201), ale payment.url ma wartość null. Otwórz wtedy sesję przez POST /v1/bookings/{id}/payment (niżej).

3. Powrót na return_url

Po płatności klient wraca na Twój adres z dwoma parametrami:

https://shop.example.com/rezerwacja/wynik?booking_id=4b1c…&payment=success

payment przyjmuje wartość:

• success — płatność zaksięgowana;
• failure — płatność nieudana albo sesja wygasła;
• pending — bramka jeszcze nie potwierdziła wyniku.

Istniejące parametry zapytania w return_url zostają. Parametry booking_id i payment Rezeri nadpisuje.

4. Weryfikacja wyniku

Parametr payment to tylko wskazówka dla interfejsu. Klient może zmienić adres w przeglądarce, a bramka bywa szybsza niż potwierdzenie płatności. Zanim wydasz usługę albo oznaczysz zamówienie jako opłacone, sprawdź stan po stronie serwera:

curl https://api.rezeri.com/v1/bookings/4b1c… \
  -H "Authorization: Bearer $REZERI_API_KEY"

Płatność jest zaksięgowana, gdy payment.status ma wartość paid. Zamiast odpytywać, możesz też nasłuchiwać zdarzeń — zobacz Webhooki.

Przy pending pokaż klientowi komunikat „Czekamy na potwierdzenie płatności” i sprawdź stan ponownie po chwili.

Pole payment rezerwacji

Pole	Znaczenie
required	czy płatność online jest obowiązkowa
status	not_required, pending, paid, failed albo refunded
amount	kwota do zapłaty albo zapłacona, string dziesiętny
url	adres żywej sesji płatności; null, gdy sesji nie ma albo wygasła

Gdy klient zapłaci online za usługę z płatnością opcjonalną, required ma wartość false, a status — paid.

Ponowienie płatności

Nieudana albo wygasła płatność nie anuluje od razu rezerwacji — zostaje ona w awaiting_payment. Otwórz nową sesję:

curl -X POST https://api.rezeri.com/v1/bookings/4b1c…/payment \
  -H "Authorization: Bearer $REZERI_API_KEY" \
  -H "Idempotency-Key: 6c0f4a52-order-1002-retry-1" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://shop.example.com/rezerwacja/wynik"}'

Odpowiedź 200 to {url, expires_at}. Gdy rezerwacja ma jeszcze żywą sesję, dostajesz tę samą sesję, a nie nową.

• Idempotency-Key jest wymagany. Powtórka z tym samym kluczem zwraca zapisaną sesję, nawet gdy już wygasła. Po wygaśnięciu użyj nowego klucza.
• return_url przechodzi tę samą walidację co przy tworzeniu rezerwacji.
• Jeśli żywą sesję otworzył wcześniej widget organizacji, API użyje jej ponownie, a klient wróci po płatności na stronę widgetu, nie na return_url.

Nieopłacona rezerwacja jest anulowana automatycznie po upływie terminu płatności.

Błędy sesji płatności

Sytuacja	Błąd
Rezerwacja już opłacona	409 already_paid
Rezerwacja anulowana, zakończona albo bez płatności online	409 not_payable
Rezerwacja czeka najpierw na akceptację pracownika	409 awaiting_acceptance
Bramka odmówiła otwarcia sesji	502 payment_provider_error

Po 502 payment_provider_error możesz ponowić żądanie z tym samym Idempotency-Key.

Zwroty

Anulowanie przez POST /v1/bookings/{id}/cancel stosuje zasady zwrotu organizacji. Po zakończonym zwrocie payment.status ma wartość refunded. Zobacz Rezerwacje — anulowanie.

Testowanie płatności

Przepływ sprawdzisz bez prawdziwych pieniędzy, przełączając bramkę organizacji w tryb testowy operatora. HotPay go nie ma. Zobacz Testowanie integracji.