Razorpay IFSC Getting Started: Account, Keys, First API Call

Getting started overview

Integrating Razorpay IFSC involves several key steps that allow you to accept payments, manage subscriptions, or process payouts within India. This guide provides a rapid onboarding path, covering account creation, API key generation, and executing a foundational API request. The objective is to establish a working integration quickly, enabling further development and customization. Razorpay provides comprehensive developer documentation and various SDKs across multiple programming languages to facilitate this process.

Before initiating live transactions, it is recommended to test all integrations thoroughly in the provided sandbox environment. This ensures that the payment flows and system interactions function as expected without affecting actual funds. Once testing is complete, transitioning to the live environment requires activating your account and using live API keys.

Quick Reference Guide

Create an account and get keys

To begin using Razorpay IFSC, the first step is to create a business account. This process typically involves providing your business details and completing Know Your Customer (KYC) verification, which is a regulatory requirement for financial services providers in India. Detailed guidance on the account activation process is available in the official documentation.

Account Registration

1. Navigate to the Razorpay signup page.
2. Provide your email address and create a password.
3. Enter your business legal name, type, and other required information.
4. You will receive an email for verification; confirm your email address to proceed.

KYC and Account Activation

Upon initial signup, your account will be in a "Test Mode" or "Sandbox" state. To accept live payments, you must complete the KYC process. This involves submitting documents such as:

• PAN Card (Permanent Account Number)
• Bank Account Details (for settlements)
• Business Registration Documents (e.g., GST certificate, proprietorship declaration)

The specific documents required may vary based on your business type (e.g., individual, sole proprietor, private limited company). Razorpay provides a checklist for account activation within their documentation. Once documents are submitted and verified, your account will be activated for live transactions.

Generating API Keys

API keys are essential for authenticating your application's requests to the Razorpay API. You will generate a pair of keys: an API Key ID and an API Key Secret. It is critical to keep your API Key Secret confidential, as it grants access to your account's functionalities. Never expose it in client-side code or public repositories. Razorpay differentiates between "Test" keys and "Live" keys:

• Test Keys: Used for development and testing in the sandbox environment. Transactions made with these keys do not involve real money.
• Live Keys: Used for production environments and processing actual payments.

To generate your keys:

1. Log in to your Razorpay Dashboard.
2. Navigate to Settings > API Keys.
3. Click on Generate Key. If keys already exist, you may regenerate them, which invalidates the previous keys.
4. Download the generated keys or copy the Key ID and Key Secret. Store them securely.

The API keys section of the Razorpay documentation provides more information on securely managing your credentials.

Your first request

After acquiring your API keys, the next step is to make a basic API call to verify your setup. This usually involves creating an "Order" object, which is a prerequisite for initiating a payment. For this initial request, we will use the Razorpay API directly via curl or a similar HTTP client, demonstrating the core authentication method. Using one of Razorpay's official SDKs is generally recommended for production applications, as they handle authentication and request formatting automatically.

Authentication

Razorpay API uses Basic Authentication. Your API Key ID serves as the username, and the API Key Secret serves as the password. These are typically base64 encoded as API_KEY_ID:API_KEY_SECRET. For example, if your Key ID is rzp_test_xxxxxxxxxxxxxx and Key Secret is yyyyyyyyyyyyyyyyyyyy, the string to encode would be rzp_test_xxxxxxxxxxxxxx:yyyyyyyyyyyyyyyyyyyy.

Sample: Create an Order

An Order is an object that encapsulates information about the payment, such as the amount, currency, and receipt ID. Creating an order is the first step in the payment flow. This example uses a curl command. Remember to replace YOUR_KEY_ID and YOUR_KEY_SECRET with your actual Test API Keys.

curl -X POST https://api.razorpay.com/v1/orders \
     -u "YOUR_KEY_ID:YOUR_KEY_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"amount": 50000, "currency": "INR", "receipt": "rcptid_11"}'

In this request:

• -X POST: Specifies the HTTP method.
• https://api.razorpay.com/v1/orders: The endpoint for creating orders.
• -u "YOUR_KEY_ID:YOUR_KEY_SECRET": Provides your API credentials for Basic Authentication.
• -H "Content-Type: application/json": Indicates that the request body is JSON.
• -d '{"amount": 50000, "currency": "INR", "receipt": "rcptid_11"}': The request body containing order details. The amount is in the smallest currency unit (paise for INR), so 50000 represents ₹500.00.

A successful response will return a JSON object containing the created order's details, including an id field (e.g., order_xxxxxxxxxxxxxx) which is crucial for subsequent payment initiation. Razorpay's Orders API documentation provides further details on available parameters and responses.

Using an SDK (Example: Python)

While the curl example demonstrates direct API interaction, using an SDK simplifies development. Here's a Python example for creating an order:

import razorpay

client = razorpay.Client(auth=("YOUR_KEY_ID", "YOUR_KEY_SECRET"))

data = {
    "amount": 50000,  # amount in paise
    "currency": "INR",
    "receipt": "rcptid_12"
}

order = client.order.create(data)
print(order)

Ensure you have the Razorpay Python SDK installed (pip install razorpay). This code initializes the client with your Test API keys and then calls the order.create method with the order details.

Common next steps

After successfully creating your first test order, you can proceed with further integration steps to build a complete payment experience:

• Integrate Payment Gateway: Typically involves using Razorpay's checkout SDK (e.g., Razorpay Standard Checkout) to present a payment interface to your users. This often involves client-side integration to display the payment form and handle user input.
• Handle Webhooks: Set up webhooks to receive asynchronous notifications from Razorpay about payment status updates (e.g., successful payment, failed payment, refund). This is crucial for updating your order status and managing inventory. For instance, receiving event notifications is a common practice in modern web applications, similar to how Stripe handles webhooks for payment events.
• Process Refunds: Learn how to initiate refunds for completed transactions through the API or dashboard.
• Manage Subscriptions: If your business model involves recurring payments, explore Razorpay's Subscriptions API for automating recurring billing cycles.
• Explore Other Products: Depending on your needs, investigate other Razorpay offerings like Payment Links, Route for marketplace payouts, or Payroll.
• Go Live: Once thoroughly tested, switch to your Live API keys and ensure your account is activated for production transactions.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• Authentication Failure (401 Unauthorized):
  • Issue: Invalid API Key ID or Secret, or incorrect Basic Auth header.
  • Solution: Double-check your Key ID and Secret for typos. Ensure they are Test keys for the sandbox environment. Verify the Basic Auth string is correctly formatted (Key_ID:Key_Secret base64 encoded or directly provided in the -u flag for curl, as shown in the example). Make sure you're using the correct API keys for the selected mode (Test vs. Live).
• Invalid Request Payload (400 Bad Request):
  • Issue: Incorrect JSON format, missing required parameters, or invalid values for parameters (e.g., negative amount, unsupported currency).
  • Solution: Review the API documentation for the specific endpoint you are calling (Orders API). Compare your request body against the expected schema. Ensure the Content-Type: application/json header is present. The amount should be a positive integer in the smallest currency unit.
• Network Connection Issues:
  • Issue: Your server cannot reach Razorpay's API endpoints.
  • Solution: Check your firewall rules and network connectivity. Ensure that outbound connections to api.razorpay.com on HTTPS (port 443) are allowed. Tools like ping or traceroute can help diagnose network reachability.
• Rate Limiting (429 Too Many Requests):
  • Issue: Sending too many requests in a short period.
  • Solution: Razorpay implements rate limits to prevent abuse. If you encounter this, implement exponential backoff and retry logic in your application.
• Test Mode vs. Live Mode:
  • Issue: Attempting to use Live API keys in a Test environment or vice versa.
  • Solution: Always ensure you are using the appropriate set of API keys (Test or Live) for your current environment. Test keys will only work with the test payment gateway, and live keys with the live gateway.

For more specific error codes and troubleshooting advice, refer to Razorpay's API error codes documentation.