Payments

Learn how to create a payment order, process it with the Razorpay SDK, and verify the result using the RideShare payments API.

The RideShare API uses Razorpay to process payments. The flow is a three-step process: you create an order on the server, your client collects payment details using the Razorpay SDK, then you verify the result with the RideShare API.

All amounts are in Indian Rupees (INR). The amountInInr field takes whole-number rupee values (e.g. 185 for ₹185).

Payment flow

1. Create a payment order

   Call POST /payments/order to create a Razorpay order on the server. The server returns an order ID and the metadata your client needs to open the Razorpay payment sheet.

   Request

   POST /payments/order
   Authorization: Bearer <token>
   Content-Type: application/json
   

   {
     "amountInInr": 185,
     "rideSummary": "MG Road → Whitefield",
     "paymentMode": "UPI"
   }
   

   Field	Type	Required	Description
   amountInInr	integer	Yes	Fare amount in INR. Must be greater than zero.
   rideSummary	string	No	Human-readable description shown on the payment sheet.
   paymentMode	string	No	Preferred payment method (e.g. UPI, CARD, NETBANKING, CASH).

   Response

   {
     "orderId": "order_QzXkA1b2C3d4E5",
     "amount": 18500,
     "currency": "INR",
     "sessionId": "sess_abc123xyz",
     "keyId": "rzp_live_xxxxxxxxxx"
   }
   

   Save the orderId and sessionId — you will need both in the next steps.

2. Collect payment with the Razorpay SDK

   Use the orderId, amount, currency, and keyId from the previous response to open the Razorpay checkout on your client. This step happens entirely in your frontend or mobile app using the Razorpay SDK.

   JavaScript (web)

   const options = {
     key: keyId,
     amount: amount,       // in paise (already converted by server)
     currency: "INR",
     order_id: orderId,
     name: "RideShare",
     description: rideSummary,
     handler: function (response) {
       // response.razorpay_order_id
       // response.razorpay_payment_id
       // response.razorpay_signature
       verifyPayment(response);
     }
   };
   const rzp = new Razorpay(options);
   rzp.open();
   

   React Native

   import RazorpayCheckout from 'react-native-razorpay';
   
   RazorpayCheckout.open({
     key: keyId,
     amount: amount,
     currency: 'INR',
     order_id: orderId,
     name: 'RideShare',
     description: rideSummary,
   }).then((data) => {
     verifyPayment(data);
   });
   

   When the user completes payment, Razorpay calls your handler with razorpay_order_id, razorpay_payment_id, and razorpay_signature. Pass all three to the verification step.

3. Verify the payment

   Call POST /payments/verify with the three values returned by the Razorpay SDK. The server verifies the HMAC signature against your Razorpay secret key and confirms the payment is legitimate.

   Always verify the payment signature server-side before marking a ride as paid or releasing any service. A successful payment response from Razorpay on the client alone is not sufficient — the signature check on POST /payments/verify is the authoritative confirmation.

   Request

   POST /payments/verify
   Content-Type: application/json
   

   {
     "orderId": "order_QzXkA1b2C3d4E5",
     "paymentId": "pay_Fg6Hi7Jk8Lm9No",
     "signature": "3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4",
     "paymentMode": "UPI"
   }
   

   Field	Type	Required	Description
   orderId	string	Yes	The Razorpay order ID from POST /payments/order.
   paymentId	string	Yes	The razorpay_payment_id returned by the Razorpay SDK.
   signature	string	Yes	The razorpay_signature returned by the Razorpay SDK.
   paymentMode	string	No	The payment mode used (e.g. UPI, CARD). Used for recordkeeping on the ride.

   Response

   {
     "verified": true,
     "paymentId": "pay_Fg6Hi7Jk8Lm9No",
     "orderId": "order_QzXkA1b2C3d4E5",
     "paymentMode": "UPI"
   }
   

   If the signature is invalid, the server returns 400 Bad Request. Do not mark the ride as paid if you receive an error response.

4. Check session status

   You can check the status of any payment session at any time using GET /payments/session/{sessionId}. Use the sessionId returned by POST /payments/order.

   Request

   GET /payments/session/{sessionId}
   

   Response

   {
     "sessionId": "sess_abc123xyz",
     "orderId": "order_QzXkA1b2C3d4E5",
     "status": "PAID",
     "paymentMode": "UPI",
     "amountInInr": 185
   }
   

   The status field reflects the current state of the payment session. Poll this endpoint if you need to reconcile payment state outside the main verification flow.

The paymentMode field

The paymentMode field appears on both the ride object and on payment requests. It records how the rider chose to pay. You set it when creating the payment order and when verifying. Common values include UPI, CARD, NETBANKING, and CASH.

After a successful payment verification, the paymentMode and paymentReference fields on the ride object are updated automatically:

{
  "id": 101,
  "status": "COMPLETED",
  "paymentMode": "UPI",
  "paymentStatus": "PAID",
  "paymentReference": "pay_Fg6Hi7Jk8Lm9No"
}

The paymentReference field on the ride stores the Razorpay paymentId for audit and dispute purposes.