# Razorpay Agent Skills

Razorpay is an RBI-authorised full-stack payment platform for businesses in India, Malaysia, Singapore, and the USA. The following actions are available for AI agents via the Razorpay API and MCP server.

**MCP Server:** `https://mcp.razorpay.com/mcp`
**API Base URL:** `https://api.razorpay.com/v1`
**Auth:** Basic Auth — `key_id:key_secret` (base64-encoded)
**Docs:** https://razorpay.com/docs/

---

## Payments

| Action | Method | Endpoint | Description |
|--------|--------|----------|-------------|
| Create order | POST | `/orders` | Create a payment order with amount (in paise), currency, and receipt |
| Fetch order | GET | `/orders/{order_id}` | Get order details and status |
| List orders | GET | `/orders` | List orders with optional filters (from, to, count, skip) |
| Create payment link | POST | `/payment_links` | Generate a shareable payment link |
| Update payment link | PATCH | `/payment_links/{payment_link_id}` | Update an existing payment link |
| Cancel payment link | POST | `/payment_links/{payment_link_id}/cancel` | Cancel a payment link |
| Fetch payment | GET | `/payments/{payment_id}` | Get payment status, amount, method |
| Fetch all payments | GET | `/payments` | List payments with optional filters |
| Capture payment | POST | `/payments/{payment_id}/capture` | Manually capture an authorized payment |

## Refunds

| Action | Method | Endpoint | Description |
|--------|--------|----------|-------------|
| Issue refund | POST | `/payments/{payment_id}/refund` | Full or partial refund for a payment |
| Fetch refund | GET | `/refunds/{refund_id}` | Get refund status |
| List refunds | GET | `/payments/{payment_id}/refunds` | All refunds for a payment |

## Invoices

| Action | Method | Endpoint | Description |
|--------|--------|----------|-------------|
| Create invoice | POST | `/invoices` | Create a GST-compliant invoice |
| Send invoice | POST | `/invoices/{invoice_id}/notify` | Send invoice via email/SMS |
| Fetch invoice | GET | `/invoices/{invoice_id}` | Get invoice details |
| Cancel invoice | POST | `/invoices/{invoice_id}/cancel` | Cancel an unpaid invoice |

## Payouts (RazorpayX)

| Action | Method | Endpoint | Description |
|--------|--------|----------|-------------|
| Create payout | POST | `/payouts` | Send money to a bank account or UPI ID |
| Fetch payout | GET | `/payouts/{payout_id}` | Get payout status |
| Cancel payout | POST | `/payouts/{payout_id}/cancel` | Cancel a queued payout |
| Create contact | POST | `/contacts` | Create a contact (vendor/employee/customer) |
| Create fund account | POST | `/fund_accounts` | Link a bank account or UPI to a contact |

## Subscriptions

| Action | Method | Endpoint | Description |
|--------|--------|----------|-------------|
| Create plan | POST | `/plans` | Create a subscription plan |
| Create subscription | POST | `/subscriptions` | Subscribe a customer to a plan |
| Fetch subscription | GET | `/subscriptions/{sub_id}` | Get subscription status |
| Cancel subscription | POST | `/subscriptions/{sub_id}/cancel` | Cancel an active subscription |

## Webhooks

Webhooks are configured in the Razorpay Dashboard (Settings → Webhooks). Verify incoming events using HMAC-SHA256 of the raw request body signed with your webhook secret, compared against the `X-Razorpay-Signature` header.

| Event | Description |
|-------|-------------|
| `payment.authorized` | Payment authorized but not yet captured |
| `payment.captured` | Payment successfully captured |
| `payment.failed` | Payment failed |
| `order.paid` | Order fully paid |
| `refund.created` | Refund initiated |
| `refund.processed` | Refund completed |
| `payout.processed` | Payout sent successfully |
| `payout.failed` | Payout failed |
| `subscription.activated` | Subscription is active |
| `subscription.charged` | Recurring charge collected |
| `subscription.cancelled` | Subscription cancelled |
| `invoice.paid` | Invoice marked as paid |
| `invoice.expired` | Invoice expired without payment |

---

## Authentication for Agents

1. Generate API keys from the Razorpay Dashboard → Settings → API Keys
2. Use Test mode keys (`rzp_test_*`) for sandbox
3. Auth: `Authorization: Basic base64(key_id:key_secret)`
4. Sandbox base URL: `https://api.razorpay.com/v1` (same URL, test keys route to sandbox)

## Supported Currencies

INR (primary), USD, EUR, GBP, SGD, MYR, and 120+ others for international payments.

## Error Codes

All errors return: `{ "error": { "code": "...", "description": "...", "source": "...", "step": "...", "reason": "..." } }`

| HTTP Code | Meaning |
|-----------|---------|
| 400 | Bad request — invalid or missing parameters |
| 401 | Authentication failed — check API keys |
| 404 | Resource not found |
| 429 | Rate limit exceeded — implement exponential backoff |
| 500 | Razorpay server error |

## Rate Limits

Contact Razorpay support for rate limit details. Implement exponential backoff on HTTP 429 responses.