Troubleshoot payments
Audience: Manager / admin
Objective: Understand payment options, ledger states, and key configuration limits.
Symptoms
- Card / Razorpay checkout unavailable
- Deposit recorded but settlement incomplete
- Webhook mismatches in production
- Duplicate charge risk after timeout
- Day reconcile shows bank settled as "Not linked"
Likely causes
| Cause | How to check |
|---|---|
| Live Razorpay keys not configured | Env / Integrations |
| Test vs live key mismatch | Dashboard key mode |
| Webhook secret missing / wrong URL | Prefer POST /api/v1/payments/webhooks/razorpay |
| Network failure mid-checkout | Open /payments — look for pending then verify before retry |
| Offline queue | Cash/record OK; live Collect requires connectivity |
| Bank settlement null | Expected until Settlements/Payouts API is configured |
Fix
- Prefer cash / record-external when guest already paid outside Opseno.
- For live UPI/card:
- Folio:
/front-desk/check-out/...→ Pay with Razorpay - Retail POS:
/pos→ UPI or Card → Collect via Razorpay - F&B:
/fnb/orders/...→ UPI or Card → Pay & settle - Status:
GET /api/v1/payments/razorpay/status
- Folio:
- If Checkout may have succeeded: do not collect again until
/paymentsshowscapturedor Razorpay dashboard confirms. - Day close:
/payments→ Reconcile day (Opseno ledger). Bank settlement stays unset without payout credentials. - Refunds:
POST /api/v1/payments{ "action": "refund", "payment_id", "amount", "reason" }(manager/admin).
Related
- Check out a guest
- Go-live
- Engineering report:
docs/plans/OPSENO-PAYMENTS-ENGINEERING-REPORT.md