S2S UPI Collect Flow
Collect UPI payments from your customers using the Razorpay S2S UPI Collect Flow API.
UPI payments enable customers to make payments using a Virtual Payment Address (VPA) without entering bank information.
Customers enter their VPAs on your UI, open the respective UPI apps and complete the payment after 2-factor authentication (UPI PIN and MPIN) on their mobile devices. Customers are redirected to your website or app after successful payment.
In this flow, customers likely enter invalid VPAs or forget their VPAs, which could lead to higher drop-off rates.To overcome this problem, Razorpay enables you to validate and save the VPAs of a customer. Know more about
.Handy Tips
As per NPCI guidelines, we have applied the following restrictions to the UPI Collect flow.
- MCC 6540: UPI Collect flow is not available for this MCC. You can use as an alternate.
- MCC 4812: Maximum amount limited to ₹5,000 per transaction for UPI Collect flow. You can use as an alternate.
- MCC 4814: Maximum amount limited to ₹5,000 per transaction for UPI Collect flow. You can use as an alternate.
Follow these best practices to accept online payments using the UPI collect flow:
- before initiating the payment request.
- Add a custom UPI Collect expiry based on the business requirement to provide enough time for the customer to complete the payment.
- Use the feature offered by Razorpay to provide a better customer experience.
- Reach out to our to enable VPA validation and saved VPA features for your account.
- Keep the API keys (
Key_Id
andKey_Secret
) handy for integration. - from the Dashboard.
Let us understand the process for accepting payments via the UPI collect flow:
- The customer selects UPI as the payment method and enters the VPA of their choice on the UI.
Razorpay validates the entered VPA. - The customer saves the entered VPA details while completing the payment.
Razorpay saves all the valid VPA details as tokens. - On a repeat visit, the customer selects the VPA token to complete the payment.
Given below are the steps to create VPA tokens:
- or fetch the customer for whom the VPA should be saved.
- .
- entered by the customer.
- with a collect request on the provided VPA.
- .
Handy Tips
Skip this step if you already have customers created in your account.
Create a customer whose VPAs should be saved, with details such as email
and contact
.
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X POST https://api.razorpay.com/v1/customers \-H "Content-Type: application/json" \-d '{"name": "Gaurav Kumar","email": "gaurav.kumar@example.com","contact": "9000090000","fail_existing": 0}'
name
mandatory
string
The name of the customer.
optional
string
The email ID of the customer.
contact
optional
string
The phone number of the customer.
fail_existing
optional
string
Possible values:
0
: If a customer with the same details already exists, fetch details of the existing customer.1
(default): If a customer with the same details already exists, it throws an error.
notes
optional
json object
Set of key-value pairs that can be associated with an entity. This can be useful for storing additional information about the entity. A maximum of 15 key-value pairs, each of 256 characters (maximum), are supported.
You should create an order before initiating a payment at your end.
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X POST https://api.razorpay.com/v1/orders \-H "Content-Type: application/json" \-d '{"amount": 200,"currency": "INR"}'
amount
mandatory
integer
The amount for which the order was created, in currency subunits.
For example, for an amount of ₹295, enter 29500
.
currency
mandatory
string
ISO code for the currency in which you want to accept the payment. Only INR
is supported.
receipt
optional
string
Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters.
notes
optional
json object
Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”
.
Collect the VPA details of the customer and validate it as follows:
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X POST https://api.razorpay.com/v1/payments/validate/vpa \-H "Content-Type: application/json" \-d '{"vpa": "gauravkumar@exampleupi"}'
vpa
mandatory
string
The virtual payment address (VPA) you want to validate. For example, gauravkumar@exampleupi
.
Once validated, you can now save the VPA provided by the customer. Create a payment with the valid vpa
as follows:
amount
mandatory
integer
The amount associated with the payment in the smallest unit of the supported currency. For example, 2000
means ₹20.
currency
mandatory
string
ISO code of the currency associated with the payment amount. Only INR
is supported.
order_id
mandatory
string
Unique identifier of the order obtained in the response of the previous step.
notes
optional
json object
Key-value pairs that can hold additional information about the payment.
Refer to the
description
optional
string
Descriptive text of the payment.
contact
mandatory
string
Phone number of the customer.
mandatory
string
Email address of the customer.
Watch Out!
The email
field is mandatory by default. However, you can contact the
save
boolean
Specifies if the VPA should be stored as tokens. Possible values are:
1
: Saves the VPA details.0
(default): Does not save the VPA details.
customer_id
mandatory
string
Unique identifier of the customer, obtained from the response of
callback_url
optional
string
URL where Razorpay will submit the final payment status.
ip
mandatory
string
The client's browser IP address. For example, 117.217.74.98
.
referer
mandatory
string
Value of referer
header passed by the client's browser. For example, https://example.com/
user_agent
mandatory
string
Value of user_agent
header passed by the client's browser.
For example, Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36
upi
Details of the collect expiry.
flow
mandatory
string
Specify the type of the UPI payment flow.
Possible values are:
collect
(default)intent
vpa
mandatory
string
The customer's VPA to which the collect request will be sent.
expiry_time
mandatory
integer
The number of minutes after which the link will expire. The default value is 5
. Maximum value is 5760
.
razorpay_payment_id
string
Unique identifier for the payment returned by Checkout only for successful payments.
Once the customer completes the payment, a POST
request is made to the callback_url
provided in the payment request. The data contained in this request will depend on whether the payment was a success or a failure.
If the payment made by the customer is successful, the following fields are sent:
razorpay_payment_id
razorpay_order_id
razorpay_signature
{"razorpay_payment_id": "pay_29QQoUBi66xm2f","razorpay_order_id": "order_9A33XWu170gUtm","razorpay_signature": "9ef4dffbfd84f1318f6739a3ce19f9d85851857ae648f114332d8401e0949a3d"}
If the payment has failed, the callback will contain details of the error. Refer to
for details.The customer can make payments using the VPA tokens (which were saved earlier) on a repeat transaction.
- .
- .
- with the token selected by the customer.
- .
You should create an order before initiating the payment.
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X POST https://api.razorpay.com/v1/orders \-H "Content-Type: application/json" \-d '{"amount": 600,"currency": "INR"}'
amount
mandatory
integer
The amount for which the order was created, in currency subunits. For example, for an amount of ₹295, enter 29500
. Payment can only be made for this amount against the order.
currency
mandatory
string
ISO code for the currency in which you want to accept the payment. Refer the
receipt
optional
string
Receipt number that corresponds to this order, set for your internal reference. Can have a maximum length of 40 characters.
notes
optional
json object
Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”
.
Use the API given below to retrieve all the card (if saved earlier) and VPA tokens of a customer.
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X GET https://api.razorpay.com/v1/customers/cust_EIW4T2etiweBmG/tokens
In each payment create request, instead of the vpa
field, pass the customer_id
and token
attributes:
curl -u <YOUR_KEY_ID>:<YOUR_KEY_SECRET> \-X POST https://api.razorpay.com/v1/payments/create/upi \-H "Content-Type: application/json" \-d '{"amount": 600,"currency": "INR","order_id": "order_ExhN1Y0100Dkjw","email": "gaurav.kumar@example.com","contact": "9000090000","method": "upi","customer_id": "cust_EIW4T2etiweBmG","token": "token_EeO65VIv8BXZg5""ip": "192.168.0.103","referer": "http","user_agent": "Mozilla/5.0","description": "Test flow","notes": {"note_key": "value1"}}'
customer_id
string
Unique identifier of the customer.
token
string
Token of the saved VPA.
Once the payment is successfully created, you will receive a response containing the next
array. This array tells you the next steps that you should take to process the payment:
razorpay_payment_id
string
Unique identifier for the payment returned by Checkout only for successful payments.
next
array
A list of action objects available to you to continue the payment process. Present when the payment requires further processing.
action
string
The action that you need to perform further. In this case, the value is poll
url
string
Contains the URL that you must poll to fetch the status of the payment, either authorized
or failed
.
Once the customer completes the payment, a POST
request is made to the callback_url
provided in the payment request. The data contained in this request will depend on whether the payment was a success or a failure.
If the payment made by the customer is successful, the following fields are sent:
razorpay_payment_id
razorpay_order_id
razorpay_signature
{"razorpay_payment_id": "pay_29QQoUBi66xm2f","razorpay_order_id": "order_9A33XWu170gUtm","razorpay_signature": "9ef4dffbfd84f1318f6739a3ce19f9d85851857ae648f114332d8401e0949a3d"}
If the payment has failed, the callback will contain details of the error. Refer to
for details.You can verify the status of the payments using any of the following methods:
-
Poll Razorpay servers periodically for the
using our Fetch Payment APIs. -
Subscribe to the webhook events created in our system for each of the following entities:
If the Order is not marked paid
within 2-3 minutes, then you can re-initiate payment for the same.
Is this integration guide useful?
ON THIS PAGE