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.
openapi: 3.0.0
info:
title: Razorpay Bills Payment Links 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 — 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 — keys prefixed rzp_live_. Real money movement. Requires KYC and business activation on the Razorpay Dashboard.
servers:
- url: https://api.razorpay.com/v1
description: Production
security:
- basicAuth: []
- oauth2:
- read_only
tags:
- 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.
paths:
/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 ₹500.'
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 — 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'
components:
schemas:
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 → 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 — 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
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
responses:
'404':
description: Resource not found.
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'
'401':
description: Authentication failed. Invalid or missing API key credentials.
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'
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)
externalDocs:
description: Razorpay API Documentation
url: https://razorpay.com/docs/api/
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 ₹500 = 50000. Minimum for INR is 100 paise (₹1). Three-decimal currencies (KWD, BHD, OMR): drop last decimal digit. Zero-decimal currencies (JPY): pass value as-is.'