Razorpay Python SDK

Warnings

• breaking All amounts are in paise (smallest currency unit) — NOT rupees. 500 INR must be passed as 50000. Passing 500 charges 5 paise (₹0.05). No error is raised — silent wrong charge.
  Fix: amount_in_paise = amount_in_inr * 100. Always multiply INR by 100.
• breaking Signature verification is mandatory after payment. Skipping it allows fraudulent payment_id injection. Never fulfill orders without calling verify_payment_signature().
  Fix: Always call client.utility.verify_payment_signature(params) with razorpay_order_id, razorpay_payment_id, razorpay_signature.
• gotcha Test keys (rzp_test_) and live keys (rzp_live_) are different. Test payments don't transfer real money. Accidentally using live keys in development charges real users.
  Fix: Use environment variables: RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET. Verify key starts with 'rzp_test_' in development.
• gotcha Webhook signature uses a separate webhook secret — not the API secret. Using API secret for webhook verification raises SignatureVerificationError.
  Fix: client.utility.verify_webhook_signature(payload, signature, WEBHOOK_SECRET) — get WEBHOOK_SECRET from Razorpay dashboard under Webhooks settings.
• gotcha payment_capture=1 in order.create auto-captures payment. Without it, payment is authorized but not captured — must manually call client.payment.capture(payment_id, amount).
  Fix: Add 'payment_capture': 1 to order creation for automatic capture.
• gotcha SDK method naming: client.payment (singular) not client.payments. client.order (singular) not client.orders. Common LLM error.
  Fix: client.payment.fetch(), client.order.create(), client.refund.fetch(), client.customer.create()
• gotcha Razorpay only supports INR for domestic payments. International currencies require Razorpay's international payment product with separate activation.
  Fix: Use currency='INR' for standard integration. Contact Razorpay for international payment activation.

Install

• pip install razorpay Python

Imports

• Client + order creation

  import razorpay
  
  client = razorpay.Client(auth=('rzp_test_KEY', 'SECRET'))
  
  # Amount MUST be in paise — 500 INR = 50000 paise
  order = client.order.create({
      'amount': 50000,       # 500 INR in paise
      'currency': 'INR',
      'receipt': 'order_rcpt_001',
      'payment_capture': 1   # auto-capture payment
  })
  print(order['id'])  # pass this to frontend

  Amount is always in the smallest currency unit. For INR: paise (1 INR = 100 paise). 500 INR = 50000 paise. Passing rupees directly causes incorrect charges.
• verify_payment_signature

  import razorpay
  
  client = razorpay.Client(auth=('rzp_test_KEY', 'SECRET'))
  
  # After frontend payment — MUST verify signature
  params = {
      'razorpay_order_id': order_id,      # from order creation
      'razorpay_payment_id': payment_id,  # from frontend callback
      'razorpay_signature': signature     # from frontend callback
  }
  
  try:
      client.utility.verify_payment_signature(params)
      # Signature valid — payment confirmed
      print('Payment verified')
  except razorpay.errors.SignatureVerificationError:
      # Signature invalid — do NOT fulfill order
      print('Payment verification failed')

  Signature verification is mandatory. Never fulfill an order based on payment status alone without verifying the HMAC signature. Razorpay raises SignatureVerificationError on failure.

Quickstart

Razorpay Python SDK — order creation, signature verification, and refund.

# pip install razorpay
import razorpay

# Use test keys from dashboard.razorpay.com
client = razorpay.Client(auth=('rzp_test_YOUR_KEY', 'YOUR_SECRET'))
client.enable_retry(True)  # retry on transient failures

# Step 1: Create order server-side
order = client.order.create({
    'amount': 50000,    # 500 INR in paise
    'currency': 'INR',
    'receipt': 'receipt_001',
    'notes': {
        'product': 'Widget',
        'user_id': '123'
    }
})
print('Order ID:', order['id'])
# Pass order['id'], key_id, amount to frontend Razorpay checkout

# Step 2: After frontend payment, verify signature
params = {
    'razorpay_order_id': order['id'],
    'razorpay_payment_id': 'pay_XXXX',   # from frontend
    'razorpay_signature': 'SIG_XXXX'     # from frontend
}
try:
    client.utility.verify_payment_signature(params)
    print('Payment confirmed')
except razorpay.errors.SignatureVerificationError:
    print('Invalid signature — reject payment')

# Fetch payment details
payment = client.payment.fetch('pay_XXXX')
print(payment['status'], payment['amount'])

# Refund
refund = client.payment.refund('pay_XXXX', {'amount': 50000})
print(refund['id'])