API ReferenceIntegrationsKnowledge Base

Saved VPA in Server-to-Server Integration

In an online transaction using UPI collect flow, customers enter their virtual payment address (VPA) on the UI, open the respective UPI apps and complete the payment after successful two-factor authentication. Customers are redirected to your website after successful payment.

In this flow, it is likely that the customers enter invalid VPAs or forget their VPAs, which could lead to higher drop-off rates. In order to overcome this problem, Razorpay enables you to save the VPAs of a customer. The VPAs entered by the customer are stored and secured as tokens in Razorpay. This saves the customer the hassle of entering the VPA again for every transaction. Thereafter, on subsequent visits, the customers select the saved VPA of their choice and complete the payment.

Feature Enabmelemt:
This feature is not available by default. Contact our Support Team to get this feature enabled for your account.

User Flow🔗

The user flow for accepting payments using tokens is as follows:

  1. Customer enters the VPA to make UPI payments on your UI.
  2. The entered VPAs are saved as tokens by Razorpay.
  3. On a repeat visit to your site, all the tokens saved for a customer are displayed on the UI.
  4. From the displayed list of VPAs, customers select VPAs of their choice to complete the payment.

Integration Steps🔗

The steps required to integrate tokens in the payment flow are as follows:

Step 1: Create a Customer🔗

Create a customer, whose VPAs should be saved, with details such as email and contact.

/customers

Request Parameters🔗

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.
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.
Copycurl -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": "9123456789" }'
CopyRazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]"); JSONObject request = new JSONObject(); request.put("name", <name>); request.put("email", <email>); Customer customer = razorpayClient.Customers.create(request);
Copyimport razorpay client = razorpay.Client(auth=("YOUR_ID", "YOUR_SECRET")) client.customer.create(data=data)
Copy$api = new Api($key_id, $secret); $customer = $api->customer->create(array('name' => 'Gaurav Kumar', 'email' => 'gaurav.kumar@example.com'));
CopyRazorpayClient client = new RazorpayClient(your_key_id, your_secret); Dictionary<string, object> options = new Dictionary<string,object>(); options.Add("name", "Gaurav Kumar"); options.Add("contact", "9123456789"); options.Add("email", "gaurav.kumar@example.com"); options.Add("fail_existing", 0); Customer customer = Customer.Create(options);
Copyrequire "razorpay" Razorpay.setup('YOUR_KEY_ID', 'YOUR_SECRET') customer = Razorpay::Customer.create email: 'gaurav.kumar@example.com', contact: '9123456789' puts customer.id #cust_6vRXClWqnLhV14
Copyvar instance = new Razorpay({ key_id: 'YOUR_KEY_ID', key_secret: 'YOUR_SECRET' }) instance.customers.create({name, email, contact, notes})
Copy{ "id" : "cust_EIW4T2etiweBmG", "entity": "customer", "name" : "Gaurav Kumar", "email" : "gaurav.kumar@example.com", "contact" : "9123456789", "gstin": null, "created_at ": 1234567890 }

This step can be skipped if there are customers already created in your account.

Response🔗

The id obtained in the response should be sent as customer_id while creating the token.

Step 2: Create an Order🔗

An order must be created before initiating a payment on your Checkout.

/orders

Request Parameters🔗

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. List of supported currencies.
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”.
Copycurl -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" }'
Copy{ "id": "order_Ee0biRtLOqzRjP", "entity": "order", "amount": 200, "amount_paid": 0, "amount_due": 200, "currency": "INR", "receipt": null, "offer_id": null, "status": "created", "attempts": 0, "notes": [], "created_at": 1586789358 }

Response🔗

The id obtained in the response should be passed as order_id while creating the token.

Step 3: Create Tokens for a Customer🔗

While making the UPI collect payment, the customer enters the VPA on your UI. To store the VPA as a token, pass additional attributes in the create payment request:

customer_id
string Unique identifier of the customer. This can be obtained from the response of Step 1.
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.
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ -X POST https://api.razorpay.com/v1/payments/create/redirect \ -H "Content-Type: application/json" \ -d '{ "amount": "200", "currency": "INR", "email": "gaurav.kumar@example.com", "contact": "9123456789", "order_id": "order_Ee0biRtLOqzRjP", "method": "upi", "vpa": "9123456789@upi", "customer_id": "cust_EIW4T2etiweBmG", "save": 1 }'

Response🔗

The response contains an HTML page that is rendered in the customer's browser. The customer can now complete the payment by logging into the respective UPI app.

Step 4: Fetch all Tokens of the Customer🔗

All the card (if saved earlier) and VPA tokens of a customer can be retrieved.

/customers/:customer_id/tokens
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ -X GET https://api.razorpay.com/v1/customers/cust_EIW4T2etiweBmG/tokens
Copy{ "entity": "collection", "count": 2, "items": [ { "id": "token_EeroOjvOvorT5L", "entity": "token", "token": "4ydxm47GQjrIEx", "bank": null, "wallet": null, "method": "card", "card": { "entity": "card", "name": "Gaurav Kumar", "last4": "8430", "network": "Visa", "type": "credit", "issuer": "HDFC", "international": false, "emi": true, "expiry_month": 12, "expiry_year": 2022, "flows": { "otp": true, "recurring": true } }, "vpa": null, "recurring": false, "auth_type": null, "mrn": null, "used_at": 1586976724, "created_at": 1586976724, "expired_at": 1672511399, "dcc_enabled": false }, { "id": "token_EeO65VIv8BXZg5", "entity": "token", "token": "D7Qun28CcPwNVy", "bank": null, "wallet": null, "method": "upi", "vpa": { "username": "9123456789", "handle": "upi", "name": null }, "recurring": false, "recurring_details": { "status": "not_applicable", "failure_reason": null }, "auth_type": null, "mrn": null, "used_at": 1586872080, "created_at": 1586872080, "start_time": null, "dcc_enabled": false } ] }

Response🔗

Pass the token that contains the VPA details of the customer, token_EeO65VIv8BXZg5 in the above example, to the payment create request.

Step 5: Create Payments using Tokens🔗

Once the VPAs are tokenized, in all the repeat transactions on your site, customers can complete their UPI payments without having to enter their VPAs again.

Now, in each payment create request, instead of the vpa field, pass the following attributes:

customer_id
string Unique identifier of the customer.
token
string Token of the saved VPA, obtained in the previous step.
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ -X POST https://api.razorpay.com/v1/payments/create/redirect \ -H "Content-Type: application/json" \ -d '{ "amount": "100", "currency": "INR", "email": "gaurav.kumar@example.com", "contact": "9123456789", "order_id": "order_EAkbvXiCJlwheT", "method": "upi", "customer_id": "cust_EIW4T2etiweBmG", "token": "token_EeO65VIv8BXZg5" }'

Response🔗

The response contains an HTML page that is rendered in the customer's browser. The customer can now complete the payment by logging into the respective UPI app.

×