> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://razorpay.com) 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.

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

## Payment flow

<Steps>
  <Step title="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**

    ```http theme={null}
    POST /payments/order
    Authorization: Bearer <token>
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "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**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="JavaScript (web)">
        ```javascript theme={null}
        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();
        ```
      </Tab>

      <Tab title="React Native">
        ```javascript theme={null}
        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);
        });
        ```
      </Tab>
    </Tabs>

    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.
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>

    **Request**

    ```http theme={null}
    POST /payments/verify
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "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**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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**

    ```http theme={null}
    GET /payments/session/{sessionId}
    ```

    **Response**

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## 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:

```json theme={null}
{
  "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.