# Razorpay Integration via LowCodeAPI

## Overview

Razorpay is a leading payment gateway solution for businesses in India. The Razorpay API provides comprehensive functionality for:

- **Payments** - Process payments, capture transactions, and handle refunds
- **Customers** - Manage customer information and payment methods
- **Orders** - Create and manage payment orders
- **Invoices** - Generate and manage invoices
- **Subscriptions** - Handle recurring payments and plans
- **Settlements** - Track payment settlements
- **Refunds** - Process payment refunds

## Base Endpoint

```
https://api.lowcodeapi.com/razorpay/
```

## Authentication

LowCodeAPI handles authentication automatically using Basic Auth with API Key and Secret. You only need to:

1. **Sign up** at [Razorpay](https://razorpay.com) to get your API Key and Secret
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Razorpay API key and secret
- Apply them to each request using Basic Authentication

**Auth Type**: Basic Auth (API Key + Secret)

## API Categories

- **Payment Processing** - Payment gateway and transaction management

## Common Endpoints

### Category: Customers

#### Create Customer

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customers`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/customers?api_token={api_token}
```

**Description**: Create a new customer in Razorpay.

**Request Body**:
```json
{
  "name": "Gaurav Kumar",
  "email": "[email protected]",
  "contact": "+919876543210",
  "fail_existing": "0",
  "gstin": "29XAbbA4369J1PA",
  "notes": {
    "note_key": "Beam me up Scotty"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Customer's name (3-50 characters, alphanumeric with special characters) |
| `email` | string | No | Customer's email address (max 64 characters) |
| `contact` | string | No | Customer's phone number (max 15 characters with country code) |
| `fail_existing` | string | No | 0: fetch existing if duplicate, 1: throw error if duplicate (default) |
| `gstin` | string | No | Customer's GST number |
| `notes` | object | No | Key-value pairs for additional information (max 15 pairs, 256 chars each) |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/customers?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gaurav Kumar",
    "email": "[email protected]",
    "contact": "+919876543210"
  }'
```

**Official Documentation**: [Create Customer](https://razorpay.com/docs/api/customers)

---

#### Get Customers

**Method**: `GET` | **LowCodeAPI Path**: `/v1/customers`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/customers?api_token={api_token}
```

**Description**: Fetch all customers with pagination support.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | No | Number of customers to retrieve (default: 10) |
| `skip` | integer | No | Number of customers to skip (for pagination) |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/razorpay/v1/customers?count=50&skip=0&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Customers](https://razorpay.com/docs/api/customers)

---

### Category: Orders

#### Create Order

**Method**: `POST` | **LowCodeAPI Path**: `/v1/orders`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/orders?api_token={api_token}
```

**Description**: Create an order for payment processing.

**Request Body**:
```json
{
  "amount": 50000,
  "currency": "INR",
  "receipt": "order_rcptid_11",
  "notes": {
    "key": "value"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | integer | Yes | Amount in currency subunits (e.g., 50000 for INR 500.00) |
| `currency` | string | Yes | Currency code (default: INR) |
| `receipt` | string | No | Receipt number for your internal reference |
| `notes` | object | No | Key-value pairs for additional information |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/orders?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "INR",
    "receipt": "order_rcptid_11"
  }'
```

**Official Documentation**: [Create Order](https://razorpay.com/docs/api/orders)

---

### Category: Payments

#### Capture Payment

**Method**: `POST` | **LowCodeAPI Path**: `/v1/payments/payment_id/capture`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/capture?id={payment_id}&api_token={api_token}
```

**Description**: Capture a payment that was authorized.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Payment ID to capture |

**Request Body**:
```json
{
  "amount": 50000,
  "currency": "INR"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | integer | Yes | Amount to capture in currency subunits |
| `currency` | string | Yes | Currency code |

**Example Request**:
```bash
# Replace PAYMENT_ID with actual payment ID
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/capture?id=PAYMENT_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "INR"
  }'
```

**Official Documentation**: [Capture Payment](https://razorpay.com/docs/api/payments)

---

### Category: Refunds

#### Create Refund

**Method**: `POST` | **LowCodeAPI Path**: `/v1/payments/payment_id/refunds`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/refunds?id={payment_id}&api_token={api_token}
```

**Description**: Create a refund for a payment.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Payment ID to refund |

**Request Body**:
```json
{
  "amount": 50000,
  "notes": {
    "reason": "Product return"
  }
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | integer | No | Amount to refund in currency subunits (default: full refund) |
| `notes` | object | No | Key-value pairs for refund reason |

**Example Request**:
```bash
# Replace PAYMENT_ID with actual payment ID
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/refunds?id=PAYMENT_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "notes": {"reason": "Product return"}
  }'
```

**Official Documentation**: [Create Refund](https://razorpay.com/docs/api/refunds)

---

### Category: Invoices

#### Create Invoice

**Method**: `POST` | **LowCodeAPI Path**: `/v1/invoices`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/invoices?api_token={api_token}
```

**Description**: Create an invoice for a customer.

**Request Body**:
```json
{
  "type": "invoice",
  "customer_id": "cust_E6BSXdAhCWp5PZ",
  "line_items": [
    {
      "name": "Master Cloud Subscription",
      "amount": 10000,
      "currency": "INR",
      "quantity": 1
    }
  ]
}
```

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/invoices?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "customer_id": "cust_E6BSXdAhCWp5PZ",
    "line_items": [{
      "name": "Master Cloud Subscription",
      "amount": 10000,
      "currency": "INR",
      "quantity": 1
    }]
  }'
```

**Official Documentation**: [Create Invoice](https://razorpay.com/docs/api/invoices)

---

### Category: Subscriptions

#### Create Subscription

**Method**: `POST` | **LowCodeAPI Path**: `/v1/subscriptions`

**Full URL**:
```
https://api.lowcodeapi.com/razorpay/v1/subscriptions?api_token={api_token}
```

**Description**: Create a subscription plan for recurring payments.

**Request Body**:
```json
{
  "plan_id": "plan_E7FVLn8g6M1c4p",
  "customer_id": "cust_E6BSXdAhCWp5PZ",
  "total_count": 12,
  "start_at": 1495995837
}
```

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/subscriptions?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_E7FVLn8g6M1c4p",
    "customer_id": "cust_E6BSXdAhCWp5PZ",
    "total_count": 12
  }'
```

**Official Documentation**: [Create Subscription](https://razorpay.com/docs/api/subscriptions)

---

## Usage Examples

### Example 1: Process a Payment

Create order, customer, and process payment:

```bash
# Step 1: Create customer
# No ID needed - creates new customer
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/customers?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gaurav Kumar",
    "email": "[email protected]",
    "contact": "+919876543210"
  }'

# Step 2: Create order
# No ID needed - creates new order
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/orders?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "INR",
    "receipt": "order_rcptid_11"
  }'

# Step 3: Capture payment after authorization
# Replace PAYMENT_ID with actual payment ID
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/capture?id=PAYMENT_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "INR"
  }'
```

### Example 2: Manage Subscriptions

Create subscription plan and subscription:

```bash
# Step 1: Create subscription plan
# No ID needed - creates new plan
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/plans?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "monthly",
    "interval": 1,
    "item": {
      "name": "Pro Plan",
      "amount": 10000,
      "currency": "INR"
    }
  }'

# Step 2: Create subscription
# No ID needed - creates new subscription
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/subscriptions?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_E7FVLn8g6M1c4p",
    "customer_id": "cust_E6BSXdAhCWp5PZ",
    "total_count": 12
  }'
```

### Example 3: Handle Refunds

Process refunds for payments:

```bash
# Step 1: Get all refunds
# No ID needed - lists all refunds
curl -X GET "https://api.lowcodeapi.com/razorpay/v1/refunds?count=50&api_token=YOUR_API_TOKEN"

# Step 2: Create specific refund
# Replace PAYMENT_ID with actual payment ID
curl -X POST "https://api.lowcodeapi.com/razorpay/v1/payments/payment_id/refunds?id=PAYMENT_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "notes": {"reason": "Partial refund"}
  }'
```

## Complete Endpoint Reference

For a complete list of all 178 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/razorpay/definition
- **Official Razorpay Documentation**: https://razorpay.com/docs

## Rate Limits & Best Practices

- **Rate Limit**: Refer to your Razorpay plan for rate limits
- **Best Practices**:
  - Always store Razorpay IDs (customers, orders, payments) for efficient updates
  - Use orders for all payment flows to ensure consistency
  - Implement webhooks to track payment status changes
  - Use customer IDs to track repeat purchases
  - Handle failed payments gracefully with retry logic
  - Keep notes on transactions for audit trails
  - Use appropriate error codes for troubleshooting

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Razorpay
  }
}
```

Common errors:
- **400**: Invalid request parameters
- **401**: Invalid API key or secret
- **404**: Resource not found
- **429**: Rate limit exceeded