> For the complete documentation index, see [llms.txt](https://docs.moodymusic.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moodymusic.xyz/api-reference/payments.md).

# Payments

Moody Music uses **Razorpay** as its payment processor for premium subscriptions.

## Flow

1. Frontend calls `POST /api/payment/create-order` to create a Razorpay order
2. Razorpay checkout modal opens in the browser
3. User completes payment in the Razorpay UI
4. The frontend handler receives the payment response and calls `POST /api/payment/verify-payment`
5. Backend verifies the HMAC-SHA256 signature, marks the order as paid, and activates premium

## Endpoints

### POST /api/payment/create-order

Creates a new Razorpay order.

**Request Body:**

```json
{
  "amount": 199,
  "discordId": "123456789012345678",
  "planType": "Monthly",
  "category": "USER",
  "guildId": null
}
```

**Parameters:**

| Field       | Required | Description                          |
| ----------- | -------- | ------------------------------------ |
| `amount`    | Yes      | Amount in INR (minimum ₹1)           |
| `discordId` | Yes      | User's Discord ID                    |
| `planType`  | No       | Plan label (Monthly, Yearly, etc.)   |
| `category`  | No       | `USER` or `SERVER` (default: SERVER) |
| `guildId`   | No       | Target guild ID for SERVER category  |

**Response:** Raw Razorpay order object with `id`, `amount`, `currency`, etc.

### POST /api/payment/verify-payment

Verifies a completed Razorpay payment and activates premium.

**Request Body:**

```json
{
  "razorpay_order_id": "order_...",
  "razorpay_payment_id": "pay_...",
  "razorpay_signature": "...",
  "discordId": "123456789012345678"
}
```

**Verification Steps:**

1. HMAC-SHA256 signature comparison
2. Order lookup and status update to `paid`
3. **Database transaction:** Updates user premium, creates/extends ServerPremium or UserPremium record
4. **Redis publish:** Sends `USER_PREMIUM_ADD` or `SERVER_PREMIUM_ADD` event to the bot

**Response:**

```json
{
  "success": true,
  "message": "Premium Activated Successfully!"
}
```

## Plan Durations

| Plan              | Duration    | Slot Count |
| ----------------- | ----------- | ---------- |
| Monthly           | 30 days     | 1          |
| Yearly            | 365 days    | 1          |
| Custom (N Months) | N × 30 days | 1          |