Payments

Card payments with Thawani, requests to book with payment on arrival, and refunds.

Guests can pay in two ways. You choose which ones are offered in Dashboard > Company settings > Payments.

Way What happens Status after booking
Pay now by card (Thawani) The guest is sent to Thawani's secure page. The booking is confirmed when Thawani tells our server the payment went through PENDING + UNPAID, then CONFIRMED + PAID
Request to book, pay on arrival No payment online. The host confirms the request in the dashboard; the guest pays at the stay PENDING + UNPAID, then CONFIRMED

Both hold the nights at once, so nobody else can book them in the meantime.

Setting up Thawani

  1. Open a merchant account with Thawani Pay (Oman). You get a secret key and a publishable key, first for the test environment (UAT).

  2. Put them in .env:

    THAWANI_MODE="uat"
    THAWANI_SECRET_KEY="..."
    THAWANI_PUBLISHABLE_KEY="..."
    
  3. Restart, then switch on Card payments in Company settings. The currency must be OMR.

  4. Make a test booking with Thawani's test card. When everything works, change THAWANI_MODE to live with your live keys.

How a card payment is checked

  1. POST /api/bookings prices the stay on the server, saves the booking and its nights, and asks Thawani for a checkout session for the exact total (src/lib/thawani.ts).
  2. The guest pays on Thawani's page and is sent back to /api/payments/thawani/return?booking=CODE.
  3. That route asks Thawani whether the session is paid. Only then does the booking become PAID and CONFIRMED. Nothing in the return address is trusted, so editing the URL cannot confirm a booking.
  4. If the guest cancels on Thawani's page, the booking is cancelled and its nights are freed.
  5. If the guest simply closes the tab, the booking stays unpaid and its nights are released after 30 minutes (HOLD_MINUTES in src/lib/booking-rules.ts).

If Thawani cannot be reached when the booking starts, the booking is cancelled at once and the guest sees "Card payment could not start".

Refunds and cancellations

Guests ask to cancel from Find your booking; the request appears on the dashboard overview and on the booking. You decide:

  • Cancel booking: the nights are freed at once. Refund the card payment in the Thawani portal, then press Mark as refunded so the books stay right.
  • Keep the booking: the request is closed and the guest keeps their nights.

The free cancellation period (days before arrival) shown to guests is set in Company settings.

Pay on arrival

When the guest pays at the stay, open the booking and press Mark as paid. Bookings added by hand in the dashboard can be marked as paid when you create them.

Other payment providers

The payment code is small and isolated: src/lib/thawani.ts (create a session, read its status) and src/app/api/payments/thawani/return/route.ts. To use another provider, write the same two functions for it and point the booking route at them.