Configuring Razorpay App

This guide details how to connect your CRM microservice, backend, and Razorpay to create a seamless payment workflow. There are three main areas you will need to configure:

• Razorpay Dashboard: Generate keys, set up webhooks, plans, and offers.
• Backend Codebase: Securely handle order creation and webhook callbacks.
• CRM Configuration Panel: Save credentials, select the environment, and link all components together.

Once all three parts are configured and working together, your integration is ready.

---

CRM Configuration Setup

Click on App from the bottom-left menu in your CRM then from the list of apps, select  Razorpay.

Configure the following fields in your CRM's Razorpay settings. Reference links are provided for detailed explanations in each relevant Razorpay section.

Field	Description & Setup Link
Active Environment	Choose Test or Production — see details
Auth ID	Razorpay Key ID — generate keys
Client Secret	Razorpay Key Secret — generate keys
Callback URL	Backend endpoint — see callback setup
Webhook Secret	Value from Razorpay — configure webhook
Plans	Registered Plan IDs — create plans

---

Razorpay Setup

Test vs Live Environments

• Test Mode: Use for development and webhook simulation.
• Live Mode: Real transactions; requires KYC completion and bank details.
• For recurring payments, enable mandate modes such as UPI or card recurring.
• Keep credentials for test and live modes separate.

Generate Keys and Secrets

In Dashboard → Settings → API Keys → Generate Key. Copy and store:

• Key ID: use as Auth ID in CRM.
• Key Secret: use as Client Secret in CRM (shown once).

If you don’t have a Razorpay account, create one and complete verification before proceeding.

Add Webhooks

you will see this URL when opening configuration modal in CRM.

Go to Dashboard → Settings → Webhooks → Add new webhook.

• Webhook URL: https://cs.fabbuilder.com/cs-app/razorpay/api/tenant/<tenant_id>/webhook
• Secret: define a webhook secret and add it to CRM configuration.
• Events:  Subscribe to these minimum events 
  • payment.captured
  • payment.failed
  • subscription.activated
  • subscription.charged
  • subscription.halted
  • subscription.cancelled
  • token related (if using charge at will)
  • payment links related 

Razorpay → CRM: CRM validates signatures and forwards the validated payload to your backend callback URL.

Create Plans (Subscriptions)

Create recurring billing plans in Dashboard → Subscriptions → Plans → Create Plan. Required fields:

• Plan name
• Amount
• Billing frequency

Copy the generated planId and register it in CRM or include it in create-order payloads.

Create Offers

Offers apply discounts or cashback for a single payment method. Create separate offers for each method:

• Offer for UPI → offerId_upi
• Offer for Card → offerId_card

Note: Only one offerId can be used per transaction. Apply based on the user’s payment method.

---

Backend Setup

Create Order (One-time vs Subscription)

The CRM provides an endpoint to create Razorpay orders or subscriptions and return checkout data.

Note: for leadId read this.

CRM_API_HOST="https://cs.fabbuilder.com"
CRM_TENANT_ID="your_tenant_id"
CRM_RAZORPAY_SUBURL="cs-app/razorpay"

const response = await axios.post(
  `${CRM_API_HOST}/${CRM_RAZORPAY_SUBURL}/api/tenant/${CRM_TENANT_ID}/razorpay/customer/create-order`, payload
);
const order = response.data.data;
if (!order || !order.id) {
  console.error('response error', response.data);
  throw new Error('Razorpay order not created. Please try again.');
}
  

One-time Payment Payload:

{
  "type": "one_time",
  "leadId": "",
  "email": "customer@example.com",
  "contact": "9999999999",
  "amount": 50000,
  "offerId": ""
}
  

Subscription Payload:

{
  "type": "recurring",
  "leadId": "",
  "email": "customer@example.com",
  "contact": "9999999999",
  "planId": "plan_XXXX",
  "offerId": ""
}
  

CRM Expected Response:

{
  "success": true,
  "data": {
    "id": "order_XXXX" // or "sub_XXXX" for subscriptions
  }
}
  

Webhook Callback Endpoint

Endpoint

Expose a POST endpoint in your backend to receive Razorpay webhook events:

<backend_url>/api/webhooks/razorpay

Controller Implementation

Example controller for handling Razorpay webhook events:

export default async function handleRazorpayWebhook(req, res) {
  try {
    const { event, payload } = req.body;

    switch (event) {
      case 'subscription.activated':
        await processSubscriptionActivated(payload);
        break;
      case 'subscription.charged':
        await processSubscriptionCharged(payload);
        break;
      case 'subscription.halted':
        await processSubscriptionHalted(payload);
        break;
      case 'subscription.cancelled':
        await processSubscriptionCancelled(payload);
        break;
      case 'payment.captured':
        await processPaymentCaptured(payload);
        break;
      case 'payment.failed':
        await processPaymentFailed(payload);
        break;
      default:
        console.warn('Unhandled event type:', event);
    }

    return res.status(200).json({ status: 'ok' });
  } catch (err) {
    console.error('Webhook handler error', err);
    return res.status(500).json({ error: 'processing_failed' });
  }
}

• Acknowledge quickly (return 200 OK).
• Log raw events for debugging and audits.

---

Testing and Best Practices

• Start in Test Mode using Razorpay’s test upi/cards.
• Never mix Test and Live credentials.
• Monitor webhook logs.
• Determine user payment mode before order creation to attach correct offerId.
• Ensure Live Mode setup: KYC complete, bank details added, recurring mode enabled.

---

Conclusion

Once Razorpay, CRM, and Backend are properly configured:

• CRM creates orders/subscriptions via Razorpay for clients.
• CRM validates and forwards webhook events to your backend.
• Frontend receives order data and completes the checkout flow.

Your integration is complete, secure, and ready for production.