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 and Key_Secret) handy for integration.
  • from the Dashboard.

Let us understand the process for accepting payments via the UPI collect flow:

  1. The customer selects UPI as the payment method and enters the VPA of their choice on the UI.
    Razorpay validates the entered VPA.
  2. The customer saves the entered VPA details while completing the payment.
    Razorpay saves all the valid VPA details as tokens.
  3. On a repeat visit, the customer selects the VPA token to complete the payment.

Given below are the steps to create VPA tokens:

  1. or fetch the customer for whom the VPA should be saved.
  2. .
  3. entered by the customer.
  4. with a collect request on the provided VPA.
  5. .

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.

POST
/customers
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.

email

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.

POST
/orders
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:

POST
/payments/validate/vpa
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:

POST
/payments/create/upi

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

section of the API Reference Guide.

description

optional

string Descriptive text of the payment.

contact

mandatory

string Phone number of the customer.

email

mandatory

string Email address of the customer.

Watch Out!

The email field is mandatory by default. However, you can contact the

to make it optional using a feature flag.

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.

  1. .
  2. .
  3. with the token selected by the customer.
  4. .

You should create an order before initiating the payment.

POST
/orders
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.

GET
/customers/:customer_id/tokens
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:

POST
/payments/create/upi
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?