Razorpay Payment Gateway

This document explains how to configure and use the Razorpay Payment Gateway Addon within the KiviCare Clinic Management System. It is intended for administrators who want to accept secure online payments using Razorpay.

Overview

The Razorpay Payment Gateway Addon enables clinics to accept payments using Razorpay’s secure checkout.

It supports multiple payment methods, including:

• Credit Cards
• Debit Cards
• Net Banking
• UPI
• Wallets

The integration works by creating an Order in Razorpay, redirecting the patient to a secure checkout, and verifying the payment signature upon completion.

Prerequisites

Before configuring Razorpay, ensure the following requirements are met:

• KiviCare Razorpay Addon
  • The Razorpay addon must be installed and activated.
• Razorpay Account
  • A valid Razorpay account created at razorpay.com.
• Account Activation
  • Your Razorpay account must be activated to accept payments.

Razorpay Configuration in KiviCare

Step 1: Navigate to Payment Settings

1. Log in to the WordPress Admin Dashboard.
2. Go to KiviCare > Settings > Payment Settings.

Step 2: Enable Razorpay Gateway

1. Locate Razorpay in the list of available payment gateways.
2. Toggle the Enable switch (Green).
3. Click Manage (or the edit icon) to open Razorpay settings.

Step 3: Configure Razorpay Settings

Fill in the following fields:

• Enable Razorpay
  Must be checked to activate Razorpay payments.
• Mode
  Choose the operating environment:
  • Sandbox (Test) – For testing payments
  • Live – For real transactions
• Key ID
  Enter your Razorpay Key ID (e.g., rzp_test_... or rzp_live_...).
• Key Secret
  Enter your Razorpay Key Secret.
• Currency
  Select the currency to accept payments in (Default: USD).

Step 4: Save Settings

Click the Save button to apply and store your Razorpay configuration.

How to Obtain Razorpay API Keys

Follow these steps to generate Razorpay API credentials:

1. Log in to the Razorpay Dashboard.
2. Navigate to Settings > API Keys.

Test Mode Keys

1. Enable Test Mode using the toggle at the top.
2. Click Generate Test Key.
3. Copy the Key ID and Key Secret.

Live Mode Keys

1. Switch to Live Mode.
2. Click Generate Live Key.
3. Copy the Key ID and Key Secret.

Important: Test keys only work in Sandbox mode, and Live keys only work in Live mode.

Payment Flow

• Patient books an appointment in KiviCare.
• Patient selects Razorpay as the payment method.
• KiviCare creates an Order using Razorpay’s /orders API.
• Razorpay secure checkout is displayed to the patient.
• Patient completes the payment.
• KiviCare verifies the payment using:
  • razorpay_order_id
  • razorpay_payment_id
  • razorpay_signature
• Upon successful verification:
  • Payment is captured (if not already captured).
  • Appointment status is updated to Confirmed.

Razorpay Webhook & Secret Key Configuration

1. Introduction

The Razorpay Webhook integration allows KiviCare to receive real-time notifications from Razorpay regarding payment status. This ensures that appointment bookings are updated instantly, even if a patient closes their browser window before being redirected back to your website.

The addition of the Webhook Secret Key provides an extra layer of security, ensuring that only authentic messages from Razorpay are processed by your clinic system.

2. Configuration Guide

Step 1: KiviCare Setup

1. Log in to your WordPress Admin Dashboard.
2. Navigate to KiviCare Settings → Payment Gateways → Razorpay.
3. Webhook Secret: Create a secure password or string and enter it into the “Webhook Secret” field.
   • Tip: Keep this secret handy as you will need to enter the exact same string in your Razorpay account.
4. Webhook URL: You will see a unique URL generated in the settings. Copy this URL to your clipboard.

Step 2: Razorpay Dashboard Setup

1. Log in to your Razorpay Dashboard.
2. In the left sidebar, go to Settings → Webhooks.
3. Click on the + Add New Webhook button.
4. Webhook URL: Paste the URL you copied from your KiviCare settings.
5. Secret: Enter the exact same Webhook Secret string you created in Step 1.
6. Active Events: Under the “Select Events” section, check the boxes for:
   • payment.captured
   • payment.failed
   • refund.created
7. Click Create Webhook to save your settings.

3. Key Benefits & Features

Automated Appointment Confirmation

Once configured, KiviCare will automatically confirm appointments as soon as Razorpay captures the payment. This eliminates the need for manual status updates and prevents “pending” appointments caused by browser closure or network interruptions.

Enhanced Security

The Webhook Secret Key acts as a digital handshake. Every notification sent by Razorpay is signed using this secret. KiviCare verifies this signature before taking any action, preventing unauthorized or fraudulent payment confirmations.

Real-Time Status Mapping

The system automatically synchronizes the following states:

• Successful Payment: Automatically marks the appointment as “Booked” .
• Failed Payment: Automatically marks the appointment as “Cancelled”.
• Refunds: Updates the internal payment logs if a refund is issued through the Razorpay dashboard.

If payment fails or is cancelled, the appointment remains Cancelled.

Troubleshooting

Common Issues and Solutions

Payment Failed

• Verify the Key ID and Key Secret are correct.
• Ensure keys match the selected Mode (Test or Live).
• Confirm that your Razorpay account is active.

Signature Verification Failed

• This usually indicates an incorrect Key Secret.
• Re-check and re-save Razorpay credentials in KiviCare.

Currency Issues

• Ensure your Razorpay account supports the selected currency.
• For non-INR currencies, international payments must be enabled in Razorpay.

Razorpay Checkout Not Loading

Ensure your site is using HTTPS.

Best Practices

• Always test payments using Sandbox mode before switching to Live.
• Keep your Key Secret secure and confidential.
• Enable international payments if accepting non-INR currencies.
• Regularly monitor transactions from the Razorpay Dashboard.