Souq offers two payment methods at checkout. The customer chooses one; you switch each on or off in Dashboard > Settings > Orders and payments.
Cash on delivery
On by default. The order is created as NEW / not paid. When you move it to DELIVERED, its payment status becomes paid (the courier collected the cash).
Card payments with Thawani
Thawani Pay is an Omani payment gateway that accepts local debit cards and international cards, in rials.
Set up
Open a merchant account with Thawani and get your secret key and publishable key. Thawani also gives test keys for its UAT environment.
Put them in
.env:THAWANI_MODE="uat" # "live" for real payments THAWANI_SECRET_KEY="..." THAWANI_PUBLISHABLE_KEY="..." SITE_URL="https://shop.example.om"Restart the server, then switch on Card payments in Settings. The settings page tells you whether the keys were found.
Card payment appears at checkout only when the keys are set, the switch is on and the store currency is OMR.
What happens during a payment
- The customer places the order with Card. The server prices the order, takes the stock and counts the coupon, exactly as for cash, and creates the order as NEW / not paid.
- The server opens a Thawani checkout session for the order total (in baisa) and sends the customer to Thawani's payment page. Your site never sees the card number.
- Thawani sends the customer back to
/api/payments/thawani/return?order=CODE. - The server does not trust that address: it asks Thawani for the session's status with the secret key. Only if Thawani answers "paid" does the order become PAID (with a timeline entry "card payment confirmed").
- If the customer cancels on Thawani's page, the order is cancelled and its stock and coupon use are given back.
If Thawani is unreachable when the order is placed, the order is cancelled at once and the customer sees "Card payment is not available right now"; they can choose cash instead.
Statuses for card orders
A card order that is not paid yet can only be cancelled by staff: it moves forward by itself when the payment is confirmed. A paid order that is stopped before shipping becomes REFUNDED (refund the customer in the Thawani portal), not cancelled.
Testing
With THAWANI_MODE="uat" use the test cards from Thawani's documentation. The order page refreshes by itself every few seconds while it waits for the payment.
Another gateway
The payment code is in src/lib/thawani.ts (two functions: create a session, read its status) and src/app/api/payments/thawani/return/route.ts. To use another gateway, write the same two functions for it and keep the rule: mark an order paid only after asking the gateway from the server.