Overview

The controlRazorpay action opens the Razorpay Checkout modal (web) or the Razorpay SDK's payment screen (Android/iOS) for a pre-created Razorpay order. It handles the entire payment UI and returns the payment result — success with signature credentials, or failure with an error — to your defined callback action chains.

Note: Server-side order creation is required. Razorpay requires that an Order ID be created on your server using the Razorpay Orders API before the checkout is opened. The controlRazorpay action does not create the order — call your order-creation API via a Data Source action first, then pass the returned order_id to this action.

Prerequisites

Warning: Complete these steps before using the action:

Parameters

Payment Flow Architecture

The recommended end-to-end flow:

1. Create order server-side: Fire a Data Source action that calls your backend endpoint (POST /orders). Your server calls the Razorpay Orders API and returns the order_id.

2. Open Razorpay checkout: In the onSuccess of the order creation data source, fire the controlRazorpay action with the returned order_id.

3. Verify payment server-side (onSuccess callback): Pass the three Razorpay signature fields to another Data Source action that calls your backend's verification endpoint. Only fulfil the order after server-side verification passes.

4. Handle failure (onFailure callback): Show an error notification with the failure reason. Optionally offer a retry button that re-opens checkout with the same order ID (Razorpay orders support multiple payment attempts).

Examples

Open Razorpay checkout after order creation

{ "actionType": "controlRazorpay", "payload": { "orderId": "{{ ds_createOrder.response.id }}", "amount": "{{ ds_createOrder.response.amount }}", "currency": "INR", "prefill": { "name": "{{ appUser.name }}", "email": "{{ appUser.email }}", "contact": "{{ appUser.phone }}" }, "theme": { "color": "#1A3C5E" }, "onSuccess": [ { "actionType": "triggerDataSource", "payload": { "dataSourceId": "ds_verifyPayment", "params": { "paymentId": "{{ onSuccess.razorpay_payment_id }}", "orderId": "{{ onSuccess.razorpay_order_id }}", "signature": "{{ onSuccess.razorpay_signature }}" } } }, { "actionType": "showNotification", "payload": { "type": "success", "title": "Payment successful!", "description": "Payment ID: {{ onSuccess.razorpay_payment_id }}" } } ], "onFailure": [ { "actionType": "showNotification", "payload": { "type": "error", "title": "Payment failed", "description": "{{ onFailure.description }}" } } ] } }

Frequently Asked Questions

How do I test Razorpay payments without real money?

Use a Test Mode Key ID (rzp_test_...) in App Settings. In the checkout modal, use Razorpay's test card number 4111 1111 1111 1111 (any future expiry, CVV 111). For UPI, use success@razorpay. Payments made with a test key are not real transactions and do not move money. Switch to a Live Mode Key ID only when deploying to production.

Why must I verify the payment signature server-side?

The razorpay_signature returned in the onSuccess callback is a SHA-256 HMAC of the payment ID and order ID, signed with your Razorpay Key Secret. Client-side verification is impossible and insecure — an attacker could forge a success callback without making a real payment. Always call your backend to verify the signature using your Key Secret before marking the order as paid.

Can the user retry a failed payment?

Yes. A Razorpay order remains active (in created state) after a failed payment attempt. You can reuse the same orderId in another controlRazorpay action call — the user will be taken back to checkout for the same order. Razorpay supports multiple payment attempts per order until the order either succeeds or expires (default: 30 minutes).