16. Online payments (Razorpay)

The system can collect invoice payments through Razorpay: UPI, cards and netbanking. Each society connects its own Razorpay account, so the money is settled by Razorpay directly to the society's bank account. Nothing passes through the software provider.

Once connected:

• every unpaid invoice's PDF carries a payment link,
• the invoice page gains a Pay Online button,
• a successful payment is recorded on the invoice by itself, with its receipt and ledger entry, without anyone typing it in.

Online payments are optional. Without them, payments are recorded by hand as in chapter 13.

A Razorpay account in the society's name, with its KYC completed for live payments, and three values from it:

All three are stored encrypted. The two secrets are never shown again after saving.

The app has its own step-by-step Razorpay Setup Guide, with your society's webhook URL filled in and links to Razorpay's official instructions. Follow that page for the details. In outline:

1. Open Settings and, under Online Payments, click Razorpay Payment Gateway . Keep the page open. The setup guide is the first link on it.
2. Sign in to the Razorpay Dashboard and choose Test Mode or Live Mode.
3. In Razorpay, under Account & Settings, API Keys, generate a key. Copy the Key ID and Key Secret into the settings page straight away.
4. On the settings page, under Your Webhook URL, click Copy .
5. In Razorpay, under Account & Settings, Webhooks, add a new webhook. Paste the URL, type a secret of your choice, and tick the four events: payment.captured, payment.failed, order.paid and payment_link.paid.
6. Enter the same secret in Webhook Secret on the settings page.
7. Tick Accept online payments and click Save Razorpay Settings .
8. Click Test Connection . "Connected to Razorpay successfully" confirms the Key ID and Key Secret.

The page is open to the Superadmin and Manager, and to staff whose role has the Razorpay Payment Gateway permission.

Through the payment link on the bill. When online payments are on, the invoice PDF of any invoice with a balance carries a Pay Online block with a link reading "Pay ₹ ... online (UPI / Card / Netbanking)". A resident signs in, opens My Invoices , downloads the invoice PDF and follows the link to Razorpay's payment page. You can also send the PDF to the resident yourself.

• The link is for the full balance due on the day the PDF was downloaded, late penalty included. It does not accept part payment.
• The same link is reused while the balance is unchanged. When the balance changes, the next PDF carries a new link for the new amount.
• No link is printed on a Paid or Cancelled invoice.

Through the Pay Online button. On the invoice page a Pay Online box opens Razorpay's checkout window on the spot. Residents see it on their own unpaid invoices and pay the full amount due. People who can record payments (the Superadmin, the Manager and staff with the Record Payment permission) see it below the payment panel and can use it at the office counter, including for a part payment:

1. Open the unpaid invoice.
2. Check Amount Received in the Payment tab. It holds the full balance.
3. Click Pay Online and complete the payment in the Razorpay window.
4. The page reloads with "Payment received. Thank you!" and the invoice updated.

The button is not offered while the invoice is Processing a cheque or bank transfer, or once it is Paid or Cancelled.

The Pay Online button charges whatever is in Amount Received. To take a part payment, type a smaller amount there before clicking the button. The amount must be more than zero and not more than the balance due.

After a part payment the invoice is Partially Paid and can be paid again, online or by hand, until the balance is cleared. The payment link in the PDF always asks for the whole balance.

Online payments never go through Processing. They are counted the moment Razorpay confirms them.

A webhook is a message Razorpay sends to the system when something happens to a payment. The system learns about a payment in two ways:

• From the checkout window. When a payment made with the Pay Online button succeeds, the page reports it straight back.
• From the webhook. Razorpay reports the payment on its own, a moment later.

Whichever arrives first records the payment. The other finds it already recorded and does nothing, so a payment is never counted twice.

• Every webhook message is checked against your Webhook Secret. A message with the wrong signature is refused.
• A failed payment attempt changes nothing on the invoice. The resident can simply try again.
• The webhook URL must be reachable from the internet over HTTPS.
• Webhooks are ignored while Accept online payments is unticked.

• "Razorpay rejected the Key ID / Key Secret": the pair does not match, or one was mistyped. Generate a new key in Razorpay and enter both values again.
• "Key ID must start with rzp_live_ or rzp_test_": you pasted something other than the Key ID.
• "... is required to accept online payments": all three values must be saved before Accept online payments can be ticked.
• "Stored credentials could not be decrypted": the server's encryption key was changed. Enter all three values again.
• A resident paid by link but the invoice is still unpaid: the webhook did not arrive. Check in the Razorpay Dashboard that the webhook exists in the right mode, uses your society's URL and the same secret, and has all four events ticked. Razorpay retries undelivered messages for a while, so once the webhook is corrected the payment may record itself. If it does not, record it on the invoice by hand (chapter 13) with Razorpay's payment ID as the reference. Do this once only and after checking Payment History, because a late message from Razorpay would record the same payment a second time.
• No Pay Online button and no link in the PDF: Accept online payments is unticked, a value is missing, the invoice has no balance or is Processing, or Razorpay has been switched off for the society.
• The link in an old PDF asks for the wrong amount: the balance has changed since it was downloaded. Download the PDF again.
• Payments work in testing but not for real: Test keys are still saved. Replace them with Live keys and create the webhook again in Live Mode.