{ "openapi": "3.0.0", "info": { "title": "Razorpay API", "version": "1.0.0", "description": "Razorpay payment gateway APIs for accepting payments, managing orders, processing refunds, payouts, and subscriptions. All amounts are in the smallest currency sub-unit (e.g. paise for INR). Supports 180+ payment methods including UPI, cards, netbanking, wallets, and EMI.", "termsOfService": "https://razorpay.com/terms/", "contact": { "name": "Razorpay Support", "url": "https://razorpay.com/support/", "email": "support@razorpay.com" }, "license": { "name": "Proprietary", "url": "https://razorpay.com/terms/" }, "x-logo": { "url": "https://razorpay.com/favicon.png" }, "x-auth-environments": { "test": { "keyPrefix": "rzp_test_", "description": "Test mode \u2014 keys prefixed rzp_test_. Same API endpoint (https://api.razorpay.com/v1). No real money movement. Use test card numbers from https://razorpay.com/docs/payments/payments/test-card-details/." }, "live": { "keyPrefix": "rzp_live_", "description": "Live mode \u2014 keys prefixed rzp_live_. Real money movement. Requires KYC and business activation on the Razorpay Dashboard." } } }, "externalDocs": { "description": "Razorpay API Documentation", "url": "https://razorpay.com/docs/api/" }, "servers": [ { "url": "https://api.razorpay.com/v1", "description": "Production" } ], "security": [ { "basicAuth": [] }, { "oauth2": [ "read_only" ] } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic authentication using your Razorpay API key pair. Use key_id as the username and key_secret as the password. Encode as Base64(key_id:key_secret). Keys are environment-scoped (Test vs Live). Obtain keys at https://dashboard.razorpay.com/app/keys. Keys are case-sensitive." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.0 via the Razorpay MCP server (mcp.razorpay.com). Supports Authorization Code with PKCE (S256) for user-delegated access and Client Credentials for server-to-server access. Tokens expire in 3600 seconds. Dynamic Client Registration available at the registration endpoint. For integration setup see https://razorpay.com/docs/build/llm-docs/mcp-server/oauth.md.", "flows": { "authorizationCode": { "authorizationUrl": "https://mcp.razorpay.com/authorize", "tokenUrl": "https://mcp.razorpay.com/token", "refreshUrl": "https://mcp.razorpay.com/token", "scopes": { "read_only": "Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)" } }, "clientCredentials": { "tokenUrl": "https://mcp.razorpay.com/token", "scopes": { "read_only": "Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)" } } } } }, "parameters": { "from": { "name": "from", "in": "query", "description": "Unix timestamp (seconds). Fetch records created on or after this time.", "schema": { "type": "integer" } }, "to": { "name": "to", "in": "query", "description": "Unix timestamp (seconds). Fetch records created on or before this time.", "schema": { "type": "integer" } }, "count": { "name": "count", "in": "query", "description": "Number of records to return per call. Maximum 100. Default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, "skip": { "name": "skip", "in": "query", "description": "Number of records to skip. Use with count for pagination. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "schemas": { "Notes": { "type": "object", "description": "Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.", "additionalProperties": { "type": "string" }, "maxProperties": 15 }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code. Examples: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR." }, "description": { "type": "string" }, "source": { "type": "string", "description": "Where the error originated (e.g. business, gateway)." }, "step": { "type": "string" }, "reason": { "type": "string", "description": "Machine-readable reason. Examples: insufficient_funds, invalid_expiry_date, declined_by_bank." }, "metadata": { "type": "object" }, "field": { "type": "string" } } } } }, "Collection": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer", "description": "Number of items in the current page." }, "items": { "type": "array", "items": {} } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique order identifier. Prefix: order_" }, "entity": { "type": "string", "enum": [ "order" ] }, "amount": { "type": "integer", "description": "Order amount in paise. Example: 50000 = \u20b9500." }, "amount_paid": { "type": "integer", "description": "Total amount paid against this order (paise)." }, "amount_due": { "type": "integer", "description": "Remaining unpaid amount (paise)." }, "currency": { "type": "string", "description": "ISO 4217 currency code. Example: INR." }, "receipt": { "type": "string", "description": "Your internal receipt or order reference number." }, "status": { "type": "string", "enum": [ "created", "attempted", "paid" ], "description": "created: awaiting payment. attempted: payment attempted but not captured. paid: fully paid." }, "attempts": { "type": "integer", "description": "Number of payment attempts made." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer", "description": "Unix timestamp of order creation." }, "offer_id": { "type": "string" }, "offers": { "type": "array", "items": { "type": "string" } } } }, "CardDetails": { "type": "object", "properties": { "id": { "type": "string", "description": "Card token identifier (card_*)." }, "entity": { "type": "string" }, "name": { "type": "string", "description": "Cardholder name." }, "last4": { "type": "string", "description": "Last 4 digits of the card number." }, "network": { "type": "string", "description": "Card network. Examples: Visa, MasterCard, RuPay, Amex." }, "type": { "type": "string", "description": "Card type: credit or debit." }, "issuer": { "type": "string", "description": "4-character code of the issuing bank." }, "emi": { "type": "boolean", "description": "Whether EMI is available on this card." }, "sub_type": { "type": "string", "description": "Card sub-type (e.g. consumer, corporate)." } } }, "UpiDetails": { "type": "object", "properties": { "payer_account_type": { "type": "string" }, "vpa": { "type": "string", "description": "Customer UPI VPA (Virtual Payment Address). Example: user@upi." }, "flow": { "type": "string", "description": "UPI flow used: collect, intent, or in_app." } } }, "AcquirerData": { "type": "object", "properties": { "rrn": { "type": "string", "description": "Bank RRN (Retrieval Reference Number)." }, "authentication_reference_number": { "type": "string" }, "bank_transaction_id": { "type": "string" }, "transaction_id": { "type": "string" } } }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment identifier. Prefix: pay_" }, "entity": { "type": "string", "enum": [ "payment" ] }, "amount": { "type": "integer", "description": "Payment amount in paise." }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "authorized", "captured", "refunded", "failed" ], "description": "created: initiated. authorized: bank approved, not yet captured. captured: funds collected. refunded: fully refunded. failed: transaction failed." }, "order_id": { "type": "string", "description": "Associated order ID (order_*)." }, "invoice_id": { "type": "string" }, "international": { "type": "boolean" }, "method": { "type": "string", "enum": [ "card", "netbanking", "wallet", "emi", "upi" ] }, "amount_refunded": { "type": "integer", "description": "Total refunded amount in paise." }, "refund_status": { "type": "string", "enum": [ "null", "partial", "full" ] }, "captured": { "type": "boolean" }, "description": { "type": "string" }, "card_id": { "type": "string" }, "card": { "$ref": "#/components/schemas/CardDetails" }, "bank": { "type": "string", "description": "Bank code for netbanking. Example: HDFC." }, "wallet": { "type": "string", "description": "Wallet name. Examples: paytm, mobikwik." }, "vpa": { "type": "string" }, "upi": { "$ref": "#/components/schemas/UpiDetails" }, "email": { "type": "string" }, "contact": { "type": "string" }, "customer_id": { "type": "string" }, "token_id": { "type": "string" }, "notes": { "$ref": "#/components/schemas/Notes" }, "fee": { "type": "integer", "description": "Razorpay fee charged (paise)." }, "tax": { "type": "integer", "description": "GST on the fee (paise)." }, "error_code": { "type": "string" }, "error_description": { "type": "string" }, "error_source": { "type": "string" }, "error_step": { "type": "string" }, "error_reason": { "type": "string" }, "acquirer_data": { "$ref": "#/components/schemas/AcquirerData" }, "created_at": { "type": "integer" } } }, "DowntimeInstrument": { "type": "object", "properties": { "bank": { "type": "string" }, "network": { "type": "string" }, "issuer": { "type": "string" }, "psp": { "type": "string" }, "vpa_handle": { "type": "string" }, "card_type": { "type": "string" }, "flow": { "type": "string" } } }, "PaymentDowntime": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string", "enum": [ "payment.downtime" ] }, "method": { "type": "string", "enum": [ "card", "netbanking", "upi" ] }, "begin": { "type": "integer" }, "end": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "scheduled", "started", "resolved", "updated" ] }, "scheduled": { "type": "boolean" }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "instrument": { "$ref": "#/components/schemas/DowntimeInstrument" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique refund identifier. Prefix: rfnd_" }, "entity": { "type": "string", "enum": [ "refund" ] }, "amount": { "type": "integer", "description": "Refund amount in paise." }, "currency": { "type": "string" }, "payment_id": { "type": "string", "description": "The original payment ID (pay_*)." }, "notes": { "$ref": "#/components/schemas/Notes" }, "receipt": { "type": "string", "description": "Your internal reference identifier." }, "acquirer_data": { "type": "object", "description": "Bank reference numbers for tracking: RRN (UPI/netbanking), ARN (cards), UTR (NEFT/RTGS).", "properties": { "arn": { "type": "string" }, "rrn": { "type": "string" }, "utr": { "type": "string" } } }, "created_at": { "type": "integer" }, "batch_id": { "type": "string", "description": "Set if refund was part of a batch upload." }, "status": { "type": "string", "enum": [ "pending", "processed", "failed" ], "description": "pending: being processed. processed: credited to customer. failed: refund failed." }, "speed_requested": { "type": "string", "enum": [ "normal", "optimum" ], "description": "normal: 5-7 business days. optimum: instant if available, falls back to normal." }, "speed_processed": { "type": "string", "enum": [ "instant", "normal" ], "description": "Actual processing mode used." } } }, "Settlement": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique settlement identifier. Prefix: setl_" }, "entity": { "type": "string", "enum": [ "settlement" ] }, "amount": { "type": "integer", "description": "Settlement amount in paise." }, "status": { "type": "string", "enum": [ "created", "processed", "failed" ] }, "fees": { "type": "integer", "description": "Processing fees charged (typically 0 for normal settlements)." }, "tax": { "type": "integer", "description": "Tax on fees (paise)." }, "utr": { "type": "string", "description": "Unique Transaction Reference (UTR) number for bank tracking." }, "created_at": { "type": "integer" } } }, "SettlementReconRecord": { "type": "object", "description": "A single transaction line item in the settlement reconciliation report.", "properties": { "entity_id": { "type": "string", "description": "ID of the transaction entity (payment, refund, etc.)." }, "settlement_id": { "type": "string" }, "order_id": { "type": "string" }, "payment_id": { "type": "string" }, "dispute_id": { "type": "string" }, "type": { "type": "string", "enum": [ "payment", "refund", "transfer", "adjustment" ] }, "amount": { "type": "integer" }, "debit": { "type": "integer" }, "credit": { "type": "integer" }, "fee": { "type": "integer" }, "tax": { "type": "integer" }, "currency": { "type": "string" }, "method": { "type": "string" }, "description": { "type": "string" }, "notes": { "type": "string" }, "settled": { "type": "boolean" }, "on_hold": { "type": "boolean" }, "created_at": { "type": "integer" }, "settled_at": { "type": "integer" }, "posted_at": { "type": "integer" }, "card_network": { "type": "string" }, "card_issuer": { "type": "string" }, "card_type": { "type": "string" }, "settlement_utr": { "type": "string" }, "order_receipt": { "type": "string" }, "credit_type": { "type": "string" } } }, "InstantSettlementPayout": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string", "enum": [ "settlement.ondemand_payout" ] }, "initiated_at": { "type": "integer" }, "processed_at": { "type": "integer" }, "reversed_at": { "type": "integer" }, "amount": { "type": "integer" }, "amount_settled": { "type": "integer" }, "fees": { "type": "integer" }, "tax": { "type": "integer" }, "utr": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "initiated", "processed", "reversed" ] }, "created_at": { "type": "integer" } } }, "InstantSettlement": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique instant settlement identifier. Prefix: setlod_" }, "entity": { "type": "string", "enum": [ "settlement.ondemand" ] }, "amount_requested": { "type": "integer", "description": "Settlement amount requested (paise)." }, "amount_settled": { "type": "integer", "description": "Total amount transferred minus fees and tax (paise)." }, "amount_pending": { "type": "integer", "description": "Portion of requested amount yet to be settled (paise)." }, "amount_reversed": { "type": "integer", "description": "Amount returned to PG balance (paise)." }, "fees": { "type": "integer", "description": "Combined fees and tax deducted (paise)." }, "tax": { "type": "integer", "description": "Tax on fee component (paise)." }, "currency": { "type": "string" }, "settle_full_balance": { "type": "boolean", "description": "If true, settles maximum available balance." }, "status": { "type": "string", "enum": [ "created", "initiated", "partially_processed", "processed", "reversed" ] }, "description": { "type": "string", "description": "Custom reference note. Max 30 alphanumeric characters." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" }, "ondemand_payouts": { "type": "object", "description": "Collection of individual payout records for this instant settlement.", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstantSettlementPayout" } } } } } }, "DisputeEvidence": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Contested amount in currency subunits." }, "summary": { "type": "string", "description": "Your explanation of why the dispute should be resolved in your favour. Max 1000 characters." }, "shipping_proof": { "type": "array", "items": { "type": "string" }, "description": "Document IDs proving product shipment." }, "billing_proof": { "type": "array", "items": { "type": "string" }, "description": "Order confirmation document IDs." }, "cancellation_proof": { "type": "array", "items": { "type": "string" } }, "customer_communication": { "type": "array", "items": { "type": "string" } }, "proof_of_service": { "type": "array", "items": { "type": "string" } }, "explanation_letter": { "type": "array", "items": { "type": "string" } }, "refund_confirmation": { "type": "array", "items": { "type": "string" } }, "access_activity_log": { "type": "array", "items": { "type": "string" } }, "refund_cancellation_policy": { "type": "array", "items": { "type": "string" } }, "term_and_conditions": { "type": "array", "items": { "type": "string" } }, "others": { "type": "array", "items": { "type": "object" } }, "submitted_at": { "type": [ "integer", "null" ], "description": "Unix timestamp of last evidence submission. Null for drafts." } } }, "Dispute": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique dispute identifier. Prefix: disp_" }, "entity": { "type": "string", "enum": [ "dispute" ] }, "payment_id": { "type": "string", "description": "The payment against which the dispute was raised (pay_*)." }, "amount": { "type": "integer", "description": "Disputed amount in currency subunits." }, "currency": { "type": "string" }, "amount_deducted": { "type": "integer", "description": "Amount deducted from your balance when dispute is lost." }, "reason_code": { "type": "string", "description": "Code identifying the dispute reason." }, "reason_description": { "type": "string", "description": "Human-readable explanation of the dispute cause." }, "respond_by": { "type": "integer", "description": "Unix timestamp by which you must respond. Missing this forfeits the dispute." }, "status": { "type": "string", "enum": [ "open", "under_review", "won", "lost", "closed" ], "description": "open: action required. under_review: evidence submitted, awaiting bank decision. won: resolved in your favour. lost: resolved against you. closed: resolved without chargeback." }, "phase": { "type": "string", "enum": [ "fraud", "retrieval", "chargeback", "pre_arbitration", "arbitration" ], "description": "Escalation stage of the dispute process." }, "created_at": { "type": "integer" }, "evidence": { "$ref": "#/components/schemas/DisputeEvidence" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique customer identifier. Prefix: cust_" }, "entity": { "type": "string", "enum": [ "customer" ] }, "name": { "type": "string", "description": "Customer name. 3-50 characters. Allowed: alphanumeric, period, apostrophe, forward slash, @, parentheses." }, "contact": { "type": "string", "description": "Phone number. Max 15 characters. Include country code (e.g. +919876543210). Minimum 8 digits." }, "email": { "type": "string", "description": "Email address. Max 64 characters." }, "gstin": { "type": "string", "description": "Goods and Services Tax Identification Number (optional)." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer", "description": "Unix timestamp of customer creation." } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique document identifier. Example: doc_EsyWjHrfzb59Re. Always 14 alphanumeric characters." }, "entity": { "type": "string", "enum": [ "document" ] }, "name": { "type": "string", "description": "Filename of the uploaded document." }, "mime_type": { "type": "string", "enum": [ "image/jpg", "image/jpeg", "image/png", "application/pdf" ], "description": "MIME type of the uploaded file." }, "size": { "type": "integer", "description": "File size in bytes." }, "purpose": { "type": "string", "description": "Upload reason. Example: dispute_evidence." }, "created_at": { "type": "integer", "description": "Unix timestamp of upload." } } }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment link identifier. Prefix: plink_" }, "entity": { "type": "string", "enum": [ "payment_link" ] }, "amount": { "type": "integer", "description": "Payment amount in smallest currency unit (paise for INR). Three-decimal currencies (KWD, BHD, OMR): drop last decimal digit (e.g. 295.991 KWD \u2192 295990). Zero-decimal currencies (JPY): pass value as-is." }, "amount_paid": { "type": "integer", "description": "Total amount paid by customer." }, "currency": { "type": "string", "default": "INR", "description": "ISO 4217 currency code. UPI Payment Links only support INR." }, "accept_partial": { "type": "boolean", "description": "Allow partial payments. Not supported for UPI links." }, "first_min_partial_amount": { "type": "integer", "description": "Minimum amount required for the first partial payment." }, "description": { "type": "string", "description": "Brief description. Max 2048 characters." }, "reference_id": { "type": "string", "description": "Your unique tracking reference. Max 40 characters. Must be unique per link." }, "expire_by": { "type": "integer", "description": "Unix timestamp when link expires. Default: 6 months from creation. Must be at least 15 minutes in the future." }, "expired_at": { "type": "integer", "description": "Unix timestamp when link actually expired." }, "cancelled_at": { "type": "integer", "description": "Unix timestamp when link was cancelled." }, "status": { "type": "string", "enum": [ "created", "partially_paid", "expired", "cancelled", "paid" ], "description": "created: awaiting payment. partially_paid: one or more partial payments received. expired: past expiry with no full payment. cancelled: manually cancelled. paid: fully paid." }, "upi_link": { "type": "boolean", "description": "true if this is a UPI Payment Link, false for standard." }, "short_url": { "type": "string", "description": "Shareable short URL for the payment link." }, "callback_url": { "type": "string", "description": "Redirect URL after payment completion." }, "callback_method": { "type": "string", "enum": [ "get" ] }, "customer": { "type": "object", "description": "Customer contact details. These are not auto-populated on the checkout page \u2014 customer must enter them manually.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } }, "notify": { "type": "object", "properties": { "sms": { "type": "boolean", "description": "true: Razorpay sends SMS notification. false: merchant handles." }, "email": { "type": "boolean", "description": "true: Razorpay sends email notification. false: merchant handles." } } }, "reminder_enable": { "type": "boolean", "description": "Send automatic payment reminders." }, "payments": { "type": "array", "description": "Captured payment records. Populated only after successful payment capture.", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "payment_id": { "type": "string" }, "plink_id": { "type": "string" }, "method": { "type": "string", "enum": [ "netbanking", "card", "wallet", "upi", "emi", "bank_transfer" ] }, "status": { "type": "string", "enum": [ "captured" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "notes": { "$ref": "#/components/schemas/Notes" }, "order_id": { "type": "string" }, "user_id": { "type": "string", "description": "Identifier for the user role that created the link." }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "QrCode": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique QR code identifier. Prefix: qr_" }, "entity": { "type": "string", "enum": [ "qr_code" ] }, "name": { "type": "string", "description": "Label for the QR code." }, "description": { "type": "string" }, "image_url": { "type": "string", "description": "Hosted URL of the QR code image." }, "payment_amount": { "type": "integer", "description": "Fixed payment amount in paise. Null for variable-amount QR codes." }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "usage_type": { "type": "string", "enum": [ "single_use", "multiple_use" ] }, "close_by": { "type": "integer", "description": "Unix timestamp when the QR code will auto-close." }, "closed_at": { "type": "integer", "description": "Unix timestamp when the QR code was closed." }, "close_reason": { "type": "string", "enum": [ "on_demand", "paid" ], "description": "Why the QR code was closed." }, "customer_id": { "type": "string", "description": "Associated customer ID (cust_*)." }, "payments_amount_received": { "type": "integer", "description": "Total amount received via this QR code (paise)." }, "payments_count_received": { "type": "integer", "description": "Number of payments received." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" } } }, "Item": { "type": "object", "description": "A reusable catalog item used in invoice line items.", "properties": { "id": { "type": "string", "description": "Item ID. Prefix: item_" }, "entity": { "type": "string", "enum": [ "item" ] }, "active": { "type": "boolean", "description": "Whether the item is active and available for use in new invoices." }, "amount": { "type": "integer", "description": "Item price in paise (smallest INR unit)." }, "unit_amount": { "type": "integer", "description": "Per-unit price in paise." }, "currency": { "type": "string", "default": "INR" }, "name": { "type": "string", "description": "Display name of the item." }, "description": { "type": "string" }, "created_at": { "type": "integer" } } }, "InvoiceLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Line item ID. Prefix: li_" }, "item_id": { "type": "string", "description": "Referenced catalog item ID (item_*). Null for ad-hoc line items." }, "name": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "integer", "description": "Total line amount in paise (unit_amount \u00d7 quantity)." }, "unit_amount": { "type": "integer", "description": "Per-unit price in paise." }, "quantity": { "type": "integer", "default": 1 }, "currency": { "type": "string", "default": "INR" }, "type": { "type": "string", "enum": [ "invoice", "payment_page" ] } } }, "Invoice": { "type": "object", "description": "An invoice or payment page sent to a customer for payment. Cannot be used to create GST invoices (those must be created via the Dashboard).", "properties": { "id": { "type": "string", "description": "Invoice ID. Prefix: inv_" }, "entity": { "type": "string", "enum": [ "invoice" ] }, "type": { "type": "string", "enum": [ "invoice", "link" ], "description": "invoice: a formal invoice document. link: a payment page / payment link." }, "status": { "type": "string", "enum": [ "draft", "issued", "partially_paid", "paid", "cancelled", "expired", "deleted" ], "description": "Invoice lifecycle status. draft\u2192issued\u2192paid/partially_paid/cancelled/expired." }, "invoice_number": { "type": "string", "description": "Auto-generated invoice number (e.g. INV-001)." }, "customer_id": { "type": "string", "description": "Customer ID (cust_*)." }, "customer": { "type": "object", "description": "Inline customer details snapshot at time of invoice creation." }, "order_id": { "type": "string", "description": "Associated order ID (order_*)." }, "line_items": { "type": "array", "maxItems": 50, "description": "Up to 50 line items.", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "payment_id": { "type": "string", "description": "Payment ID (pay_*) of the successful payment, if paid." }, "currency": { "type": "string", "default": "INR" }, "gross_amount": { "type": "integer", "description": "Sum of all line item amounts before tax (paise)." }, "tax_amount": { "type": "integer", "description": "Total tax amount (paise)." }, "taxable_amount": { "type": "integer", "description": "Taxable base amount (paise)." }, "amount": { "type": "integer", "description": "Total invoice amount including tax (paise)." }, "amount_paid": { "type": "integer", "description": "Amount received so far (paise). Relevant for partial_payment invoices." }, "amount_due": { "type": "integer", "description": "Remaining amount due (paise)." }, "short_url": { "type": "string", "description": "Hosted payment page URL to send to the customer." }, "partial_payment": { "type": "boolean", "description": "If true, customer can pay any amount \u2265 first_payment_min_amount." }, "first_payment_min_amount": { "type": "integer", "description": "Minimum amount for the first partial payment (paise). Required when partial_payment=true." }, "receipt": { "type": "string", "description": "Your internal reference number." }, "description": { "type": "string" }, "comment": { "type": "string", "description": "Internal comment (not shown on invoice)." }, "terms": { "type": "string", "description": "Payment terms shown on the invoice." }, "notes": { "$ref": "#/components/schemas/Notes" }, "expire_by": { "type": "integer", "description": "Unix timestamp after which the invoice expires and cannot be paid." }, "issued_at": { "type": "integer" }, "paid_at": { "type": "integer" }, "cancelled_at": { "type": "integer" }, "expired_at": { "type": "integer" }, "created_at": { "type": "integer" } } }, "Plan": { "type": "object", "description": "A billing plan defining the recurring charge amount and frequency. Reusable across multiple subscriptions.", "properties": { "id": { "type": "string", "description": "Plan ID. Prefix: plan_" }, "entity": { "type": "string", "enum": [ "plan" ] }, "interval": { "type": "integer", "description": "Number of periods between charges. For daily period, minimum interval is 7." }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "yearly" ], "description": "Billing frequency unit. daily requires interval \u2265 7." }, "item": { "$ref": "#/components/schemas/Item", "description": "The item (price, currency, name) billed each cycle." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" } } }, "Subscription": { "type": "object", "description": "A recurring billing subscription linking a customer to a plan. Requires customer mandate authorization via short_url before charges can be collected.", "properties": { "id": { "type": "string", "description": "Subscription ID. Prefix: sub_" }, "entity": { "type": "string", "enum": [ "subscription" ] }, "plan_id": { "type": "string", "description": "Associated plan ID (plan_*)." }, "status": { "type": "string", "enum": [ "created", "authenticated", "active", "pending", "halted", "cancelled", "completed", "expired", "paused" ], "description": "Subscription lifecycle status. created\u2192authenticated (mandate authorized)\u2192active\u2192completed/cancelled/expired. pending=charge retry scheduled; halted=multiple failures; paused=temporarily stopped." }, "current_start": { "type": "integer", "description": "Unix timestamp of current billing cycle start." }, "current_end": { "type": "integer", "description": "Unix timestamp of current billing cycle end." }, "ended_at": { "type": "integer", "description": "Unix timestamp when subscription ended (cancelled/completed/expired)." }, "quantity": { "type": "integer", "default": 1, "description": "Number of plan units billed per cycle." }, "notes": { "$ref": "#/components/schemas/Notes" }, "charge_at": { "type": "integer", "description": "Unix timestamp of next scheduled charge attempt." }, "start_at": { "type": "integer", "description": "Unix timestamp of first charge. Defaults to subscription creation time." }, "end_at": { "type": "integer", "description": "Unix timestamp after which no more charges will be attempted." }, "auth_attempts": { "type": "integer", "description": "Number of mandate authorization attempts." }, "total_count": { "type": "integer", "description": "Total billing cycles. 0 = indefinite." }, "paid_count": { "type": "integer", "description": "Number of billing cycles successfully charged." }, "remaining_count": { "type": "integer", "description": "Remaining billing cycles." }, "customer_notify": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = Razorpay sends SMS/email notifications to customer on each charge." }, "short_url": { "type": "string", "description": "Mandate authorization URL. Must be sent to the customer to activate the subscription." }, "has_scheduled_changes": { "type": "boolean", "description": "True if a plan/quantity change is scheduled for the next cycle." }, "change_scheduled_at": { "type": "string", "enum": [ "now", "cycle_end" ], "description": "When scheduled changes take effect." }, "source": { "type": "string", "description": "Source that created the subscription (e.g., api, dashboard)." }, "offer_id": { "type": "string", "description": "Offer/coupon applied to the subscription." }, "expire_by": { "type": "integer", "description": "Unix timestamp by which the customer must authorize the mandate." }, "created_at": { "type": "integer" } } }, "LinkedAccount": { "type": "object", "description": "A sub-merchant (Linked Account) created under a Route marketplace account. Linked Accounts can receive transfers and settlements. Prefix: acc_", "properties": { "id": { "type": "string", "description": "Account ID. Prefix: acc_" }, "type": { "type": "string", "enum": [ "route" ], "description": "Account type. Always 'route' for Route marketplace accounts." }, "status": { "type": "string", "enum": [ "created", "suspended" ], "description": "Account status." }, "email": { "type": "string", "description": "Contact email. Cannot be updated after creation." }, "phone": { "type": "string", "description": "Contact phone number with country code (e.g., +919876543210)." }, "legal_business_name": { "type": "string", "description": "Registered legal name of the business." }, "business_type": { "type": "string", "enum": [ "route" ], "description": "Business type. Cannot be updated after creation." }, "profile": { "type": "object", "properties": { "category": { "type": "string", "description": "Business category (e.g., healthcare, education, ecommerce)." }, "subcategory": { "type": "string", "description": "Business subcategory." }, "addresses": { "type": "object", "properties": { "registered": { "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "operation": { "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } } } } } }, "legal_info": { "type": "object", "properties": { "pan": { "type": "string", "description": "Business PAN number." }, "gst": { "type": "string", "description": "GST number (22 chars)." } } }, "contact_name": { "type": "string", "description": "Name of the primary contact person." }, "contact_info": { "type": "object", "properties": { "chargeback": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" }, "policy_url": { "type": "string" } } }, "refund": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" }, "policy_url": { "type": "string" } } }, "support": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" }, "policy_url": { "type": "string" } } } } }, "apps": { "type": "object", "properties": { "websites": { "type": "array", "items": { "type": "string" } }, "android": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } }, "ios": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } } } }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" } } }, "Stakeholder": { "type": "object", "description": "A business owner or director associated with a Linked Account. Only one stakeholder is allowed per Route Linked Account. Prefix: sth_", "properties": { "id": { "type": "string", "description": "Stakeholder ID. Prefix: sth_" }, "entity": { "type": "string", "enum": [ "stakeholder" ] }, "name": { "type": "string", "description": "Full name of the stakeholder." }, "email": { "type": "string", "description": "Email address." }, "percentage_ownership": { "type": "number", "description": "Ownership percentage (0-100)." }, "relationship": { "type": "object", "properties": { "director": { "type": "boolean", "description": "True if the stakeholder is a company director." }, "executive": { "type": "boolean", "description": "True if the stakeholder is an executive." } } }, "phone": { "type": "object", "properties": { "primary": { "type": "object", "properties": { "number": { "type": "string" }, "country_code": { "type": "string" } } }, "secondary": { "type": "object", "properties": { "number": { "type": "string" }, "country_code": { "type": "string" } } } } }, "addresses": { "type": "object", "properties": { "residential": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } } } }, "kyc": { "type": "object", "properties": { "pan": { "type": "string", "description": "Individual PAN. 4th character must be 'P'." } } }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" } } }, "ProductConfiguration": { "type": "object", "description": "Route product configuration for a Linked Account. Controls settlement account details and tracks activation status. Prefix: acc_prd_", "properties": { "id": { "type": "string", "description": "Product configuration ID. Prefix: acc_prd_" }, "account_id": { "type": "string", "description": "Linked Account ID this configuration belongs to." }, "product_name": { "type": "string", "enum": [ "route" ], "description": "Product name. Always 'route' for Route product." }, "activation_status": { "type": "string", "enum": [ "requested", "needs_clarification", "under_review", "activated", "suspended" ], "description": "Current activation status. Progresses from requested \u2192 under_review \u2192 activated. needs_clarification requires additional info from the merchant." }, "tnc": { "type": "object", "properties": { "id": { "type": "string" }, "accepted": { "type": "boolean" }, "accepted_at": { "type": "integer", "description": "Unix timestamp when TnC was accepted." } } }, "requested_configuration": { "type": "object", "description": "Configuration details provided during activation request." }, "active_configuration": { "type": "object", "properties": { "settlements": { "type": "object", "properties": { "account_number": { "type": "string", "description": "Bank account number for settlements." }, "ifsc_code": { "type": "string", "description": "IFSC code of the settlement bank." }, "beneficiary_name": { "type": "string", "description": "Account holder name." } } } } }, "requirements": { "type": "array", "description": "List of pending requirements needed for activation.", "items": { "type": "object", "properties": { "field_reference": { "type": "string" }, "resolution_url": { "type": "string" }, "status": { "type": "string" }, "reason_code": { "type": "string" } } } }, "requested_at": { "type": "integer", "description": "Unix timestamp when product was requested." } } }, "Transfer": { "type": "object", "description": "A fund transfer from a merchant or captured payment to a Linked Account (Route). Minimum amount is \u20b9100 (10000 paise). INR only. Prefix: trf_", "properties": { "id": { "type": "string", "description": "Transfer ID. Prefix: trf_" }, "entity": { "type": "string", "enum": [ "transfer" ] }, "source": { "type": "string", "description": "Source entity ID (payment ID, order ID, or merchant account ID for direct transfers)." }, "recipient": { "type": "string", "description": "Destination Linked Account ID (acc_*)." }, "amount": { "type": "integer", "description": "Transfer amount in paise. Minimum 10000 (\u20b9100)." }, "currency": { "type": "string", "enum": [ "INR" ], "description": "Always INR for transfers." }, "amount_reversed": { "type": "integer", "description": "Total amount reversed so far in paise." }, "fees": { "type": "integer", "description": "Transfer fee charged in paise." }, "tax": { "type": "integer", "description": "GST on transfer fee in paise." }, "transfer_status": { "type": "string", "enum": [ "created", "pending", "processed", "failed", "reversed", "partially_reversed" ], "description": "Transfer processing status." }, "settlement_status": { "type": "string", "enum": [ "pending", "on_hold", "settled" ], "description": "Settlement status of the transferred funds in the Linked Account." }, "on_hold": { "type": "boolean", "description": "If true, settlement of this transfer is on hold." }, "on_hold_until": { "type": "integer", "description": "Unix timestamp until which settlement is on hold. null means indefinite hold." }, "recipient_settlement_id": { "type": "string", "description": "Settlement ID (setl_*) in the Linked Account once settled." }, "notes": { "$ref": "#/components/schemas/Notes" }, "linked_account_notes": { "type": "array", "items": { "type": "string" }, "description": "Keys from notes that will be visible to the Linked Account in their dashboard." }, "created_at": { "type": "integer" }, "processed_at": { "type": "integer", "description": "Unix timestamp when the transfer was processed." } } }, "Reversal": { "type": "object", "description": "A reversal of a transfer \u2014 moves funds back from the Linked Account to the merchant. Partial reversals are supported and multiple reversals per transfer are allowed. Prefix: rvrsl_", "properties": { "id": { "type": "string", "description": "Reversal ID. Prefix: rvrsl_" }, "entity": { "type": "string", "enum": [ "reversal" ] }, "transfer_id": { "type": "string", "description": "Transfer ID being reversed (trf_*)." }, "amount": { "type": "integer", "description": "Reversed amount in paise." }, "currency": { "type": "string", "enum": [ "INR" ] }, "notes": { "$ref": "#/components/schemas/Notes" }, "initiator_id": { "type": "string", "description": "ID of the entity that initiated the reversal." }, "created_at": { "type": "integer" } } }, "VirtualAccount": { "type": "object", "description": "A virtual bank account or VPA that accepts NEFT/RTGS/IMPS/UPI payments (Smart Collect). Each payment creates a BankTransfer entity. Auto-closes after 90 days of inactivity. Prefix: va_", "properties": { "id": { "type": "string", "description": "Virtual account ID. Prefix: va_" }, "name": { "type": "string", "description": "Display name of the virtual account." }, "entity": { "type": "string", "enum": [ "virtual_account" ] }, "description": { "type": "string", "description": "Purpose or description of the virtual account." }, "amount_expected": { "type": "integer", "description": "Expected payment amount in paise. 0 means any amount is accepted." }, "amount_paid": { "type": "integer", "description": "Total amount received so far in paise." }, "status": { "type": "string", "enum": [ "active", "closed" ], "description": "active = accepting payments; closed = no longer accepting payments." }, "receivers": { "type": "array", "description": "Payment receivers assigned to this virtual account. Can include bank_account (ba_*) and/or vpa (vpa_*) receivers.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Receiver ID. Prefix: ba_ for bank account, vpa_ for VPA." }, "entity": { "type": "string", "enum": [ "bank_account", "vpa" ] }, "ifsc": { "type": "string", "description": "IFSC code (bank accounts only)." }, "bank_name": { "type": "string", "description": "Bank name (bank accounts only)." }, "name": { "type": "string", "description": "Account holder name (bank accounts) or VPA address (VPAs)." }, "notes": { "$ref": "#/components/schemas/Notes" }, "account_number": { "type": "string", "description": "Virtual account number (bank accounts only)." }, "username": { "type": "string", "description": "UPI username part of the VPA (VPAs only)." }, "handle": { "type": "string", "description": "UPI handle (e.g., razorpay) (VPAs only)." }, "flow": { "type": "string", "enum": [ "upi_qr" ], "description": "Flow type for VPA receivers." } } } }, "close_by": { "type": "integer", "description": "Unix timestamp by which the account will auto-close. Maximum value: 2147483647." }, "closed_at": { "type": "integer", "description": "Unix timestamp when the account was closed." }, "customer_id": { "type": "string", "description": "Customer ID linked to this virtual account (cust_*)." }, "notes": { "$ref": "#/components/schemas/Notes" }, "created_at": { "type": "integer" } } }, "BankTransfer": { "type": "object", "description": "A payment received into a Virtual Account via bank transfer (NEFT/RTGS/IMPS/UPI). Created automatically when a payer sends funds to the virtual account. Prefix: bt_", "properties": { "id": { "type": "string", "description": "Bank transfer ID. Prefix: bt_" }, "entity": { "type": "string", "enum": [ "bank_transfer" ] }, "payment_id": { "type": "string", "description": "Razorpay payment ID generated for this bank transfer (pay_*)." }, "mode": { "type": "string", "enum": [ "NEFT", "RTGS", "IMPS", "UPI" ], "description": "Transfer mode used by the payer." }, "amount": { "type": "integer", "description": "Amount received in paise." }, "payer_bank_account": { "type": "object", "description": "Payer's bank account details.", "properties": { "id": { "type": "string" }, "entity": { "type": "string", "enum": [ "bank_account" ] }, "ifsc": { "type": "string" }, "bank_name": { "type": "string" }, "name": { "type": "string", "description": "Account holder name." }, "notes": { "$ref": "#/components/schemas/Notes" }, "account_number": { "type": "string" } } }, "bank_reference": { "type": "string", "description": "UTR (Unique Transaction Reference) number from the bank." }, "virtual_account_id": { "type": "string", "description": "Virtual account that received this transfer (va_*)." }, "virtual_account": { "$ref": "#/components/schemas/VirtualAccount" } } }, "Bill": { "type": "object", "description": "A Razorpay Billme digital receipt/bill. Used for retail, food & beverage, events, ecommerce, and other use cases.", "properties": { "id": { "type": "string", "description": "Bill ID with prefix bill_" }, "business_type": { "type": "string", "enum": [ "ecommerce", "retail", "food_and_beverage", "events" ] }, "business_category": { "type": "string" }, "customer": { "type": "object", "properties": { "contact": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "customer_id": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object" } } } }, "employee": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "loyalty": { "type": "object", "properties": { "points": { "type": "integer" }, "redeemed_points": { "type": "integer" } } }, "store_code": { "type": "string" }, "receipt_timestamp": { "type": "integer", "description": "Unix timestamp of the transaction" }, "receipt_number": { "type": "string" }, "receipt_type": { "type": "string", "enum": [ "tax_invoice", "sales_invoice", "bill_of_supply", "credit_note", "debit_note" ] }, "receipt_delivery": { "type": "string", "enum": [ "digital", "print", "digital_and_print" ] }, "tags": { "type": "object" }, "bar_code_number": { "type": "string" }, "qr_code_number": { "type": "string" }, "billing_pos_number": { "type": "string" }, "pos_category": { "type": "string" }, "order_number": { "type": "string" }, "order_service_type": { "type": "string", "enum": [ "dine_in", "takeaway", "delivery" ] }, "delivery_status_url": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "unit_amount": { "type": "integer" }, "unit": { "type": "string" }, "hsn_code": { "type": "string" }, "product_code": { "type": "string" }, "total_amount": { "type": "integer" }, "taxes": { "type": "array", "items": { "type": "object" } }, "sub_items": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "object" } } } }, "receipt_summary": { "type": "object", "properties": { "total_quantity": { "type": "number" }, "sub_total_amount": { "type": "integer" }, "currency": { "type": "string" }, "net_payable_amount": { "type": "integer" }, "payment_status": { "type": "string" }, "discounts": { "type": "array", "items": { "type": "object" } }, "taxes": { "type": "array", "items": { "type": "object" } } } }, "taxes": { "type": "array", "items": { "type": "object" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "integer" }, "payment_reference_id": { "type": "string" }, "financier_data": { "type": "object" } } } }, "event": { "type": "object", "description": "Event details for events business type" }, "irn": { "type": "string", "description": "Invoice Reference Number for GST e-invoicing" }, "receipt_url": { "type": "string" }, "created_at": { "type": "integer" } } }, "PartnerAccount": { "type": "object", "description": "A sub-merchant account created by a Partner (Aggregator/Platform) via the Partners API. Uses OAuth access_token authentication. Type=standard for Partners vs type=route for Route API.", "properties": { "id": { "type": "string", "description": "Account ID with prefix acc_" }, "type": { "type": "string", "enum": [ "standard", "route" ] }, "status": { "type": "string", "enum": [ "created", "activated", "needs_clarification", "under_review", "suspended", "rejected" ] }, "email": { "type": "string" }, "phone": { "type": "string" }, "legal_business_name": { "type": "string" }, "customer_facing_business_name": { "type": "string" }, "business_type": { "type": "string" }, "reference_id": { "type": "string", "description": "Partner's internal reference for this merchant" }, "profile": { "type": "object", "properties": { "category": { "type": "string" }, "subcategory": { "type": "string" }, "business_model": { "type": "string" }, "addresses": { "type": "object", "properties": { "registered": { "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } } } } } }, "legal_info": { "type": "object", "properties": { "pan": { "type": "string" }, "gst": { "type": "string" }, "cin": { "type": "string" } } }, "brand": { "type": "object", "properties": { "color": { "type": "string" } } }, "contact_name": { "type": "string" }, "contact_info": { "type": "object", "properties": { "chargeback": { "type": "object", "properties": { "email": { "type": "string" } } }, "refund": { "type": "object", "properties": { "email": { "type": "string" } } }, "support": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" }, "policy_url": { "type": "string" } } } } }, "apps": { "type": "object" }, "notes": { "type": "object" }, "activated_at": { "type": "integer" }, "live": { "type": "boolean" }, "hold_funds": { "type": "boolean" }, "suspended_at": { "type": "integer" }, "created_at": { "type": "integer" } } }, "PartnerProductConfiguration": { "type": "object", "description": "Product configuration for a sub-merchant account. Partners configure payment_gateway or payment_links; Route API uses 'route'. One payment method can be updated per PATCH request.", "properties": { "id": { "type": "string", "description": "Product config ID with prefix acc_prd_" }, "account_id": { "type": "string" }, "product_name": { "type": "string", "enum": [ "payment_gateway", "payment_links", "route" ] }, "activation_status": { "type": "string", "enum": [ "under_review", "needs_clarification", "activated", "rejected", "suspended" ] }, "tnc": { "type": "object", "properties": { "id": { "type": "string" }, "accepted": { "type": "boolean" }, "accepted_at": { "type": "integer" } } }, "requested_configuration": { "type": "object" }, "active_configuration": { "type": "object", "properties": { "payment_capture": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "automatic", "manual" ] }, "automatic_expiry_period": { "type": "integer" }, "manual_expiry_period": { "type": "integer" }, "refund_speed": { "type": "string" } } }, "settlements": { "type": "object", "properties": { "account_number": { "type": "string" }, "ifsc_code": { "type": "string" }, "beneficiary_name": { "type": "string" } } }, "checkout": { "type": "object" }, "refund": { "type": "object" }, "notifications": { "type": "object" }, "payment_methods": { "type": "object", "description": "One payment method can be updated per PATCH request" } } }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "field_reference": { "type": "string" }, "resolution_url": { "type": "string" }, "status": { "type": "string" }, "reason_code": { "type": "string" }, "description": { "type": "string" } } } }, "requested_at": { "type": "integer" } } }, "PartnerStakeholder": { "type": "object", "description": "A stakeholder (director/executive) associated with a sub-merchant account. Multiple stakeholders allowed per account (unlike Route which allows only 1).", "properties": { "id": { "type": "string", "description": "Stakeholder ID with prefix sth_" }, "entity": { "type": "string", "enum": [ "stakeholder" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "percentage_ownership": { "type": "number" }, "relationship": { "type": "object", "properties": { "director": { "type": "boolean" }, "executive": { "type": "boolean" } } }, "phone": { "type": "object", "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" } } }, "addresses": { "type": "object", "properties": { "residential": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } } } }, "kyc": { "type": "object", "properties": { "pan": { "type": "string" } } }, "notes": { "type": "object" } } }, "PartnerWebhook": { "type": "object", "description": "A webhook configured for a sub-merchant account via the Partners API. Maximum 30 webhooks per account.", "properties": { "id": { "type": "string", "description": "Webhook ID, max 14 characters" }, "entity": { "type": "string", "enum": [ "webhook" ] }, "owner_id": { "type": "string" }, "owner_type": { "type": "string" }, "url": { "type": "string", "description": "HTTPS URL to receive webhook events" }, "alert_email": { "type": "string" }, "secret": { "type": "string", "description": "Shared secret for HMAC verification (write-only)" }, "secret_exists": { "type": "boolean" }, "active": { "type": "boolean" }, "events": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Map of event names to boolean" }, "service": { "type": "string" }, "context": { "type": "array", "items": { "type": "string" } }, "disabled_at": { "type": "integer" }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "AccountDocument": { "type": "object", "description": "KYC documents for a sub-merchant account. Files must be JPG/PNG (max 4MB) or PDF (max 2MB).", "properties": { "business_proof_of_identification": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "business_proof_url", "gst_certificate", "shop_establishment_certificate", "certificate_of_incorporation", "trust_deed", "society_registration_certificate" ] }, "document_id": { "type": "string" } } } }, "business_proof_of_address": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "document_id": { "type": "string" } } } } } }, "StakeholderDocument": { "type": "object", "description": "KYC documents for a stakeholder. Supports PAN, Aadhaar, passport, and voter ID. Files must be JPG/PNG (max 4MB) or PDF (max 2MB).", "properties": { "individual_proof_of_address": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "aadhar_front", "aadhar_back", "passport_front", "passport_back", "voter_id_front", "voter_id_back" ] }, "url": { "type": "string" }, "document_id": { "type": "string" } } } }, "individual_proof_of_identification": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal_pan" ] }, "url": { "type": "string" }, "document_id": { "type": "string" } } } } } }, "XContact": { "type": "object", "description": "RazorpayX payout recipient. Created before sending payouts.", "properties": { "id": { "type": "string", "description": "Contact ID (cont_*)" }, "entity": { "type": "string", "enum": [ "contact" ] }, "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "email": { "type": "string", "format": "email" }, "contact": { "type": "string", "description": "Phone number" }, "type": { "type": "string", "enum": [ "vendor", "customer", "employee", "self" ], "description": "Built-in types only via API; custom types must be created on Dashboard first" }, "reference_id": { "type": "string", "maxLength": 40, "description": "External reference (must be unique per merchant)" }, "batch_id": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "type": "object" }, "created_at": { "type": "integer", "description": "Unix timestamp" } } }, "FundAccount": { "type": "object", "description": "Payout destination linked to a Contact. Immutable after creation.", "properties": { "id": { "type": "string", "description": "Fund account ID (fa_*)" }, "entity": { "type": "string", "enum": [ "fund_account" ] }, "contact_id": { "type": "string" }, "account_type": { "type": "string", "enum": [ "bank_account", "vpa", "card", "wallet" ] }, "active": { "type": "boolean" }, "batch_id": { "type": "string" }, "bank_account": { "type": "object", "properties": { "ifsc": { "type": "string" }, "bank_name": { "type": "string" }, "name": { "type": "string" }, "account_number": { "type": "string" } } }, "vpa": { "type": "object", "properties": { "username": { "type": "string" }, "handle": { "type": "string" }, "address": { "type": "string" } } }, "card": { "type": "object", "properties": { "last4": { "type": "string" }, "network": { "type": "string" }, "type": { "type": "string" }, "issuer": { "type": "string" }, "input_type": { "type": "string", "enum": [ "razorpay_token", "service_provider_token", "raw" ] } } }, "created_at": { "type": "integer" }, "wallet": { "type": "object", "description": "Amazon Pay wallet details. Required when account_type=wallet.", "properties": { "provider": { "type": "string", "enum": [ "amazonpay" ] }, "phone": { "type": "string", "description": "10-digit phone with country code, e.g. +919876543210" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 4, "maxLength": 120, "description": "Wallet holder name. Case-sensitive. Supported: a-z, A-Z, 0-9, space, ', -, _, /, (, ), ." } } } } }, "Payout": { "type": "object", "description": "RazorpayX payout disbursement. Idempotency header X-Payout-Idempotency required since March 15, 2025.", "properties": { "id": { "type": "string", "description": "Payout ID (pout_*)" }, "entity": { "type": "string", "enum": [ "payout" ] }, "fund_account_id": { "type": "string" }, "fund_account": { "$ref": "#/components/schemas/FundAccount" }, "amount": { "type": "integer", "minimum": 100, "description": "Amount in paise (min 100)" }, "currency": { "type": "string", "enum": [ "INR" ] }, "fees": { "type": "integer" }, "tax": { "type": "integer" }, "mode": { "type": "string", "enum": [ "NEFT", "RTGS", "IMPS", "UPI", "card", "amazonpay" ], "description": "Transfer mode \u2014 case-sensitive. amazonpay limited to \u20b910,000 per transaction; no custom narration allowed." }, "utr": { "type": "string", "description": "Unique Transaction Reference from bank" }, "reference_id": { "type": "string", "maxLength": 40 }, "debit_account_number": { "type": "string" }, "narration": { "type": "string", "maxLength": 30 }, "purpose": { "type": "string", "enum": [ "refund", "cashback", "payout", "salary", "utility bill", "vendor bill" ] }, "fee_type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "pending", "rejected", "processing", "processed", "cancelled", "reversed", "failed" ] }, "status_details": { "type": "object", "properties": { "description": { "type": "string" }, "source": { "type": "string" }, "reason": { "type": "string" } } }, "batch_id": { "type": "string" }, "notes": { "type": "object" }, "created_at": { "type": "integer" }, "queue_if_low_balance": { "type": "boolean", "description": "true: queue payout when account balance is insufficient. false (default): fail immediately." } } }, "FundAccountValidation": { "type": "object", "description": "Bank/VPA account validation result. Live-mode only, RazorpayX Lite only.", "properties": { "id": { "type": "string", "description": "Validation ID (fav_*)" }, "entity": { "type": "string", "enum": [ "fund_account.validation" ] }, "status": { "type": "string", "enum": [ "created", "completed", "failed" ] }, "amount": { "type": "integer", "description": "Penny drop amount in paise" }, "currency": { "type": "string" }, "utr": { "type": "string" }, "reference_id": { "type": "string" }, "notes": { "type": "object" }, "validated_account_type": { "type": "string" }, "fund_account": { "type": "object", "properties": { "id": { "type": "string" }, "account_type": { "type": "string" }, "bank_account": { "type": "object" }, "vpa": { "type": "object" } } }, "validation_results": { "type": "object", "properties": { "account_status": { "type": "string" }, "registered_name": { "type": "string" }, "name_match_score": { "type": "integer" }, "details": { "type": "object" } } }, "status_details": { "type": "object" }, "upi_intent": { "type": "object", "description": "Present only for reverse penny drop (UPI intent flow)", "properties": { "intent_url": { "type": "string" }, "phonepe_url": { "type": "string" }, "gpay_url": { "type": "string" }, "paytm_url": { "type": "string" }, "bhim_url": { "type": "string" }, "encoded_qr_code": { "type": "string" } } }, "created_at": { "type": "integer" } } }, "BankingBalance": { "type": "object", "description": "RazorpayX banking account balance.", "properties": { "entity": { "type": "string", "enum": [ "banking_balance" ] }, "currency": { "type": "string" }, "account_number": { "type": "string" }, "account_type": { "type": "string", "enum": [ "current_account", "fixed_deposit", "razorpayx_lite" ] }, "bank_name": { "type": "string" }, "bank_code": { "type": "string", "description": "First 4 characters of IFSC" }, "amount": { "type": "integer", "description": "Total balance in paise" }, "available_amount": { "type": "integer", "description": "Available balance in paise" }, "refreshed_at": { "type": "integer", "description": "Unix timestamp of last refresh" } } }, "PayoutLink": { "type": "object", "description": "Payout link sent to a contact when fund account details are unavailable.", "properties": { "id": { "type": "string", "description": "Payout link ID (poutlk_*)" }, "entity": { "type": "string", "enum": [ "payout_link" ] }, "contact_id": { "type": "string" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" }, "type": { "type": "string" } } }, "amount": { "type": "integer", "description": "Amount in paise" }, "currency": { "type": "string" }, "purpose": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "issued", "processing", "processed", "cancelled", "rejected" ] }, "fund_account_id": { "type": "string" }, "payout_id": { "type": "string" }, "description": { "type": "string" }, "receipt": { "type": "string" }, "notes": { "type": "object" }, "send_sms": { "type": "boolean" }, "send_email": { "type": "boolean" }, "short_url": { "type": "string" }, "attempt_count": { "type": "integer" }, "created_at": { "type": "integer" }, "cancelled_at": { "type": "integer" }, "expire_by": { "type": "integer", "description": "Must be at least 15 minutes in the future" }, "expired_at": { "type": "integer" } } }, "XTransaction": { "type": "object", "description": "RazorpayX transaction record \u2014 inflow (bank_transfer credit) or outflow (payout debit).", "properties": { "id": { "type": "string", "description": "Transaction ID (txn_*)" }, "entity": { "type": "string", "enum": [ "transaction" ] }, "account_number": { "type": "string", "description": "RazorpayX account number" }, "amount": { "type": "integer", "description": "Amount in paise (does not include fees/tax)" }, "currency": { "type": "string", "enum": [ "INR" ] }, "credit": { "type": "integer", "description": "Amount credited in paise; 0 for debits" }, "debit": { "type": "integer", "description": "Amount debited in paise; 0 for credits" }, "balance": { "type": "integer", "description": "Remaining account balance in paise after this transaction" }, "source": { "type": "object", "description": "Source entity \u2014 either a payout (debit) or bank_transfer (credit)", "properties": { "id": { "type": "string", "description": "pout_* for payouts, bt_* for bank transfers" }, "entity": { "type": "string", "enum": [ "payout", "bank_transfer" ] }, "amount": { "type": "integer" }, "fund_account_id": { "type": "string", "description": "Payout only" }, "notes": { "type": "object", "description": "Payout only" }, "fees": { "type": "integer", "description": "Payout only, populated at processing state" }, "tax": { "type": "integer", "description": "Payout only, populated at processing state" }, "status": { "type": "string", "description": "Payout only" }, "utr": { "type": "string", "description": "Payout only" }, "mode": { "type": "string", "description": "Payout only" }, "fee_type": { "type": "string" }, "payer_name": { "type": "string", "description": "bank_transfer only" }, "payer_account": { "type": "string", "description": "bank_transfer only" }, "payer_ifsc": { "type": "string", "description": "bank_transfer only" }, "bank_reference": { "type": "string", "description": "bank_transfer only" }, "created_at": { "type": "integer" } } }, "created_at": { "type": "integer", "description": "Unix timestamp" } } } }, "responses": { "401": { "description": "Authentication failed. Invalid or missing API key credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Bad request. Invalid parameters or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Implement exponential backoff with jitter before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/orders": { "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Create an order before initiating a payment. The returned order_id must be passed to Razorpay Checkout. An order can have multiple payment attempts but only one successful capture.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "description": "Payment amount in paise. Example: 50000 for \u20b9500. Must be >= 100.", "minimum": 100 }, "currency": { "type": "string", "description": "ISO 4217 currency code. Example: INR.", "default": "INR" }, "receipt": { "type": "string", "description": "Your internal receipt number. Max 40 characters." }, "notes": { "$ref": "#/components/schemas/Notes" }, "partial_payment": { "type": "boolean", "description": "Allow partial payments.", "default": false } } }, "example": { "amount": 50000, "currency": "INR", "receipt": "receipt_001" } } } }, "responses": { "200": { "description": "Order created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "fetchAllOrders", "summary": "Fetch all orders", "description": "Retrieve a paginated list of orders. Maximum 100 records per call.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" }, { "name": "authorized", "in": "query", "description": "1 = orders with authorized payments only. 0 = without.", "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "receipt", "in": "query", "description": "Filter by receipt value.", "schema": { "type": "string" } }, { "name": "expand[]", "in": "query", "description": "Expand: payments, payments.card, transfers, virtual_account.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "payments", "payments.card", "transfers", "virtual_account" ] } }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Collection of orders.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/orders/{id}": { "get": { "operationId": "fetchOrder", "summary": "Fetch order by ID", "description": "Retrieve the full details and current status of a specific order.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID (order_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateOrder", "summary": "Update an order", "description": "Update the notes field of an existing order. Only notes can be modified after creation.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID (order_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notes" ], "properties": { "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Updated order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/orders/{id}/payments": { "get": { "operationId": "fetchOrderPayments", "summary": "Fetch payments for an order", "description": "Retrieve all authorized and failed payment attempts made against a specific order.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID (order_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection of payments for the order.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments": { "get": { "operationId": "fetchAllPayments", "summary": "Fetch all payments", "description": "Retrieve a paginated list of payments. Maximum 100 per call.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of payments.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{id}": { "get": { "operationId": "fetchPayment", "summary": "Fetch payment by ID", "description": "Retrieve full details and current status of a specific payment. Always re-fetch before acting \u2014 status can change.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updatePayment", "summary": "Update a payment", "description": "Update the notes field of a payment. Only notes can be modified.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notes" ], "properties": { "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Updated payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{id}/capture": { "post": { "operationId": "capturePayment", "summary": "Capture a payment", "description": "Capture an authorized payment to collect funds. Must be called within the capture window (default 5 days). Amount must exactly equal authorized amount unless partial capture is enabled.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*). Must be in 'authorized' status.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "description": "Amount to capture in paise. Must equal authorized amount unless partial capture is enabled." }, "currency": { "type": "string", "default": "INR" } } }, "example": { "amount": 50000, "currency": "INR" } } } }, "responses": { "200": { "description": "Payment captured. Status changes to 'captured'.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{id}/refund": { "post": { "operationId": "createRefund", "summary": "Create a refund", "description": "Initiate a full or partial refund for a captured payment. Use speed=normal (default, 5-7 business days) or speed=optimum for instant refund (falls back to normal if unavailable). Use the X-Refund-Idempotency header with a unique key (>=10 chars) to safely retry without duplicate refunds.", "tags": [ "Refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID to refund (pay_*). Payment must be captured.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Refund amount in paise. Omit to refund the full payment amount." }, "speed": { "type": "string", "enum": [ "normal", "optimum" ], "default": "normal", "description": "normal: 5-7 business days. optimum: instant if available, falls back to normal." }, "notes": { "$ref": "#/components/schemas/Notes" }, "receipt": { "type": "string", "description": "Your internal reference identifier." } } }, "example": { "amount": 50000, "speed": "normal", "receipt": "refund_receipt_001" } } } }, "responses": { "200": { "description": "Refund initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } }, "x-idempotency": { "header": "X-Refund-Idempotency", "description": "Unique key (>=10 chars, alphanumeric/hyphens/underscores). Same key + same payload = same result. Different payload = BAD_REQUEST. 409 Conflict = prior request still processing, retry." } } }, "/payments/{payment_id}/refunds": { "get": { "operationId": "fetchPaymentRefunds", "summary": "Fetch refunds for a payment", "description": "Retrieve all refunds issued against a specific payment.", "tags": [ "Refunds" ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of refunds for the payment.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{payment_id}/refunds/{refund_id}": { "get": { "operationId": "fetchPaymentRefund", "summary": "Fetch a specific refund for a payment", "description": "Retrieve a specific refund by its ID scoped to a particular payment.", "tags": [ "Refunds" ], "parameters": [ { "name": "payment_id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } }, { "name": "refund_id", "in": "path", "required": true, "description": "Refund ID (rfnd_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/refunds": { "get": { "operationId": "fetchAllRefunds", "summary": "Fetch all refunds", "description": "Retrieve a paginated list of all refunds across payments. Maximum 100 per call.", "tags": [ "Refunds" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of refunds.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/refunds/{id}": { "get": { "operationId": "fetchRefund", "summary": "Fetch refund by ID", "description": "Retrieve full details and current status of a specific refund.", "tags": [ "Refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Refund ID (rfnd_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refund details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateRefund", "summary": "Update a refund", "description": "Update the notes field of a refund. Only notes can be modified.", "tags": [ "Refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Refund ID (rfnd_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notes" ], "properties": { "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Updated refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/downtimes": { "get": { "operationId": "fetchPaymentDowntimes", "summary": "Fetch all payment downtimes", "description": "Retrieve current and upcoming payment method downtimes for cards, netbanking, and UPI. Use to surface degraded methods in checkout UI.", "tags": [ "Payment Downtimes" ], "responses": { "200": { "description": "Collection of active and scheduled downtimes.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDowntime" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/downtimes/{id}": { "get": { "operationId": "fetchPaymentDowntime", "summary": "Fetch payment downtime by ID", "description": "Retrieve details of a specific payment downtime event.", "tags": [ "Payment Downtimes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Downtime identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Downtime details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDowntime" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/settlements": { "get": { "operationId": "fetchAllSettlements", "summary": "Fetch all settlements", "description": "Retrieve a paginated list of settlements. Each settlement represents a batch transfer to your bank account. Maximum 100 per call.", "tags": [ "Settlements" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of settlements.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/settlements/{id}": { "get": { "operationId": "fetchSettlement", "summary": "Fetch settlement by ID", "description": "Retrieve details of a specific settlement transaction.", "tags": [ "Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Settlement ID (setl_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Settlement details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/settlements/recon/combined": { "get": { "operationId": "fetchSettlementRecon", "summary": "Fetch settlement reconciliation report", "description": "Retrieve a detailed transaction-level reconciliation report for a given month (or day). Each record maps a payment, refund, transfer, or adjustment to its settlement. Use for accounting reconciliation. Maximum 1000 records per call.", "tags": [ "Settlements" ], "parameters": [ { "name": "year", "in": "query", "required": true, "description": "Settlement year in YYYY format.", "schema": { "type": "integer", "example": 2024 } }, { "name": "month", "in": "query", "required": true, "description": "Settlement month in MM format (01\u201312).", "schema": { "type": "integer", "minimum": 1, "maximum": 12, "example": 4 } }, { "name": "day", "in": "query", "description": "Settlement day in DD format (1\u201331). Omit to fetch the full month.", "schema": { "type": "integer", "minimum": 1, "maximum": 31 } }, { "name": "count", "in": "query", "description": "Records per call. Maximum 1000. Default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 } }, { "name": "skip", "in": "query", "description": "Records to skip for pagination.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Reconciliation report records.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementReconRecord" } } } } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/settlements/ondemand": { "post": { "operationId": "createInstantSettlement", "summary": "Create an instant settlement", "description": "Request an on-demand (instant) settlement of your available Razorpay balance to your bank account. Fees apply. Use settle_full_balance=true to settle everything available, or specify an amount.", "tags": [ "Instant Settlements" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "description": "Settlement amount in paise." }, "settle_full_balance": { "type": "boolean", "description": "Set true to settle the full available balance. Overrides amount.", "default": false }, "description": { "type": "string", "description": "Custom reference note. Max 30 alphanumeric characters." }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Instant settlement initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantSettlement" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchAllInstantSettlements", "summary": "Fetch all instant settlements", "description": "Retrieve a list of all on-demand instant settlements. Use expand[]=ondemand_payouts to include individual payout records inline.", "tags": [ "Instant Settlements" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" }, { "name": "expand[]", "in": "query", "description": "Set to ondemand_payouts to include payout details.", "schema": { "type": "string", "enum": [ "ondemand_payouts" ] } } ], "responses": { "200": { "description": "Collection of instant settlements.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstantSettlement" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/settlements/ondemand/{id}": { "get": { "operationId": "fetchInstantSettlement", "summary": "Fetch instant settlement by ID", "description": "Retrieve details of a specific on-demand instant settlement. Use expand[]=ondemand_payouts to include payout records.", "tags": [ "Instant Settlements" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instant settlement ID (setlod_*).", "schema": { "type": "string" } }, { "name": "expand[]", "in": "query", "description": "Set to ondemand_payouts to include payout details.", "schema": { "type": "string", "enum": [ "ondemand_payouts" ] } } ], "responses": { "200": { "description": "Instant settlement details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantSettlement" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/disputes": { "get": { "operationId": "fetchAllDisputes", "summary": "Fetch all disputes", "description": "Retrieve a list of all payment disputes. Use expand[]=payment or expand[]=transaction.settlement for additional context.", "tags": [ "Disputes" ], "parameters": [ { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" }, { "name": "expand[]", "in": "query", "description": "Expand sub-entities. Supported: payment, transaction.settlement.", "schema": { "type": "string", "enum": [ "payment", "transaction.settlement" ] } } ], "responses": { "200": { "description": "Collection of disputes.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Dispute" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/disputes/{id}": { "get": { "operationId": "fetchDispute", "summary": "Fetch dispute by ID", "description": "Retrieve full details of a specific dispute including submitted evidence.", "tags": [ "Disputes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dispute ID (disp_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dispute details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/disputes/{id}/accept": { "post": { "operationId": "acceptDispute", "summary": "Accept a dispute", "description": "Accept a dispute, acknowledging it as lost. This is irreversible \u2014 the dispute status changes to 'lost' and the disputed amount is deducted from your balance. Only accept if you do not wish to contest.", "tags": [ "Disputes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dispute ID (disp_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dispute accepted. Status changes to 'lost'.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/disputes/{id}/contest": { "patch": { "operationId": "contestDispute", "summary": "Contest a dispute", "description": "Submit evidence to challenge a dispute. Use action=draft to save without submitting, or action=submit to send for bank review (triggers payment.dispute.under_review webhook). At least one evidence document is required when submitting. You can contest partial amounts by specifying amount.", "tags": [ "Disputes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dispute ID (disp_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "draft", "submit" ], "description": "draft: save evidence without submitting. submit: send for bank review. Minimum one document required for submit." }, "amount": { "type": "integer", "description": "Amount being contested (paise). Defaults to full dispute amount." }, "summary": { "type": "string", "description": "Your explanation of why the dispute should be resolved in your favour. Max 1000 characters." }, "shipping_proof": { "type": "array", "items": { "type": "string" }, "description": "Document IDs proving product shipment." }, "billing_proof": { "type": "array", "items": { "type": "string" } }, "cancellation_proof": { "type": "array", "items": { "type": "string" } }, "customer_communication": { "type": "array", "items": { "type": "string" } }, "proof_of_service": { "type": "array", "items": { "type": "string" } }, "explanation_letter": { "type": "array", "items": { "type": "string" } }, "refund_confirmation": { "type": "array", "items": { "type": "string" } }, "access_activity_log": { "type": "array", "items": { "type": "string" } }, "refund_cancellation_policy": { "type": "array", "items": { "type": "string" } }, "term_and_conditions": { "type": "array", "items": { "type": "string" } }, "others": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Dispute contested. Status changes to 'under_review' on submit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/customers": { "post": { "operationId": "createCustomer", "summary": "Create a customer", "description": "Create a customer profile. The combination of email and contact must be unique per customer. Customer profiles enable saved card tokens, faster checkout, and customer-scoped data.", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Customer name. 3-50 characters. Allowed: alphanumeric, period, apostrophe, forward slash, @, parentheses." }, "contact": { "type": "string", "description": "Phone number with country code. Min 8 digits, max 15 chars. Example: +919876543210." }, "email": { "type": "string", "description": "Email address. Max 64 characters." }, "gstin": { "type": "string", "description": "GST Identification Number." }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "example": { "name": "Aisha Sharma", "contact": "+919876543210", "email": "aisha@example.com" } } } }, "responses": { "200": { "description": "Customer created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchAllCustomers", "summary": "Fetch all customers", "description": "Retrieve a paginated list of all customers. Maximum 100 per call.", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of customers.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/customers/{id}": { "get": { "operationId": "fetchCustomer", "summary": "Fetch customer by ID", "description": "Retrieve full details of a specific customer.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer ID (cust_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "put": { "operationId": "updateCustomer", "summary": "Update a customer", "description": "Update a customer's name, email, or contact. The combination of email and contact must remain unique. Contact number must contain at least 8 digits.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer ID (cust_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name. 3-50 characters." }, "contact": { "type": "string", "description": "Updated phone number. Min 8 digits including country code." }, "email": { "type": "string", "description": "Updated email. Max 64 characters." } } } } } }, "responses": { "200": { "description": "Updated customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/documents": { "post": { "operationId": "uploadDocument", "summary": "Upload a document", "description": "Upload a file to Razorpay. Returns a document ID that can be used in dispute evidence submissions. Supports JPEG, PNG, and PDF formats.", "tags": [ "Documents" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "purpose" ], "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload. Supported: JPEG, PNG, PDF." }, "purpose": { "type": "string", "description": "Reason for upload. Example: dispute_evidence." } } } } } }, "responses": { "200": { "description": "Document uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/documents/{id}": { "get": { "operationId": "fetchDocument", "summary": "Fetch document info", "description": "Retrieve metadata for an uploaded document (name, MIME type, size, purpose). Document IDs are exactly 14 alphanumeric characters.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID (doc_*). Exactly 14 alphanumeric characters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/documents/{id}/content": { "post": { "operationId": "fetchDocumentContent", "summary": "Fetch document content", "description": "Retrieve the binary content of a previously uploaded document. Returns the raw file bytes.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document ID. Exactly 14 alphanumeric characters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document binary content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payment_links": { "post": { "operationId": "createPaymentLink", "summary": "Create a payment link", "description": "Create a shareable payment link to collect payments via SMS and email. Supports standard links (all payment methods) and UPI-only links (set upi_link=true). UPI links are not available in test mode. Partial payments are not supported for UPI links. Links expire after 6 months by default.", "tags": [ "Payment Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "description": "Amount in smallest currency unit (paise for INR). Example: 50000 for \u20b9500." }, "currency": { "type": "string", "default": "INR", "description": "ISO 4217 currency code. UPI links support INR only." }, "upi_link": { "type": "boolean", "default": false, "description": "Set true to create a UPI-only Payment Link. Not available in test mode." }, "accept_partial": { "type": "boolean", "description": "Enable partial payments. Not supported for UPI links." }, "first_min_partial_amount": { "type": "integer", "description": "Minimum first partial payment amount in paise." }, "expire_by": { "type": "integer", "description": "Unix timestamp for link expiry. Max 6 months from creation. Must be at least 15 minutes in the future." }, "reference_id": { "type": "string", "description": "Your unique tracking reference. Max 40 characters. Must be unique." }, "description": { "type": "string", "description": "Brief description shown on the payment page. Max 2048 characters." }, "customer": { "type": "object", "description": "Customer contact details. Not auto-populated on checkout \u2014 customer must enter manually.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } }, "notify": { "type": "object", "description": "Notification handlers. Set true for Razorpay to send, false to handle yourself.", "properties": { "sms": { "type": "boolean" }, "email": { "type": "boolean" } } }, "reminder_enable": { "type": "boolean", "description": "Send automatic payment reminders." }, "callback_url": { "type": "string", "description": "Redirect URL after payment completion." }, "callback_method": { "type": "string", "enum": [ "get" ], "description": "Required when callback_url is set." }, "notes": { "$ref": "#/components/schemas/Notes" }, "options": { "type": "object", "description": "Checkout and payment page customization.", "properties": { "checkout": { "type": "object", "properties": { "name": { "type": "string", "description": "Custom business name displayed on checkout." }, "theme": { "type": "object", "properties": { "hide_topbar": { "type": "boolean", "description": "Hide the checkout top bar to prevent method switching." } } }, "method": { "type": "object", "description": "Enable or disable specific payment methods.", "properties": { "card": { "type": "boolean" }, "netbanking": { "type": "boolean" }, "upi": { "type": "boolean" }, "wallet": { "type": "boolean" } } }, "config": { "type": "object", "description": "Advanced checkout display configuration (blocks, sequence, preferences).", "properties": { "display": { "type": "object", "properties": { "blocks": { "type": "object", "description": "Custom payment method groupings with names and instruments." }, "sequence": { "type": "array", "items": { "type": "string" }, "description": "Display order of payment method blocks." }, "preferences": { "type": "object", "properties": { "show_default_blocks": { "type": "boolean" } } } } } } }, "partial_payment": { "type": "object", "description": "Rename partial payment labels (for localisation).", "properties": { "min_amount_label": { "type": "string" }, "partial_amount_label": { "type": "string" }, "partial_amount_description": { "type": "string" }, "full_amount_label": { "type": "string" } } } } }, "hosted_page": { "type": "object", "description": "Customise labels on the payment details section of the hosted page.", "properties": { "label": { "type": "object", "description": "Map of field names to custom label text. Supports localisation (Hindi, Tamil, etc.).", "properties": { "PAYMENT FOR": { "type": "string" }, "RECEIPT NO.": { "type": "string" }, "AMOUNT PAYABLE": { "type": "string" }, "EXPIRES ON": { "type": "string" }, "DUE": { "type": "string" }, "PAID": { "type": "string" }, "AMOUNT PAID": { "type": "string" }, "ISSUED TO": { "type": "string" } } } } }, "order": { "type": "object", "description": "Order-level options including offers and transfers.", "properties": { "offers": { "type": "array", "items": { "type": "string" }, "description": "Offer IDs to apply. Do not combine with accept_partial." }, "transfers": { "type": "array", "description": "Auto-transfer payments to linked accounts.", "items": { "type": "object", "properties": { "account": { "type": "string", "description": "Linked account ID." }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } } } } } }, "example": { "amount": 50000, "currency": "INR", "description": "Payment for Order #1234", "customer": { "name": "Aisha Sharma", "email": "aisha@example.com", "contact": "+919876543210" }, "notify": { "sms": true, "email": true }, "reminder_enable": true } } } }, "responses": { "200": { "description": "Payment link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchAllPaymentLinks", "summary": "Fetch all payment links", "description": "Retrieve all payment links. Filter by payment_id or reference_id to narrow results.", "tags": [ "Payment Links" ], "parameters": [ { "name": "payment_id", "in": "query", "description": "Filter by associated payment ID.", "schema": { "type": "string" } }, { "name": "reference_id", "in": "query", "description": "Filter by your custom reference number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payment links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_links": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payment_links/{id}": { "get": { "operationId": "fetchPaymentLink", "summary": "Fetch payment link by ID", "description": "Retrieve full details of a specific payment link.", "tags": [ "Payment Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment Link ID (plink_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment link details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updatePaymentLink", "summary": "Update a payment link", "description": "Update an existing payment link. Updates are only allowed when the link is in 'created' or 'partially_paid' status.", "tags": [ "Payment Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment Link ID (plink_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference_id": { "type": "string", "description": "Add or update unique reference number. Max 40 characters." }, "expire_by": { "type": "integer", "description": "Updated expiry Unix timestamp." }, "reminder_enable": { "type": "boolean" }, "accept_partial": { "type": "boolean" }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Updated payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payment_links/{id}/cancel": { "post": { "operationId": "cancelPaymentLink", "summary": "Cancel a payment link", "description": "Cancel a payment link. Only links in 'created' status can be cancelled. Paid, partially paid, and already expired links cannot be cancelled.", "tags": [ "Payment Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment Link ID (plink_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment link cancelled. Status changes to 'cancelled'.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payment_links/{id}/notify_by/{medium}": { "post": { "operationId": "resendPaymentLinkNotification", "summary": "Send or resend payment link notification", "description": "Send or resend a payment link notification to the customer via SMS or email.", "tags": [ "Payment Links" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment Link ID (plink_*).", "schema": { "type": "string" } }, { "name": "medium", "in": "path", "required": true, "description": "Notification medium.", "schema": { "type": "string", "enum": [ "sms", "email" ] } } ], "responses": { "200": { "description": "Notification sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/qr_codes": { "post": { "operationId": "createQrCode", "summary": "Create a QR code", "description": "Create a UPI QR code for accepting digital payments. Only upi_qr type is supported (on-demand feature; requires merchant activation). single_use QR codes require fixed_amount=true and close_by maximum is 45 days. multiple_use QR codes have no expiry restriction.", "tags": [ "QR Codes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "name", "usage", "fixed_amount" ], "properties": { "type": { "type": "string", "enum": [ "upi_qr" ], "description": "QR code type. Only upi_qr is supported (on-demand feature requiring merchant activation)." }, "name": { "type": "string", "description": "Label for the QR code." }, "usage": { "type": "string", "enum": [ "single_use", "multiple_use" ], "description": "single_use: auto-closes after first successful payment (requires fixed_amount=true). multiple_use: stays open for multiple payments." }, "fixed_amount": { "type": "boolean", "description": "true: fixed amount QR (required for single_use). false: customer enters amount at scan time." }, "payment_amount": { "type": "integer", "description": "Fixed payment amount in paise. Required when fixed_amount=true." }, "description": { "type": "string" }, "customer_id": { "type": "string", "description": "Associate QR code with a customer (cust_*)." }, "close_by": { "type": "integer", "description": "Unix timestamp for auto-close. Maximum 45 days from creation for single_use." }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "QR code created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCode" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchAllQrCodes", "summary": "Fetch all QR codes", "description": "Retrieve all QR codes. Filter by customer_id or payment_id.", "tags": [ "QR Codes" ], "parameters": [ { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID (cust_*).", "schema": { "type": "string" } }, { "name": "payment_id", "in": "query", "description": "Filter QR codes associated with a specific payment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection of QR codes.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QrCode" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/qr_codes/{id}": { "get": { "operationId": "fetchQrCode", "summary": "Fetch QR code by ID", "description": "Retrieve details of a specific QR code including payment counts and status.", "tags": [ "QR Codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QR code ID (qr_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "QR code details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCode" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateQrCode", "summary": "Update a QR code", "description": "Update the notes field of a QR code. Only notes can be modified after creation.", "tags": [ "QR Codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QR code ID (qr_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "notes" ], "properties": { "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Updated QR code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCode" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/qr_codes/{id}/close": { "post": { "operationId": "closeQrCode", "summary": "Close a QR code", "description": "Deactivate a QR code to stop accepting new payments. Once closed, the QR code cannot be reopened.", "tags": [ "QR Codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QR code ID (qr_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "QR code closed. Status changes to 'closed'.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCode" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/qr_codes/{id}/payments": { "get": { "operationId": "fetchQrCodePayments", "summary": "Fetch payments for a QR code", "description": "Retrieve all payments made against a specific QR code.", "tags": [ "QR Codes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "QR code ID (qr_*).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of payments for the QR code.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items": { "post": { "operationId": "createItem", "summary": "Create an item", "description": "Create a reusable catalog item. Items can be referenced in invoice line_items by item_id, which auto-fills price and description. Each item is merchant-scoped.", "tags": [ "Items" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "amount", "currency" ], "properties": { "name": { "type": "string", "description": "Item display name." }, "description": { "type": "string" }, "amount": { "type": "integer", "description": "Item price in paise." }, "currency": { "type": "string", "default": "INR" } } } } } }, "responses": { "200": { "description": "Item created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listItems", "summary": "List all items", "description": "Retrieve all catalog items. Supports pagination.", "tags": [ "Items" ], "parameters": [ { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of items.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/items/{id}": { "get": { "operationId": "fetchItem", "summary": "Fetch an item", "description": "Get details of a specific catalog item.", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item ID (item_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateItem", "summary": "Update an item", "description": "Update the name, description, amount, currency, or active status of an item.", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item ID (item_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "integer", "description": "Price in paise." }, "currency": { "type": "string" }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "deleteItem", "summary": "Delete an item", "description": "Permanently delete a catalog item. Deleted items cannot be recovered.", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item ID (item_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item deleted.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/invoices": { "post": { "operationId": "createInvoice", "summary": "Create an invoice", "description": "Create an invoice or payment page. Set type='invoice' for a formal invoice or type='link' for a simple payment page. The invoice is created in draft state; call POST /invoices/{id}/issue to send it to the customer. Cannot be used to create GST invoices (use the Dashboard for those). Maximum 50 line items per invoice.", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "invoice", "link" ], "description": "invoice: formal invoice; link: payment page." }, "description": { "type": "string" }, "customer_id": { "type": "string", "description": "Existing customer ID (cust_*). Provide this OR customer object, not both." }, "customer": { "type": "object", "description": "Inline customer details. Used when no customer_id is available.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } }, "line_items": { "type": "array", "maxItems": 50, "description": "Invoice line items. Each item must have name and amount (in paise), or an item_id to reference a catalog item.", "items": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Reference a catalog item. Populates name, amount, currency automatically." }, "name": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "integer", "description": "Price in paise." }, "quantity": { "type": "integer", "default": 1 }, "currency": { "type": "string", "default": "INR" } } } }, "currency": { "type": "string", "default": "INR" }, "receipt": { "type": "string", "description": "Your internal reference number." }, "comment": { "type": "string" }, "terms": { "type": "string", "description": "Payment terms shown on the invoice." }, "partial_payment": { "type": "boolean", "description": "Allow customer to pay a partial amount initially." }, "first_payment_min_amount": { "type": "integer", "description": "Minimum first payment amount in paise. Required when partial_payment=true." }, "expire_by": { "type": "integer", "description": "Unix timestamp after which the invoice expires. Must be at least 15 minutes in the future." }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Invoice created in draft state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listInvoices", "summary": "List all invoices", "description": "Retrieve a list of invoices. Filter by type, status, customer, payment, or subscription. Returns up to 100 per call.", "tags": [ "Invoices" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "invoice", "link" ] }, "description": "Filter by invoice type." }, { "name": "payment_id", "in": "query", "schema": { "type": "string" }, "description": "Filter invoices by the payment ID used to pay them." }, { "name": "customer_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by customer ID (cust_*)." }, { "name": "subscription_id", "in": "query", "schema": { "type": "string" }, "description": "Fetch all invoices generated for a subscription (sub_*)." }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of invoices.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/invoices/{id}": { "get": { "operationId": "fetchInvoice", "summary": "Fetch an invoice", "description": "Get full details of a specific invoice including status, line items, and payment information.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateInvoice", "summary": "Update an invoice", "description": "Update invoice fields. Updatable fields depend on current status: draft=all fields; issued=partial_payment, receipt, comment, terms, notes, expire_by; paid/cancelled/expired=notes only.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "receipt": { "type": "string" }, "comment": { "type": "string" }, "terms": { "type": "string" }, "partial_payment": { "type": "boolean" }, "expire_by": { "type": "integer" }, "notes": { "$ref": "#/components/schemas/Notes" }, "line_items": { "type": "array", "description": "Replaces existing line items. Draft status only.", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Updated invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "deleteInvoice", "summary": "Delete a draft invoice", "description": "Permanently delete a draft invoice. Only invoices in draft status can be deleted.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice deleted.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/invoices/{id}/issue": { "post": { "operationId": "issueInvoice", "summary": "Issue an invoice", "description": "Transition a draft invoice to issued status, sending a notification to the customer with the payment link. Once issued, line items cannot be changed.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice issued. short_url is now active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/invoices/{id}/cancel": { "post": { "operationId": "cancelInvoice", "summary": "Cancel an invoice", "description": "Cancel a draft or issued invoice. Cancelled invoices cannot be paid and cannot be reinstated.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/invoices/{id}/notify_by/{medium}": { "post": { "operationId": "sendInvoiceNotification", "summary": "Send invoice notification", "description": "Send or resend the invoice payment link to the customer via SMS or email.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoice ID (inv_*).", "schema": { "type": "string" } }, { "name": "medium", "in": "path", "required": true, "description": "Notification channel.", "schema": { "type": "string", "enum": [ "sms", "email" ] } } ], "responses": { "200": { "description": "Notification sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/plans": { "post": { "operationId": "createPlan", "summary": "Create a plan", "description": "Define a recurring billing plan with a fixed period, interval, and amount. Plans are reusable across multiple subscriptions. Once created, plan details cannot be modified.", "tags": [ "Plans" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "interval", "item" ], "properties": { "period": { "type": "string", "enum": [ "daily", "weekly", "monthly", "quarterly", "yearly" ], "description": "Billing frequency unit. For daily, minimum interval is 7." }, "interval": { "type": "integer", "description": "Number of periods between charges (e.g. interval=3, period=monthly \u2192 charge every 3 months)." }, "item": { "type": "object", "required": [ "name", "amount", "currency" ], "properties": { "name": { "type": "string", "description": "Plan display name shown to customers." }, "description": { "type": "string" }, "amount": { "type": "integer", "description": "Charge amount in paise per billing cycle." }, "currency": { "type": "string", "default": "INR" } } }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "example": { "period": "monthly", "interval": 1, "item": { "name": "Pro Plan", "description": "Monthly SaaS subscription", "amount": 49900, "currency": "INR" } } } } }, "responses": { "200": { "description": "Plan created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listPlans", "summary": "List all plans", "description": "Retrieve all billing plans. Supports pagination.", "tags": [ "Plans" ], "parameters": [ { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of plans.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/plans/{id}": { "get": { "operationId": "fetchPlan", "summary": "Fetch a plan", "description": "Get details of a specific billing plan.", "tags": [ "Plans" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Plan ID (plan_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions": { "post": { "operationId": "createSubscription", "summary": "Create a subscription", "description": "Subscribe a customer to a plan. Returns a short_url that the customer MUST open to authorize the payment mandate (UPI Autopay, NACH, or card-on-file). The subscription will not charge until the mandate is authorized. Set notify_info to send the auth link via SMS/email automatically. Requires Subscriptions feature enabled on your Razorpay account.", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan_id", "total_count" ], "properties": { "plan_id": { "type": "string", "description": "Plan ID (plan_*) to subscribe the customer to." }, "total_count": { "type": "integer", "description": "Total number of billing cycles. Use 0 for indefinite (no fixed end)." }, "quantity": { "type": "integer", "default": 1, "description": "Number of plan units billed per cycle." }, "customer_notify": { "type": "integer", "enum": [ 0, 1 ], "description": "1 to have Razorpay notify customer via SMS/email on each charge event." }, "start_at": { "type": "integer", "description": "Unix timestamp for the first charge. Defaults to subscription creation time." }, "expire_by": { "type": "integer", "description": "Unix timestamp deadline for the customer to authorize the mandate." }, "addons": { "type": "array", "description": "One-time charges added to the first billing cycle only.", "items": { "type": "object", "properties": { "item": { "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "integer", "description": "Addon amount in paise." }, "currency": { "type": "string", "default": "INR" } } } } } }, "offer_id": { "type": "string", "description": "Offer/coupon ID to apply to the subscription." }, "notify_info": { "type": "object", "description": "If provided, Razorpay sends the mandate auth link directly to the customer.", "properties": { "notify_phone": { "type": "string", "description": "Customer phone number to send SMS." }, "notify_email": { "type": "string", "description": "Customer email address to send the link." } } }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Subscription created. Send short_url to the customer for mandate authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listSubscriptions", "summary": "List all subscriptions", "description": "Retrieve all subscriptions. Filter by plan_id or status. Returns up to 100 per call.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "plan_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by plan ID." }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/skip" } ], "responses": { "200": { "description": "Collection of subscriptions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Collection" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}": { "get": { "operationId": "fetchSubscription", "summary": "Fetch a subscription", "description": "Get current status and full details of a subscription.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateSubscription", "summary": "Update a subscription", "description": "Update plan, quantity, or schedule future changes for a subscription. Use schedule_change_at='now' for immediate effect (creates a new billing cycle) or 'cycle_end' to defer until the current cycle ends. Cannot change plan mid-cycle without creating a new cycle.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "New plan ID to switch to." }, "quantity": { "type": "integer" }, "remaining_count": { "type": "integer", "description": "Override remaining billing cycles." }, "schedule_change_at": { "type": "string", "enum": [ "now", "cycle_end" ], "description": "When changes take effect. 'now' starts a new cycle immediately; 'cycle_end' defers to end of current cycle." }, "customer_notify": { "type": "integer", "enum": [ 0, 1 ] }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Subscription updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "summary": "Cancel a subscription", "description": "Cancel an active or authenticated subscription. Use cancel_at_cycle_end=1 to continue service until the end of the current cycle before cancelling.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cancel_at_cycle_end": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = cancel at end of current cycle; 0 = cancel immediately." } } } } } }, "responses": { "200": { "description": "Subscription cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}/pause": { "post": { "operationId": "pauseSubscription", "summary": "Pause a subscription", "description": "Pause an active subscription. No charges will be attempted while paused. Resume with POST /subscriptions/{id}/resume.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pause_at": { "type": "string", "enum": [ "now", "cycle_end" ], "description": "When to pause. 'now' = immediately; 'cycle_end' = after current cycle." } } } } } }, "responses": { "200": { "description": "Subscription paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}/resume": { "post": { "operationId": "resumeSubscription", "summary": "Resume a paused subscription", "description": "Resume a paused subscription. Charging resumes on the next scheduled cycle.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resume_at": { "type": "string", "enum": [ "now" ], "description": "When to resume. Currently only 'now' is supported." } } } } } }, "responses": { "200": { "description": "Subscription resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}/retrieve_scheduled_changes": { "get": { "operationId": "fetchSubscriptionScheduledChanges", "summary": "Fetch scheduled changes", "description": "Retrieve any pending plan or quantity changes scheduled for the next billing cycle.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled changes for the subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "entity": { "type": "string" }, "change_scheduled_at": { "type": "integer" }, "status": { "type": "string" }, "subscription_id": { "type": "string" }, "plan_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{id}/cancel_scheduled_changes": { "post": { "operationId": "cancelSubscriptionScheduledChanges", "summary": "Cancel scheduled changes", "description": "Cancel any pending plan or quantity changes that were scheduled for the next billing cycle.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled changes cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/subscriptions/{sub_id}/{offer_id}": { "delete": { "operationId": "deleteSubscriptionOffer", "summary": "Delete an offer from a subscription", "description": "Remove an applied offer/coupon from a subscription. The offer will no longer apply from the next billing cycle.", "tags": [ "Subscriptions" ], "parameters": [ { "name": "sub_id", "in": "path", "required": true, "description": "Subscription ID (sub_*).", "schema": { "type": "string" } }, { "name": "offer_id", "in": "path", "required": true, "description": "Offer ID to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer removed from subscription.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/accounts": { "post": { "operationId": "createLinkedAccount", "summary": "Create a Linked Account", "description": "Create a sub-merchant (Linked Account) under a Route marketplace. The account type must be 'route'. Email and business_type cannot be changed after creation. Only one stakeholder is allowed per Linked Account.", "tags": [ "Linked Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "profile", "type" ], "properties": { "email": { "type": "string", "description": "Contact email. Cannot be changed after creation." }, "phone": { "type": "string", "description": "Phone number with country code." }, "legal_business_name": { "type": "string" }, "business_type": { "type": "string", "enum": [ "route" ], "description": "Cannot be changed after creation." }, "type": { "type": "string", "enum": [ "route" ] }, "profile": { "type": "object", "properties": { "category": { "type": "string" }, "subcategory": { "type": "string" }, "addresses": { "type": "object" } } }, "legal_info": { "type": "object", "properties": { "pan": { "type": "string" }, "gst": { "type": "string" } } }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Linked Account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/accounts/{account_id}": { "get": { "operationId": "fetchLinkedAccount", "summary": "Fetch a Linked Account", "description": "Retrieve the details of a Linked Account by its ID. Also used in Partners API to fetch sub-merchant account details (authentication: OAuth access_token).", "tags": [ "Linked Accounts", "Partner Accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Linked Account details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccount" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateLinkedAccount", "summary": "Update a Linked Account", "description": "Update mutable fields of a Linked Account. email and business_type cannot be changed after creation.", "tags": [ "Linked Accounts", "Partner Accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "legal_business_name": { "type": "string" }, "profile": { "type": "object" }, "legal_info": { "type": "object" }, "contact_name": { "type": "string" }, "contact_info": { "type": "object" }, "apps": { "type": "object" }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Linked Account updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "delete": { "operationId": "deletePartnerAccount", "summary": "Delete (suspend) a sub-merchant account", "description": "Suspend a sub-merchant account created via Partners API. Sets account status to 'suspended' and returns suspended_at timestamp. Authentication: OAuth access_token as username with empty password.", "tags": [ "Partner Accounts" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account ID with prefix acc_" } ], "responses": { "200": { "description": "Account suspended", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "suspended" ] }, "suspended_at": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/accounts/{account_id}/stakeholders": { "post": { "operationId": "createStakeholder", "summary": "Create a Stakeholder", "description": "Add a business owner or director to a Linked Account. Only one stakeholder is allowed per Route Linked Account. PAN 4th character must be 'P' (individual PAN).", "tags": [ "Linked Accounts", "Partner Stakeholders" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "percentage_ownership": { "type": "number" }, "relationship": { "type": "object", "properties": { "director": { "type": "boolean" }, "executive": { "type": "boolean" } } }, "phone": { "type": "object" }, "addresses": { "type": "object" }, "kyc": { "type": "object", "properties": { "pan": { "type": "string", "description": "Individual PAN. 4th character must be P." } } }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Stakeholder created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stakeholder" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchAllStakeholders", "summary": "Fetch all stakeholders for an account", "description": "Retrieve all stakeholders associated with a sub-merchant account. Partners API only \u2014 Route allows only 1 stakeholder per account. Authentication: OAuth access_token.", "tags": [ "Partner Stakeholders" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." } ], "responses": { "200": { "description": "List of stakeholders", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerStakeholder" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/accounts/{account_id}/stakeholders/{stakeholder_id}": { "patch": { "operationId": "updateStakeholder", "summary": "Update a Stakeholder", "description": "Update stakeholder information for a Linked Account.", "tags": [ "Linked Accounts", "Partner Stakeholders" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } }, { "name": "stakeholder_id", "in": "path", "required": true, "description": "Stakeholder ID (sth_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "percentage_ownership": { "type": "number" }, "relationship": { "type": "object" }, "phone": { "type": "object" }, "addresses": { "type": "object" }, "kyc": { "type": "object" }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Stakeholder updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stakeholder" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/accounts/{account_id}/products": { "post": { "operationId": "requestProductConfig", "summary": "Request Route product configuration", "description": "Request activation of the Route product for a Linked Account. Submits the account for review and KYC. Activation progresses: requested \u2192 under_review \u2192 activated.", "tags": [ "Linked Accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_name" ], "properties": { "product_name": { "type": "string", "enum": [ "route" ] }, "tnc_accepted": { "type": "boolean", "description": "Set to true to accept Razorpay TnC on behalf of the sub-merchant." }, "applicable_identified": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Product configuration created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductConfiguration" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/accounts/{account_id}/products/{product_id}": { "get": { "operationId": "fetchProductConfig", "summary": "Fetch product configuration", "description": "Retrieve the current product configuration and activation status for a Linked Account.", "tags": [ "Linked Accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "Product configuration ID (acc_prd_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product configuration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductConfiguration" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateProductConfig", "summary": "Update product configuration", "description": "Update settlement details or other configuration for a Route product on a Linked Account.", "tags": [ "Linked Accounts" ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "Linked Account ID (acc_*).", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "Product configuration ID (acc_prd_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settlements": { "type": "object", "properties": { "account_number": { "type": "string" }, "ifsc_code": { "type": "string" }, "beneficiary_name": { "type": "string" } } }, "tnc_accepted": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Product configuration updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductConfiguration" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{id}/transfers": { "post": { "operationId": "createTransfersFromPayment", "summary": "Create transfers from a payment", "description": "Split a captured payment to one or more Linked Accounts. Amount is deducted from the payment and transferred to the recipient. INR only, minimum \u20b9100 per transfer.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transfers" ], "properties": { "transfers": { "type": "array", "items": { "type": "object", "required": [ "account", "amount", "currency" ], "properties": { "account": { "type": "string", "description": "Linked Account ID (acc_*)." }, "amount": { "type": "integer", "description": "Amount in paise. Minimum 10000." }, "currency": { "type": "string", "enum": [ "INR" ] }, "notes": { "$ref": "#/components/schemas/Notes" }, "linked_account_notes": { "type": "array", "items": { "type": "string" } }, "on_hold": { "type": "boolean" }, "on_hold_until": { "type": "integer" } } } } } } } } }, "responses": { "200": { "description": "Transfers created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "fetchTransfersForPayment", "summary": "Fetch transfers for a payment", "description": "Retrieve all transfers created from a specific payment.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of transfers for the payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/transfers": { "post": { "operationId": "createDirectTransfer", "summary": "Create a direct transfer", "description": "Create an on-demand direct transfer from the merchant account to a Linked Account. Requires the Direct Transfer feature to be enabled on the account. Supports idempotency via the X-Transfer-Idempotency header (unique to direct transfers).", "tags": [ "Transfers" ], "parameters": [ { "name": "X-Transfer-Idempotency", "in": "header", "required": false, "description": "Idempotency key for direct transfers. If provided, retrying with the same key within 24 hours returns the original transfer instead of creating a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "amount", "currency" ], "properties": { "account": { "type": "string", "description": "Linked Account ID (acc_*)." }, "amount": { "type": "integer", "description": "Amount in paise. Minimum 10000 (\u20b9100)." }, "currency": { "type": "string", "enum": [ "INR" ] }, "notes": { "$ref": "#/components/schemas/Notes" }, "linked_account_notes": { "type": "array", "items": { "type": "string" } }, "on_hold": { "type": "boolean" }, "on_hold_until": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Transfer created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listTransfers", "summary": "List transfers", "description": "Retrieve a paginated list of transfers. Filter by recipient_settlement_id to fetch transfers included in a specific settlement. Use expand[]=recipient_settlement to include settlement details.", "tags": [ "Transfers" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter (start)." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter (end)." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Number of records to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of records to skip. Use for pagination. Default: 0." }, { "name": "recipient_settlement_id", "in": "query", "schema": { "type": "string" }, "description": "Filter transfers by settlement ID in the Linked Account." }, { "name": "expand[]", "in": "query", "schema": { "type": "string", "enum": [ "recipient_settlement" ] }, "description": "Expand recipient_settlement to include full settlement object." } ], "responses": { "200": { "description": "List of transfers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/transfers/{id}": { "get": { "operationId": "fetchTransfer", "summary": "Fetch a transfer", "description": "Retrieve details of a specific transfer by ID.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer ID (trf_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transfer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "modifyTransferSettlementHold", "summary": "Modify settlement hold on a transfer", "description": "Put a transfer's settlement on hold or release an existing hold. Use on_hold=true to hold settlement, on_hold=false to release. on_hold_until sets a future timestamp for automatic hold release.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer ID (trf_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "on_hold": { "type": "boolean", "description": "true to hold settlement; false to release." }, "on_hold_until": { "type": "integer", "description": "Unix timestamp for automatic hold release. null = hold indefinitely until manually released." } } } } } }, "responses": { "200": { "description": "Transfer settlement hold updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/transfers/{id}/reversals": { "post": { "operationId": "reverseTransfer", "summary": "Reverse a transfer", "description": "Move funds from a Linked Account back to the merchant. Partial reversals are supported. Multiple reversals per transfer are allowed as long as the total reversed amount does not exceed the transfer amount.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer ID (trf_*).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Amount to reverse in paise. Omit to reverse the full remaining amount." }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Reversal created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reversal" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listReversals", "summary": "List reversals for a transfer", "description": "Retrieve all reversals for a specific transfer.", "tags": [ "Transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer ID (trf_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of reversals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Reversal" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts": { "post": { "operationId": "createVirtualAccount", "summary": "Create a Virtual Account", "description": "Create a virtual bank account (and optionally a VPA) for accepting NEFT/RTGS/IMPS/UPI payments. Set amount_expected=0 to accept any amount. Auto-closes after 90 days of inactivity. Maximum close_by timestamp: 2147483647.", "tags": [ "Virtual Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "receivers", "description" ], "properties": { "receivers": { "type": "object", "required": [ "types" ], "properties": { "types": { "type": "array", "items": { "type": "string", "enum": [ "bank_account", "vpa" ] }, "description": "Receiver types. bank_account creates a virtual bank account. vpa creates a UPI VPA (Smart Collect 2.0, requires feature flag)." } } }, "description": { "type": "string", "description": "Purpose of the virtual account." }, "amount": { "type": "integer", "description": "Expected amount in paise. Set to 0 to accept any amount." }, "customer_id": { "type": "string", "description": "Link to an existing customer (cust_*)." }, "close_by": { "type": "integer", "description": "Unix timestamp to auto-close the account. Maximum: 2147483647." }, "notes": { "$ref": "#/components/schemas/Notes" } } } } } }, "responses": { "200": { "description": "Virtual Account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } }, "get": { "operationId": "listVirtualAccounts", "summary": "List Virtual Accounts", "description": "Retrieve a paginated list of virtual accounts with optional filters.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter (start)." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter (end)." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Number of records to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of records to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of Virtual Accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualAccount" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{id}": { "get": { "operationId": "fetchVirtualAccount", "summary": "Fetch a Virtual Account", "description": "Retrieve details of a specific virtual account.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Virtual Account details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } }, "patch": { "operationId": "updateVirtualAccount", "summary": "Update a Virtual Account", "description": "Update the amount_expected or close_by timestamp on an active virtual account.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "description": "New expected amount in paise." }, "close_by": { "type": "integer", "description": "New close timestamp. Maximum: 2147483647." }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Virtual Account updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{id}/close": { "post": { "operationId": "closeVirtualAccount", "summary": "Close a Virtual Account", "description": "Manually close an active virtual account so it no longer accepts payments.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "closed" ], "description": "Must be 'closed' to close the account." } } } } } }, "responses": { "200": { "description": "Virtual Account closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{id}/payments": { "get": { "operationId": "fetchVirtualAccountPayments", "summary": "Fetch payments for a Virtual Account", "description": "Retrieve all payments received by a virtual account. Returns Payment objects.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payments for the virtual account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{id}/receivers": { "post": { "operationId": "addVpaReceiver", "summary": "Add a VPA receiver to a Virtual Account", "description": "Add a UPI VPA receiver to an existing virtual account (Smart Collect 2.0). Requires the VPA receiver feature to be enabled on the merchant account.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "types" ], "properties": { "types": { "type": "array", "items": { "type": "string", "enum": [ "vpa" ] }, "description": "Must contain 'vpa'." } } } } } }, "responses": { "200": { "description": "VPA receiver added. Returns the updated VirtualAccount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{va_id}/allowed_payers": { "post": { "operationId": "addAllowedPayer", "summary": "Add an allowed payer (TPV)", "description": "Whitelist a specific payer bank account or VPA for a virtual account (Smart Collect with Third Party Validation). Only whitelisted payers can successfully pay into this virtual account.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "va_id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "bank_account", "vpa" ], "description": "Type of allowed payer." }, "bank_account": { "type": "object", "description": "Required if type=bank_account.", "properties": { "ifsc": { "type": "string" }, "account_number": { "type": "string" } } }, "vpa": { "type": "object", "description": "Required if type=vpa.", "properties": { "address": { "type": "string", "description": "Full UPI VPA address (e.g., user@upi)." } } } } } } } }, "responses": { "200": { "description": "Allowed payer added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/virtual_accounts/{va_id}/allowed_payers/{id}": { "delete": { "operationId": "deleteAllowedPayer", "summary": "Delete an allowed payer (TPV)", "description": "Remove a payer from the whitelist of a virtual account (Smart Collect TPV). The payer will no longer be able to make payments to this virtual account.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "va_id", "in": "path", "required": true, "description": "Virtual Account ID (va_*).", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Allowed payer ID to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Allowed payer removed.", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/payments/{id}/bank_transfer": { "get": { "operationId": "fetchBankTransfer", "summary": "Fetch bank transfer details for a payment", "description": "Retrieve the BankTransfer entity associated with a payment received via a Virtual Account. Contains the UTR number, payer bank account details, and transfer mode.", "tags": [ "Virtual Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment ID (pay_*).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bank transfer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransfer" } } } }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/bills": { "post": { "operationId": "createBill", "summary": "Create a bill", "description": "Create a digital bill/receipt for a customer. Supports retail, food & beverage, events, and ecommerce use cases. Used for Razorpay Billme digital receipts.", "tags": [ "Bills" ], "security": [ { "basicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "business_type", "customer" ], "properties": { "business_type": { "type": "string", "enum": [ "ecommerce", "retail", "food_and_beverage", "events" ] }, "business_category": { "type": "string" }, "customer": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "customer_id": { "type": "string" } } }, "receipt_timestamp": { "type": "integer" }, "receipt_number": { "type": "string" }, "receipt_type": { "type": "string", "enum": [ "tax_invoice", "sales_invoice", "bill_of_supply", "credit_note", "debit_note" ] }, "receipt_delivery": { "type": "string", "enum": [ "digital", "print", "digital_and_print" ] }, "store_code": { "type": "string" }, "order_number": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object" } }, "receipt_summary": { "type": "object" }, "taxes": { "type": "array", "items": { "type": "object" } }, "payments": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Bill created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/bills/{bill_id}": { "patch": { "operationId": "updateBill", "summary": "Update a bill", "description": "Update an existing digital bill. Can update customer details, line items, receipt summary, and other fields.", "tags": [ "Bills" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "bill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bill ID with prefix bill_" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "responses": { "200": { "description": "Bill updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bill" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "deleteBill", "summary": "Delete a bill", "description": "Delete a digital bill/receipt.", "tags": [ "Bills" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "bill_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bill ID with prefix bill_" } ], "responses": { "200": { "description": "Bill deleted successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/accounts/{account_id}/webhooks": { "post": { "operationId": "createPartnerWebhook", "summary": "Create a webhook for a sub-merchant", "description": "Create a webhook to receive events for a sub-merchant account. Maximum 30 webhooks per account. Authentication: OAuth access_token.", "tags": [ "Partner Webhooks" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string" }, "alert_email": { "type": "string" }, "secret": { "type": "string" }, "active": { "type": "boolean" }, "events": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } }, "responses": { "200": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listPartnerWebhooks", "summary": "List webhooks for a sub-merchant", "description": "Retrieve all webhooks configured for a sub-merchant account. Authentication: OAuth access_token.", "tags": [ "Partner Webhooks" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerWebhook" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/v2/accounts/{account_id}/webhooks/{webhook_id}": { "get": { "operationId": "fetchPartnerWebhook", "summary": "Fetch a webhook by ID", "description": "Retrieve details of a specific webhook for a sub-merchant account. Authentication: OAuth access_token.", "tags": [ "Partner Webhooks" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the webhook (e.g. `we_00000000000001`)." } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "operationId": "updatePartnerWebhook", "summary": "Update a webhook", "description": "Update webhook URL, events, secret, or active status for a sub-merchant account. Authentication: OAuth access_token.", "tags": [ "Partner Webhooks" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the webhook (e.g. `we_00000000000001`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "deletePartnerWebhook", "summary": "Delete a webhook", "description": "Delete a webhook for a sub-merchant account. Returns empty array on success. Authentication: OAuth access_token.", "tags": [ "Partner Webhooks" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the webhook (e.g. `we_00000000000001`)." } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "description": "Empty object on success." } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/accounts/{account_id}/documents": { "post": { "operationId": "uploadAccountDocuments", "summary": "Upload KYC documents for a sub-merchant account", "description": "Upload KYC documents for business identity and address verification. Multipart form upload. JPG/PNG max 4MB, PDF max 2MB. Authentication: OAuth access_token.", "tags": [ "Partner Documents" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "enum": [ "business_proof_url", "gst_certificate", "shop_establishment_certificate", "certificate_of_incorporation", "trust_deed", "society_registration_certificate" ] }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDocument" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "fetchAccountDocuments", "summary": "Fetch KYC documents for a sub-merchant account", "description": "Retrieve all KYC documents uploaded for a sub-merchant account. Authentication: OAuth access_token.", "tags": [ "Partner Documents" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." } ], "responses": { "200": { "description": "Account documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDocument" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/accounts/{account_id}/stakeholders/{stakeholder_id}/documents": { "post": { "operationId": "uploadStakeholderDocuments", "summary": "Upload KYC documents for a stakeholder", "description": "Upload identity and address verification documents for a stakeholder. Supports PAN, Aadhaar (front/back), passport (front/back), voter ID (front/back). Multipart form upload. JPG/PNG max 4MB, PDF max 2MB. Authentication: OAuth access_token.", "tags": [ "Partner Documents" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." }, { "name": "stakeholder_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the stakeholder (e.g. `sth_00000000000001`)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "enum": [ "personal_pan", "aadhar_front", "aadhar_back", "passport_front", "passport_back", "voter_id_front", "voter_id_back" ] }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakeholderDocument" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "fetchStakeholderDocuments", "summary": "Fetch KYC documents for a stakeholder", "description": "Retrieve all KYC documents uploaded for a specific stakeholder. Authentication: OAuth access_token.", "tags": [ "Partner Documents" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the linked merchant account (e.g. `acc_00000000000001`)." }, { "name": "stakeholder_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the stakeholder (e.g. `sth_00000000000001`)." } ], "responses": { "200": { "description": "Stakeholder documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakeholderDocument" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } } } }, "/contacts": { "post": { "operationId": "createContact", "summary": "Create a contact", "description": "Create a payout recipient contact. Returns existing contact if all identifying fields (name, email, contact, type) match an existing record.", "tags": [ "X Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 50 }, "email": { "type": "string", "format": "email" }, "contact": { "type": "string" }, "type": { "type": "string", "enum": [ "vendor", "customer", "employee", "self" ] }, "reference_id": { "type": "string", "maxLength": 40 }, "notes": { "type": "object" } } } } } }, "responses": { "200": { "description": "Contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XContact" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listContacts", "summary": "List contacts", "tags": [ "X Contacts" ], "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter by contact name (partial match supported)." }, { "name": "email", "in": "query", "schema": { "type": "string" }, "description": "Filter by contact email address." }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "description": "Filter by contact phone number." }, { "name": "reference_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by your unique reference ID for the contact (max 40 chars)." }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter" }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only contacts created before this timestamp are returned." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Number of contacts to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of contacts to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/XContact" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "Filter and list all contacts. Supports filtering by name, email, phone number, reference ID, and active status." } }, "/contacts/{contact_id}": { "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the contact (e.g. `cont_00000000000001`)." } ], "get": { "operationId": "fetchContact", "summary": "Fetch a contact", "tags": [ "X Contacts" ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XContact" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific contact by its ID." }, "patch": { "operationId": "updateContact", "summary": "Update or activate/deactivate a contact", "tags": [ "X Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" }, "type": { "type": "string" }, "reference_id": { "type": "string" }, "notes": { "type": "object" }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XContact" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "Update contact details or activate/deactivate a contact. Set `active: false` to deactivate." } }, "/fund_accounts": { "post": { "operationId": "createFundAccount", "summary": "Create a fund account", "description": "Create a bank account, VPA, card, or wallet (Amazon Pay) fund account linked to a contact. Fund accounts are immutable after creation. Returns existing record if contact_id + account details all match.", "tags": [ "X Fund Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact_id", "account_type" ], "properties": { "contact_id": { "type": "string" }, "account_type": { "type": "string", "enum": [ "bank_account", "vpa", "card", "wallet" ] }, "bank_account": { "type": "object", "properties": { "name": { "type": "string" }, "ifsc": { "type": "string" }, "account_number": { "type": "string" } } }, "vpa": { "type": "object", "properties": { "address": { "type": "string" } } }, "card": { "type": "object", "description": "Requires PCI DSS compliance", "properties": { "name": { "type": "string" }, "number": { "type": "string" }, "expiry_month": { "type": "string" }, "expiry_year": { "type": "string" }, "input_type": { "type": "string", "enum": [ "razorpay_token", "service_provider_token", "raw" ] }, "token_id": { "type": "string" }, "token": { "type": "string" } } }, "wallet": { "type": "object", "description": "Required when account_type=wallet (Amazon Pay only)", "properties": { "provider": { "type": "string", "enum": [ "amazonpay" ] }, "phone": { "type": "string", "description": "10-digit phone with country code (mandatory)" }, "email": { "type": "string" }, "name": { "type": "string", "minLength": 4, "maxLength": 120 } } } } } } } }, "responses": { "200": { "description": "Fund account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listFundAccounts", "summary": "List fund accounts", "tags": [ "X Fund Accounts" ], "parameters": [ { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by contact ID to list fund accounts linked to that contact." }, { "name": "account_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by fund account type: `bank_account`, `vpa`, `card`, or `wallet`." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Number of fund accounts to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of fund accounts to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of fund accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FundAccount" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "List fund accounts linked to contacts. Filter by contact ID and/or account type." } }, "/fund_accounts/{fund_account_id}": { "parameters": [ { "name": "fund_account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the fund account (e.g. `fa_00000000000001`)." } ], "get": { "operationId": "fetchFundAccount", "summary": "Fetch a fund account", "tags": [ "X Fund Accounts" ], "responses": { "200": { "description": "Fund account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific fund account by its ID." }, "patch": { "operationId": "activateDeactivateFundAccount", "summary": "Activate or deactivate a fund account", "tags": [ "X Fund Accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated fund account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundAccount" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "Activate or deactivate a fund account. Fund account details are immutable \u2014 only the `active` status can be changed." } }, "/fund_accounts/validations": { "post": { "operationId": "validateFundAccount", "summary": "Validate a bank account or VPA", "description": "Three validation methods: (1) penny drop for bank accounts \u2014 sends Re.1 to verify; (2) penny drop for VPA \u2014 sends Re.1 to UPI address; (3) reverse penny drop \u2014 sends UPI intent URL to customer who initiates payment. Live-mode only, RazorpayX Lite account required. Composite validation (creates Contact + Fund Account inline) supported via validation_type field.", "tags": [ "X Account Validation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_type", "fund_account" ], "properties": { "account_type": { "type": "string", "enum": [ "bank_account", "vpa" ] }, "fund_account": { "type": "object", "description": "For composite validation, include contact object instead of contact_id" }, "amount": { "type": "integer", "description": "Penny drop amount in paise (typically 100)" }, "currency": { "type": "string", "default": "INR" }, "notes": { "type": "object" }, "receipt": { "type": "string" }, "validation_type": { "type": "string", "enum": [ "pennydrop", "penniless", "optimized" ], "description": "penniless = reverse penny drop (UPI intent); optimized = system chooses best method" } } } } } }, "responses": { "200": { "description": "Validation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundAccountValidation" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listFundAccountValidations", "summary": "List fund account validations", "tags": [ "X Account Validation" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only validations created from this timestamp onwards are returned." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only validations created before this timestamp are returned." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Number of validation records to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of validation records to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of validations", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FundAccountValidation" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "List all fund account validation records, optionally filtered by date range." } }, "/fund_accounts/validations/{validation_id}": { "parameters": [ { "name": "validation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the fund account validation (e.g. `fav_00000000000001`)." } ], "get": { "operationId": "fetchFundAccountValidation", "summary": "Fetch a fund account validation", "tags": [ "X Account Validation" ], "responses": { "200": { "description": "Validation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundAccountValidation" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific fund account validation by its ID." } }, "/banking_balances": { "get": { "operationId": "fetchBankingBalances", "summary": "Fetch RazorpayX banking balances", "tags": [ "X Banking Balances" ], "parameters": [ { "name": "account_type", "in": "query", "schema": { "type": "string", "enum": [ "current_account", "fixed_deposit", "razorpayx_lite" ] }, "description": "Type of RazorpayX account to query. Accepted values: `current_account` or `razorpayx_lite`." }, { "name": "bank_code", "in": "query", "schema": { "type": "string" }, "description": "First 4 characters of IFSC" } ], "responses": { "200": { "description": "Banking balances", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BankingBalance" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "Fetch balance details for RazorpayX current accounts or RazorpayX Lite accounts." } }, "/payouts": { "post": { "operationId": "createPayout", "summary": "Create a payout", "description": "Disburse funds via NEFT, RTGS, IMPS, UPI, or card. Supports standard payouts (fund_account_id), composite payouts (contact + fund account inline), card payouts (PCI DSS required), and mobile number payouts (resolved via NPCI mapper). Idempotency header X-Payout-Idempotency (UUID v4, 4\u201336 chars) is mandatory since March 15, 2025. Never generate a new idempotency key while a payout is in 'processing' state.", "tags": [ "X Payouts" ], "parameters": [ { "name": "X-Payout-Idempotency", "in": "header", "required": true, "schema": { "type": "string", "minLength": 4, "maxLength": 36 }, "description": "UUID v4 idempotency key. Mandatory since March 15, 2025." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_number", "amount", "currency", "mode", "purpose" ], "properties": { "account_number": { "type": "string", "description": "Razorpay X account number to debit" }, "fund_account_id": { "type": "string", "description": "Required for standard payouts; omit for composite" }, "fund_account": { "type": "object", "description": "Inline fund account for composite payout" }, "amount": { "type": "integer", "minimum": 100, "description": "Amount in paise" }, "currency": { "type": "string", "enum": [ "INR" ] }, "mode": { "type": "string", "enum": [ "NEFT", "RTGS", "IMPS", "UPI", "card", "amazonpay" ], "description": "Case-sensitive" }, "purpose": { "type": "string", "enum": [ "refund", "cashback", "payout", "salary", "utility bill", "vendor bill" ] }, "narration": { "type": "string", "maxLength": 30 }, "reference_id": { "type": "string", "maxLength": 40 }, "notes": { "type": "object" }, "queue_if_low_balance": { "type": "boolean", "description": "true: queue payout when account balance is insufficient (default: false)" } } } } } }, "responses": { "200": { "description": "Payout created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listPayouts", "summary": "List payouts", "tags": [ "X Payouts" ], "parameters": [ { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The RazorpayX account number (Customer Identifier from Dashboard \u2192 My Account & Settings \u2192 Banking). Required to scope results to a specific account." }, { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter payouts by the contact ID of the recipient." }, { "name": "fund_account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter payouts by fund account ID." }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only payouts created from this timestamp onwards are returned." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only payouts created before this timestamp are returned." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 25 }, "description": "Number of payouts to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of payouts to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of payouts", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "List payouts for a given RazorpayX account. Filter by contact, fund account, date range, or status." } }, "/payouts/{payout_id}": { "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout (e.g. `pout_00000000000001`)." } ], "get": { "operationId": "fetchPayout", "summary": "Fetch a payout", "tags": [ "X Payouts" ], "responses": { "200": { "description": "Payout details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific payout by its ID." } }, "/payouts/{payout_id}/cancel": { "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout to cancel." } ], "post": { "operationId": "cancelPayout", "summary": "Cancel a queued payout", "description": "Only payouts in 'queued' status can be cancelled.", "tags": [ "X Payouts" ], "responses": { "200": { "description": "Payout cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/payouts/{payout_id}/approve": { "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout to approve." } ], "post": { "operationId": "approvePayout", "summary": "Approve a payout (workflow enabled)", "description": "Requires Payouts Approval workflow enabled and Technology Partner status with OAuth.", "tags": [ "X Payouts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "remarks": { "type": "string" } } } } } }, "responses": { "200": { "description": "Payout approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/payouts/{payout_id}/reject": { "parameters": [ { "name": "payout_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout to reject." } ], "post": { "operationId": "rejectPayout", "summary": "Reject a payout (workflow enabled)", "description": "Requires Payouts Approval workflow enabled and Technology Partner status with OAuth.", "tags": [ "X Payouts" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "remarks": { "type": "string" } } } } } }, "responses": { "200": { "description": "Payout rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/payout-links": { "post": { "operationId": "createPayoutLink", "summary": "Create a payout link", "description": "Send a payout link to a contact when fund account details are unavailable. expire_by must be at least 15 minutes in the future.", "tags": [ "X Payout Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact_id", "amount", "currency", "purpose" ], "properties": { "contact_id": { "type": "string" }, "amount": { "type": "integer", "description": "Amount in paise" }, "currency": { "type": "string", "enum": [ "INR" ] }, "purpose": { "type": "string" }, "description": { "type": "string" }, "receipt": { "type": "string" }, "send_sms": { "type": "boolean" }, "send_email": { "type": "boolean" }, "notes": { "type": "object" }, "expire_by": { "type": "integer", "description": "Unix timestamp; must be \u226515 minutes from now" } } } } } }, "responses": { "200": { "description": "Payout link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "get": { "operationId": "listPayoutLinks", "summary": "List payout links", "tags": [ "X Payout Links" ], "parameters": [ { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter payout links by the contact ID of the recipient." }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only payout links created from this timestamp onwards are returned." }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp. Only payout links created before this timestamp are returned." }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Number of payout links to return. Default: 10." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of payout links to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of payout links", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutLink" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "List all payout links. Filter by contact ID, status, or date range." } }, "/payout-links/{payout_link_id}": { "parameters": [ { "name": "payout_link_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout link (e.g. `poutlk_00000000000001`)." } ], "get": { "operationId": "fetchPayoutLink", "summary": "Fetch a payout link", "tags": [ "X Payout Links" ], "responses": { "200": { "description": "Payout link details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific payout link by its ID." } }, "/payout-links/{payout_link_id}/cancel": { "parameters": [ { "name": "payout_link_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the payout link to cancel." } ], "post": { "operationId": "cancelPayoutLink", "summary": "Cancel a payout link", "tags": [ "X Payout Links" ], "responses": { "200": { "description": "Payout link cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutLink" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "description": "Cancel a payout link that is in `issued` or `pending` state." } }, "/transactions": { "get": { "operationId": "listTransactions", "summary": "List transactions for a RazorpayX account", "description": "Returns all transaction records (credits and debits) for a given RazorpayX account. Use account_number from Dashboard \u2192 My Account & Settings \u2192 Banking \u2192 Customer Identifier.", "tags": [ "X Transactions" ], "parameters": [ { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string" }, "description": "RazorpayX account number (Customer Identifier from Dashboard). Different for Test and Live mode." }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter start" }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "Unix timestamp filter end" }, { "name": "count", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Number of transactions to return. Default: 10. Maximum: 100." }, { "name": "skip", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of transactions to skip. Use for pagination. Default: 0." } ], "responses": { "200": { "description": "List of transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "enum": [ "collection" ] }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/XTransaction" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/transactions/{transaction_id}": { "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transaction ID (txn_*)" } ], "get": { "operationId": "fetchTransaction", "summary": "Fetch a transaction by ID", "tags": [ "X Transactions" ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XTransaction" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" }, "404": { "$ref": "#/components/responses/404" } }, "description": "Fetch details of a specific transaction from a RazorpayX account by its ID." } } }, "tags": [ { "name": "Orders", "description": "Orders are the starting point for accepting a payment. Create an order with the amount and currency, pass the order_id to Razorpay Checkout, then verify the payment signature after success." }, { "name": "Payments", "description": "A payment is created when a customer completes checkout. Payments can be auto-captured or manually captured. Fetch payment details to reconcile and diagnose failures." }, { "name": "Refunds", "description": "Refunds return captured payment amounts to customers. Normal refunds take 5-7 business days. Instant (optimum) refunds settle immediately but may fall back to normal. Use X-Refund-Idempotency header to safely retry without duplicates." }, { "name": "Payment Downtimes", "description": "Scheduled and live downtime information for card, netbanking, and UPI. Poll or subscribe to payment.downtime webhooks to detect degraded methods and adjust your checkout UI." }, { "name": "Payment Links", "description": "Payment Links are shareable URLs to collect payments without a website. Share via SMS, email, or any channel. Supports partial payments, expiry, reminders, UPI-only mode, offers, and transfers to linked accounts." }, { "name": "QR Codes", "description": "QR Codes enable offline and digital payment collection. Customers scan with any UPI or card app. Supports fixed-amount and variable-amount codes, single-use and multiple-use modes." }, { "name": "Customers", "description": "Customer profiles store contact information for recurring billing, saved cards, and personalised checkout. Each email+contact combination must be unique." }, { "name": "Documents", "description": "Document uploads for dispute evidence. Upload JPEG, PNG, or PDF files and receive a document ID to reference in dispute contest submissions." }, { "name": "Settlements", "description": "Settlements represent batch transfers of collected payment funds to your bank account. Use the recon endpoint for transaction-level reconciliation reports mapping each payment, refund, and adjustment to its settlement." }, { "name": "Instant Settlements", "description": "On-demand settlements let you transfer your available Razorpay balance to your bank account immediately, outside the normal settlement cycle. Fees apply. Requires Instant Settlements to be enabled on your account." }, { "name": "Disputes", "description": "Disputes (chargebacks) are raised by customers via their bank. You can accept (lose) or contest (challenge with evidence) each dispute. Monitor respond_by timestamp \u2014 missing the deadline forfeits the dispute." }, { "name": "Items", "description": "Reusable catalog items that can be referenced in invoice line items. Defining items once avoids repeating price and description on each invoice." }, { "name": "Invoices", "description": "Invoices and payment pages for one-time or partial-payment collection. Create in draft, issue to the customer, and track payment status. Cannot be used for GST invoices (use the Dashboard for those). Maximum 50 line items per invoice." }, { "name": "Plans", "description": "Billing plan definitions for recurring subscriptions. A plan sets the billing period, interval, and per-cycle charge. Plans are reusable across multiple subscriptions and cannot be modified after creation." }, { "name": "Subscriptions", "description": "Recurring billing subscriptions. Customers must authorize a payment mandate (UPI Autopay, NACH, or card-on-file) via the short_url before charges begin. Supports pause/resume, plan changes, add-ons, and indefinite billing cycles." }, { "name": "Linked Accounts", "description": "Sub-merchant accounts (Linked Accounts) created under a Route marketplace. Includes account creation, stakeholder KYC, and Route product activation. Uses /v2/ API base path. Only one stakeholder is allowed per Linked Account. email and business_type cannot be changed after creation." }, { "name": "Transfers", "description": "Fund transfers from a merchant, payment, or order to a Linked Account (Route). Supports payment-based splits, direct on-demand transfers, settlement hold controls, and full/partial reversals. INR only, minimum \u20b9100. Direct transfers support idempotency via X-Transfer-Idempotency header." }, { "name": "Virtual Accounts", "description": "Virtual bank accounts and UPI VPAs that accept NEFT/RTGS/IMPS/UPI payments (Smart Collect). Each incoming payment creates a BankTransfer entity. Supports Third Party Validation (TPV) to restrict payers, and VPA receivers (Smart Collect 2.0). Auto-closes after 90 days of inactivity." }, { "name": "Bills", "description": "Razorpay Billme digital receipts and bills for retail, food & beverage, events, and ecommerce." }, { "name": "Partner Accounts", "description": "Sub-merchant account lifecycle management via Partners API (Aggregator/Platform model). Uses OAuth access_token authentication." }, { "name": "Partner Products", "description": "Configure payment_gateway or payment_links products for sub-merchant accounts." }, { "name": "Partner Stakeholders", "description": "Manage stakeholders (directors/executives) for sub-merchant accounts. Multiple stakeholders allowed per account." }, { "name": "Partner Documents", "description": "Upload and fetch KYC documents for sub-merchant accounts and their stakeholders." }, { "name": "Partner Webhooks", "description": "Configure webhooks for sub-merchant accounts to receive payment events. Maximum 30 per account." }, { "name": "X Contacts", "description": "RazorpayX payout recipients \u2014 create, fetch, update contacts" }, { "name": "X Fund Accounts", "description": "Payout destination accounts (bank, VPA, card) linked to contacts" }, { "name": "X Account Validation", "description": "Penny drop and reverse penny drop bank/VPA validation" }, { "name": "X Payouts", "description": "Disbursements via NEFT, RTGS, IMPS, UPI, card \u2014 includes composite and approval flows" }, { "name": "X Banking Balances", "description": "Fetch RazorpayX account balances" }, { "name": "X Payout Links", "description": "Payout links for recipients without saved fund accounts" }, { "name": "X Transactions", "description": "Fetch RazorpayX transaction records \u2014 credits (bank_transfer inflows) and debits (payout outflows)" } ], "x-tagGroups": [ { "name": "Core Payments", "tags": [ "Orders", "Payments", "Refunds", "Payment Downtimes" ] }, { "name": "Payment Collection", "tags": [ "Payment Links", "QR Codes" ] }, { "name": "Billing & Subscriptions", "tags": [ "Items", "Invoices", "Plans", "Subscriptions" ] }, { "name": "Customer Management", "tags": [ "Customers", "Documents" ] }, { "name": "Finance & Reconciliation", "tags": [ "Settlements", "Instant Settlements", "Disputes" ] }, { "name": "Route & Marketplace", "tags": [ "Linked Accounts", "Transfers" ] }, { "name": "Smart Collect", "tags": [ "Virtual Accounts" ] }, { "name": "Partners & Onboarding", "tags": [ "Partner Accounts", "Partner Products", "Partner Stakeholders", "Partner Documents", "Partner Webhooks" ] }, { "name": "Bills", "tags": [ "Bills" ] }, { "name": "RazorpayX", "tags": [ "X Contacts", "X Fund Accounts", "X Account Validation", "X Banking Balances", "X Payouts", "X Payout Links", "X Transactions" ] } ], "x-rateLimit": { "description": "Razorpay does not publish specific rate limits. If you receive HTTP 429, implement exponential backoff with jitter and retry. Add randomisation to avoid thundering-herd effects.", "throttleStatus": 429, "strategy": "exponential backoff with jitter" }, "x-pagination": { "description": "All list endpoints return at most 100 records per call (1000 for settlement recon). Use count and skip together to paginate. Date range filters (from/to) use Unix timestamps in seconds.", "example": "GET /payments?from=1700000000&to=1700086400&count=100&skip=100" }, "x-amountEncoding": { "description": "All monetary amounts are in the smallest currency sub-unit. For INR: 1 rupee = 100 paise, so \u20b9500 = 50000. Minimum for INR is 100 paise (\u20b91). Three-decimal currencies (KWD, BHD, OMR): drop last decimal digit. Zero-decimal currencies (JPY): pass value as-is." } }