Razorpay integration

Overview

Razorpay is India's largest online payments platform. The Automize connector covers orders, payments, refunds, customers, invoices, payment links, subscriptions, and settlements via the Razorpay v1 REST API.

• Regions: Single global API at api.razorpay.com. Razorpay primarily serves India (INR + UPI + RuPay rails) but supports international cards in INR. Razorpay Curlec covers Malaysia on a separate API not included here.
• Plans: All accounts have API access. International payments and Subscriptions are enabled per-account by Razorpay support. Payouts (RazorpayX) is a separate product, not in this connector.

Setting up the connection

Auth type: HTTP Basic.

1. In Razorpay Dashboard → Settings → API Keys, click Generate Test Key (or Generate Live Key for production). Keys are issued in pairs: Key ID (rzp_test_... / rzp_live_...) + Key Secret.
2. Save the secret immediately – it's shown ONCE on creation. Razorpay doesn't store it server-side; lost = regenerate.
3. In Automize, paste Key ID as the username + Key Secret as the password (HTTP Basic auth).
4. Test mode keys hit api.razorpay.com but route to the sandbox. Use Test until your account is activated for live mode by Razorpay's KYC team.

Find your credentials at https://dashboard.razorpay.com/app/keys.

Rate limits

~5000 requests / minute per key on production. No public document for test keys; in practice the same ceiling. 429 includes Retry-After; connector backs off. Webhook deliveries from Razorpay are subject to their own retry policy (3 attempts).

Data model

Razorpay's payment graph:

    Order        → server-side intent (amount + currency + receipt)
      └─ Payment → one or more attempts against the order
           ├─ Refund   → partial or full reversal of a payment
           └─ Dispute  → chargeback raised by the cardholder

    Customer     → optional saved entity (name + email + contact)
      └─ Token   → saved card / UPI / netbanking instrument
      └─ Subscription → recurring plan billing

    Invoice      → standalone hosted invoice (with or without an order)
    Payment Link → shareable hosted-checkout URL
    Settlement   → bank payout aggregating captured payments T+2

Identifiers all use friendly prefixes:

    order_xxxxxxxxxxxx          → orders
    pay_xxxxxxxxxxxx            → payments
    rfnd_xxxxxxxxxxxx           → refunds
    cust_xxxxxxxxxxxx           → customers
    sub_xxxxxxxxxxxx            → subscriptions
    inv_xxxxxxxxxxxx            → invoices
    plink_xxxxxxxxxxxx          → payment links
    setl_xxxxxxxxxxxx           → settlements
    plan_xxxxxxxxxxxx           → plans (used by subscriptions)

All amounts are integers in PAISE (₹1 = 100 paise). Sending decimal
amounts silently rounds – always work in integer paise client-side.
notes (key:value, up to 15 keys, 256 chars each) is your free-form
attribution bag – round-trips through every related entity.

Available operations

25 operations available. Click any row to jump to its detail.

Operations

Cancel Invoice

Cancel an issued invoice

Tips

• POST /v1/invoices/{invoice_id}/cancel – only valid for status='issued' invoices. partially_paid/paid invoices cannot be cancelled – issue a refund instead.

Cancel Payment Link

Cancel a payment link

Tips

• POST /v1/payment_links/{plink_id}/cancel – cancels an unpaid link. Already-paid links can't be cancelled (refund the underlying payment).

Cancel Subscription

Cancel a subscription

Tips

• POST /v1/subscriptions/{sub_id}/cancel – body: cancel_at_cycle_end=0|1. cycle_end=1 lets the current billing period finish; cycle_end=0 stops immediately.
• Cancelled subscriptions can't be reactivated – create a new subscription against the same customer.

Capture Payment

Capture an authorized payment

Tips

• Only needed when authorize-then-capture flow is used. Auto-capture is the default – payments come back already captured.
• amount must equal or be less than the authorised amount. Partial capture is allowed once per payment.

Create Customer

Create a customer record

Tips

• name + (email OR contact) required. Returns customer_id used in tokenisation flows and subscriptions.
• fail_existing=0 returns the existing customer on duplicate (email/contact) instead of 400-ing.

Create Invoice

Create an invoice

Tips

• Invoices can be standalone or tied to an order_id. customer_id + line_items[] + amount (sum of line items in paise).
• expire_by, partial_payment, sms_notify, email_notify controls the hosted invoice page behaviour.
• Returns short_url (rzp.io/i/...) for the hosted invoice.

Create Order

Create a payment order

Tips

• Order is the server-side intent. Always create the order server-side, pass order_id to the client checkout – never trust a client-built amount.
• amount in paise (₹1 = 100). currency='INR' default. receipt is your own reference (60 char max, unique recommended).
• notes (key:value, up to 15 keys) round-trip through to payment / refund – use for invoice IDs, user IDs, etc.

Create Payment Link

Create a standalone payment link

Tips

• Shareable hosted-checkout URL. customer.contact + customer.email + amount + description.
• expire_by (Unix epoch) auto-expires the link. notify={sms,email} triggers Razorpay's SMS+email blast on create.
• Returns short_url (typically rzp.io/i/...) – that's what you share with the payer.

Create Subscription

Create a recurring subscription

Tips

• Subscriptions need a Plan first (Plans API, not in this connector – create via Dashboard or POST /plans). plan_id + total_count (number of billing cycles) + customer_notify.
• Razorpay's recurring works via e-mandate (UPI Autopay, Card-on-File). The customer must complete a mandate-approval step on first charge.

Get Customer

Get a customer

Tips

• GET /v1/customers/{customer_id} – name, email, contact, GST IDs, created_at, notes.
• Doesn't return saved tokens – token listing has its own endpoint not currently in this connector.

Get Invoice

Get an invoice

Tips

• GET /v1/invoices/{invoice_id} – status: draft → issued → partially_paid → paid → expired → cancelled. paid_at unix-stamp when fully settled.

Get Order

Get a single order

Tips

• GET /v1/orders/{order_id} – returns amount, currency, status (created/attempted/paid), receipt, notes, attempts count.
• status='paid' means the order's been fully captured. status='attempted' means at least one payment was tried – could be a failed payment, not necessarily a successful one.

Get Payment

Get a single payment

Tips

• GET /v1/payments/{payment_id} – full payment detail including method (card / netbanking / upi / wallet), status, bank, vpa, card.network.
• error_code + error_description populated when status='failed'. Common error_code: BAD_REQUEST_ERROR, GATEWAY_ERROR, NETWORK_ERROR.

Get Refund

Get a refund

Tips

• GET /v1/refunds/{refund_id} – refund detail. speed_processed shows whether instant or normal rails were used; speed_requested is what you asked for.
• status: pending → processed → (failed). Pending refunds settle T+0 to T+7 depending on speed + payment method.

List Customers

List customers

No input parameters.

Tips

• Plain list – no filter parameters other than count + skip. For email/contact lookup, search by Create Customer with fail_existing=0 (it returns the existing match).

List Invoices

List invoices

No input parameters.

Tips

• Filter by status, customer_id, receipt. payment_id filter shows the single invoice settled by a payment (1:1 relationship).

List Order Payments

List payments associated with an order

Tips

• GET /v1/orders/{order_id}/payments – every payment attempt against the order, including failed ones.
• Use this for reconciliation: total captured = sum of items where status='captured'.

List Orders

List orders

No input parameters.

Tips

• Filter by from/to (Unix seconds, NOT ms), authorized=1, receipt=<your reference>. Default count=10, max 100.
• Orders include nested payment IDs if expand[]=payments is passed.

List Payment Links

List payment links

No input parameters.

Tips

• GET /v1/payment_links – paginated. Filter by status (created|partially_paid|paid|cancelled|expired), customer_id, payment_id.
• Returns short_url, amount, amount_paid, expire_by, notify settings per link. Use this for outstanding-receivables reports.

List Payments

List payments

No input parameters.

Tips

• Same filter shape as List Orders. Returns ALL payments across the account, not just successful – filter by status='captured' for revenue reporting.

List Refunds

List refunds on the account

No input parameters.

Tips

• Account-wide refunds. To list refunds for a specific payment, use GET /v1/payments/{payment_id}/refunds (separate variant, not in this connector – filter the response client-side).

List Settlements

List settlements (payouts to your bank)

No input parameters.

Tips

• Returns settled payouts to your bank account. Razorpay settles T+2 by default for cards, T+1 for UPI. Each settlement record includes the underlying payment IDs.
• Filter by from/to (Unix epoch). count caps at 100; paginate via skip.

List Subscriptions

List subscriptions

No input parameters.

Tips

• Filter by plan_id, customer_id, status (created|authenticated|active|pending|halted|cancelled|completed|expired).
• 'halted' = mandate failure; subscription resumes on retry success.

Refund Payment

Issue a full or partial refund

Tips

• Partial refunds supported: amount in paise; omit for full refund. Razorpay enforces a 7-day window for instant refunds; older payments refund via the slower 'normal' speed (5-7 business days).
• speed='optimum' is the safe default. 'instant' tries the card network's instant rails and falls back to normal silently.

Errors

• BAD_REQUEST_ERROR – Refund amount > captured amount, or refund window exceeded for instant speed.

Update Customer

Update a customer

Tips

• PUT /v1/customers/{customer_id} – replace fields. Only name, email, contact, notes are mutable; contact/email change requires the existing customer to NOT have an active subscription (else 400).

FAQ

Test vs Live – same code path?

Yes. Switch by swapping the key pair (rzp_test_* vs rzp_live_*). Same endpoints, same response shapes. Test mode never moves money but exposes the same webhooks.

Why is my payment 'authorized' but not 'captured'?

Account is set to manual capture. Either flip it in Dashboard → Settings → Payment Capture, or call Capture Payment within 5 days of authorisation (else auto-voids).

International cards – auto-enabled?

No. International payments require activation via Razorpay support after KYC clears. Once enabled, set currency to USD/EUR/etc. on Create Order; Razorpay handles FX to INR on settlement.

Webhook signature verification?

Razorpay signs the body with HMAC-SHA256 using your webhook secret (different from the API secret). Verify X-Razorpay-Signature on every inbound webhook – webhooks without verification are an audit finding.

Settlement timing – variable?

T+2 (cards) / T+1 (UPI) are defaults. International payments settle T+5. Pause-settlement is enabled per-account on request – useful for high-dispute merchants.

Related connectors

• Stripe
• Paypal
• Paystack
• Flutterwave
• Peach-payments