Authentication overview

Razorpay's API authentication system is designed to secure transactions and access to sensitive financial data. The primary method involves a pair of unique credentials: a Key ID and a Key Secret. These are mandatory for almost all API requests made to the Razorpay platform, ensuring that only authorized applications can initiate actions such as creating payments, managing refunds, or accessing transaction reports. This approach is standard for many payment gateways due to its simplicity and effectiveness for server-to-server communication Razorpay API authentication overview.

When an API call is made, the Key ID identifies the merchant's account, while the Key Secret is used to sign the request, verifying its authenticity. This mechanism protects against unauthorized access and tampering with requests in transit. For client-side integrations, particularly with the Razorpay Checkout, only the Key ID is typically exposed, as the secret remains on the backend. This separation of concerns is critical for maintaining the integrity of payment processes and user data Razorpay security practices in payments.

Razorpay maintains compliance with industry-standard security protocols, including PCI DSS Level 1, SOC 2 Type II, and GDPR Razorpay security certifications and compliance. These certifications dictate stringent requirements for handling sensitive data, including how authentication credentials are generated, stored, and used, further underpinning the security of its API interactions.

Supported authentication methods

Razorpay primarily supports a single, robust authentication method for its core API interactions. While various levels of security are applied depending on the context (e.g., server-side vs. client-side), the underlying mechanism remains consistent.

Method When to Use Security Level
Key ID and Key Secret (Basic Authentication)
  • All server-side API requests
  • Creating payments, refunds, settlements
  • Accessing transaction data
  • Integrations with backend systems (e.g., e-commerce platforms, ERPs)

High. Requires both a public identifier (Key ID) and a private credential (Key Secret) to be present in the HTTP Basic Auth header. The Key Secret should never be exposed client-side. This method is effective for securing server-to-server communications, a common pattern for API security Mozilla HTTP Authorization header documentation.
Key ID Only (Client-Side Checkout)
  • When integrating the Razorpay Checkout on a client-side application (web browser, mobile app)
  • Initiating the payment flow directly from the user's device

Moderate-High. The Key ID is publicly exposed to initialize the checkout form. However, sensitive operations (like charging a card) are not performed directly by the client using only the Key ID. Instead, the client interacts with Razorpay's secure checkout environment, which then communicates with the backend using its own secure channels. The actual payment processing and sensitive data handling occur on Razorpay's PCI DSS compliant servers, isolating the client from direct card data exposure Razorpay Checkout customization documentation.

Getting your credentials

To interact with the Razorpay API, you must first obtain your Key ID and Key Secret. These credentials are generated through the Razorpay Dashboard.

  1. Log in to the Razorpay Dashboard: Access your merchant account at https://dashboard.razorpay.com/.
  2. Navigate to API Keys: From the dashboard, go to Settings > API Keys.
  3. Generate New Key: If you do not have an active key pair, click Generate Key. If you have an existing key, you can view its Key ID. To regenerate the Key Secret (which is only shown once), you will need to revoke the old key and generate a new one. This action is irreversible for the old key pair Razorpay API keys generation guide.
  4. Securely Store Credentials: Upon generation, Razorpay will display both your Key ID and Key Secret. It is critical to copy and securely store your Key Secret immediately, as it will not be displayed again. Treat your Key Secret with the same level of confidentiality as you would a password. It should never be hardcoded into client-side code, committed to version control systems like Git, or exposed in public-facing applications.
  5. Test Mode vs. Live Mode: Razorpay provides separate API keys for 'Test Mode' and 'Live Mode'. Always ensure you are using the correct set of keys for your development and production environments respectively to avoid processing real transactions when testing or vice-versa Razorpay Test Mode documentation.

Authenticated request example

Razorpay API requests typically use HTTP Basic Authentication. This means the Key ID and Key Secret are combined, base64-encoded, and sent in the Authorization header.

Consider an example in Python using the requests library to create an order:


import requests
from requests.auth import HTTPBasicAuth
import json

# Replace with your actual Key ID and Key Secret
KEY_ID = 'YOUR_KEY_ID'
KEY_SECRET = 'YOUR_KEY_SECRET'

# API endpoint for creating orders
API_URL = 'https://api.razorpay.com/v1/orders'

# Order payload
order_payload = {
    'amount': 50000,  # amount in paise (e.g., 500.00 INR)
    'currency': 'INR',
    'receipt': 'receipt#1',
    'payment_capture': 1  # 1 for auto-capture, 0 for manual
}

try:
    response = requests.post(
        API_URL,
        auth=HTTPBasicAuth(KEY_ID, KEY_SECRET),
        json=order_payload
    )

    response.raise_for_status()  # Raise an exception for HTTP errors

    order_data = response.json()
    print("Order created successfully:")
    print(json.dumps(order_data, indent=4))

except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
    print(f"Response content: {err.response.text}")
except requests.exceptions.RequestException as err:
    print(f"An error occurred: {err}")

In this Python example, HTTPBasicAuth(KEY_ID, KEY_SECRET) handles the base64 encoding and setting the Authorization header automatically. For other languages or manual implementations, you would construct the header as Authorization: Basic <Base64-encoded(KEY_ID:KEY_SECRET)>.

Security best practices

Securing your Razorpay API credentials and integrating them safely is paramount to prevent financial fraud and protect sensitive data. Adhere to these best practices:

  • Never Expose Key Secret Client-Side: Your Key Secret must always remain on your backend servers. Do not embed it in JavaScript, mobile applications, or any client-side code. Only the Key ID should be used client-side for initializing the Razorpay Checkout Razorpay guidelines on API key security.
  • Store Credentials Securely: Do not hardcode API keys directly into your application's source code. Instead, use environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault) AWS Secrets Manager documentation.
  • Rotate API Keys Regularly: Periodically generate new API keys and revoke old ones. This minimizes the risk window if a key is compromised. A common practice is to rotate keys every 90 days.
  • Implement Strong Access Controls: Limit access to your Razorpay Dashboard and API keys to only those personnel who absolutely require it. Use strong, unique passwords and enable multi-factor authentication (MFA) for all Razorpay Dashboard accounts.
  • Use IP Whitelisting: If your infrastructure allows, configure IP whitelisting in your Razorpay Dashboard settings. This ensures that API requests can only originate from a predefined set of trusted IP addresses, adding an extra layer of security.
  • Monitor API Activity: Regularly review your API logs for unusual activity or failed authentication attempts. Razorpay provides logging and reporting features in their dashboard that can help identify potential security breaches Razorpay blog on securing API keys.
  • Validate Webhooks: If you use Razorpay webhooks, always verify the signature of incoming requests to ensure they genuinely originate from Razorpay and haven't been tampered with. Webhook secret validation prevents spoofing Razorpay webhooks documentation.
  • Secure Your Development Environment: Treat development and staging environments with similar security considerations as production. Do not use live API keys in development, and ensure all test credentials are for sandbox environments only.