The UPI Seamless Integration allows merchants to process UPI payments directly through a server-to-server (S2S) flow without redirecting customers to external payment pages. This integration provides a smooth payment experience by handling UPI transactions programmatically using the customer's Virtual Payment Address (VPA).
When to Use UPI Seamless Integration
Use this integration when:
- You want to accept UPI payments without redirecting customers away from your platform
- Your customers prefer to stay on your application during the payment process
- You need to integrate UPI payments into mobile apps or web applications seamlessly
- You want to provide a faster checkout experience for UPI users
Environment
Test Environment | https://apitest.payu.in/v2/payments |
Production Environment | https://api.payu.in/v2/payments> |
Request header
Parameter | Description |
---|---|
date | The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT. |
authorization | The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description. |
authorization fields description
Field | Description |
---|---|
username | Represents the username or identifier for the client or merchant, for example smsplus. |
algorithm | Use SHA512 algorithm for hashing and send this as header value. |
headers | Specifies which headers have been used in generating the hash, for example date. |
signature | The HMAC signature generated using the specified algorithm. For more information, refer to hashing algorithm. |
hashing algorithm
You must hash the request parameters using the following hash logic:
Hash logic: sha512(<Body data>
+ '|' + date + '|' + merchant_secret)
Where <Body data>
contains the request body posted with the request.
Sample header code
var merchant_key = 'smsplus';
var merchant_secret = 'izF09TlpX4ZOwmf9MvXijwYsBPUmxYHD';
// date
var date = new Date();
date = date.toUTCString();
// authorization
var authorization = getAuthHeader(date);
function getAuthHeader(date) {
var AUTH_TYPE = 'sha512';
var data = isEmpty(request['data']) ? "" : request['data'];
var hash_string = data + '|' + date + '|' + merchant_secret;
var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
return `hmac username="${merchant_key}", algorithm="${AUTH_TYPE}", headers="date", signature="${hash}"`;
}
Request parameters
Parameter | Description | Example |
---|---|---|
accountId |
|
UMXDPA |
txnId |
|
ZP6267f0d2996ce |
order |
|
|
additionalInfo |
|
|
callBackActions |
|
|
billingDetails |
|
paymentMethod object fields description
Field | Description | Example |
---|---|---|
name |
|
UPI |
bankCode |
|
CC |
order object fields description
Parameter | Description | Example |
---|---|---|
productInfomandatory |
Product details. | Product details |
orderedItemoptional |
Details about the items ordered. | Array of Objects |
userDefinedFieldsoptional |
Custom fields for additional information. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10. For more information, refer to | Object |
paymentChargeSpecificationmandatory |
Includes amount and charges. For more information, refer to paymentChargeSpecification object fields description | Object |
paymentChargeSpecification object fields description
Parameter | Description | Example |
---|---|---|
pricemandatory |
The transaction amount. | 1000 |
netAmountDebitoptional |
Net amount to be debited. | 1000 |
taxSpecificationoptional |
Tax details of the product/order. | Object |
convenienceFeeoptional |
Fees format (e.g., CC:12). | CC:12 |
offersoptional |
Offers applied or available for the payment. | Object |
userDefinedFields object fields description
Field | Description |
---|---|
udf1 | User defined field. |
udf2 | User defined field. |
udf3 | User defined field. |
udf4 | User defined field. |
udf5 | User defined field. |
udf6 | User defined field. |
udf7 | User defined field. |
udf8 | User defined field. |
udf9 | User defined field. |
udf10 | User defined field. |
additionalInfo object fields description
Parameter | Description | Example |
---|---|---|
enforcePaymethodoptional |
Force a transaction with a specified method (e.g., CC, DC). | CC |
forcePgidoptional |
Forces identification for payment gateway. | PG123 |
partnerHoldTimeoptional |
Time held by the partner for the transaction. | 60 |
userCredentialsoptional |
Credentials for user authentication. | string |
userTokenoptional |
Token for the customer. | user_token_123 |
subventionAmountoptional |
Amount paid through EMI subvention payments. | 100 |
authOnlyoptional |
Initiates an authentication-only payment (true/false). | false |
createOrderoptional |
A flag to store the order details (true/false). | true |
txnS2sFlowoptional |
For defining seamless/non-seamless flows in handling payments. | seamless |
callbackActions object fields description
Parameter | Description | Example |
---|---|---|
successActionmandatory |
URL to be called on payment success. | https://example.com/success |
failureActionmandatory |
URL to be called on payment failure. | https://example.com/failure |
cancelActionmandatory |
URL to be called if user cancels the payment. | https://example.com/cancel |
codActionoptional |
URL for Cash on Delivery (COD) action. | https://example.com/cod |
billingDetails object fields description
Parameter | Description | Example |
---|---|---|
firstNamemandatory |
First name of the billing contact. | Ashish |
lastNameoptional |
Last name of the billing contact. | Kumar |
address1mandatory |
Primary billing address. | 123 Main Street |
address2optional |
Secondary billing address. | Apt 4B |
phoneoptional |
Phone number of the billing contact. | 9123456789 |
emailmandatory |
Email address of the billing contact. | [email protected] |
cityoptional |
City of the billing address. | Bharatpur |
stateoptional |
State of the billing address. | Rajasthan |
countryoptional |
Country of the billing address. | India |
zipCodeoptional |
Postal/Zip code of the billing address. | 321028 |
Sample request
curl --location 'https://apitest.payu.in/v2/payments' \
--header 'date: Thu, 27 Mar 2025 10:12:27 GMT' \
--header 'authorization: hmac username="smsplus", algorithm="sha512", headers="date", signature="ec84843a663143bb86c46b46c5c5ccae8c2cf6b9beb3e14d0be04119daffe83f2de2a8e28c20cb0c1c8e23d5e86e5cbdc5774e6a2e9a7186e1b8b9b6f8a8b9c8c1e3c4c5c1a3c7c9b7b2a1a3e7e8e9c8c1e3c4c5c1a3c7c9b7b2a1a"' \
--header 'Content-Type: application/json' \
--data-raw '{
"accountId": "KOEfPI",
"txnId": "Test123UPI",
"amount": 424.38,
"paymentMethod": {
"name": "UPI",
"bankCode": "NB",
"upi": {
"vpa": "xyz@axis"
}
},
"order": {
"productInfo": "Example Product",
"paymentChargeSpecification": {
"price": 424.38,
"netAmountDebit": 424.38
}
},
"additionalInfo": {
"vpa": "xyz@axis",
"txnFlow": "seamless",
"createOrder": "true"
},
"callBackActions": {
"successAction": "https://merchantwebsite.com/success",
"failureAction": "https://merchantwebsite.com/failure"
},
"billingDetails": {
"firstName": "John",
"phone": "9876543210",
"email": "[email protected]"
}
}'
Sample response
{
"result": {
"redirectUrl": "https://secure.payu.in/ResponseHandler.php",
"authAction": "https://api.payu.in/payments/21667772394/otps",
"paymentId": "21667772394",
"redirectTemplate": "<html><body><form name='payment_post' id='payment_post' action='https://upi.return.url' method='post'></form></body></html>",
"upi": {
"amount": "424.38",
"merchantVpa": "facebookadsmanager.payu@hdfcbank",
"intentURIData": "pa=facebookadsmanager.payu@hdfcbank&pn=Facebook India Online Services Private Limited&tr=21667772414&tid=PPPL21667772XXXXXXXXXXXX0016744c229&am=424.38&cu=INR&tn=UPIIntent",
"merchantName": "FacebookIndiaOnlineServicesPrivateLimited"
}
},
"orderId": "b5f2d8785768087678f4",
"status": "PENDING"
}
Response Parameters
Parameter | Description |
---|---|
txnId | This parameter contains the transaction ID of the transaction. |
paymentId | This parameter contains the payment ID of the transaction. |
message | This parameter contains the status message of the transaction. |
UPI-Specific Response Parameters
For UPI payments, the response includes additional UPI-specific fields:
Parameter | Description |
---|---|
upi.amount | Transaction amount for UPI payment |
upi.merchantVpa | Merchant's VPA for receiving payment |
upi.intentURIData | UPI intent data for payment apps |
upi.merchantName | Merchant name displayed in UPI apps |
orderId | Generated order ID if createOrder is true |
Implementation Steps
Step 1: Collect Customer VPA
Obtain the customer's Virtual Payment Address (VPA) through your application interface. The VPA format is typically username@bankname
(e.g., customer@paytm
, user@googlepay
).
Step 2: Create Payment Request
Submit the payment request with the customer's VPA and all required parameters as shown in the sample request above.
Step 3: Handle UPI Response
Process the response which contains:
- UPI Intent Data: Use for triggering UPI apps on mobile devices
- Payment ID: For tracking and verification
- Merchant VPA: For displaying payment details
Step 4: Verify Payment Status
Always call the Verify Payment API to confirm the final transaction status:
curl --location 'https://apitest.payu.in/v2/payments/verify' \
--header 'date: Thu, 27 Mar 2025 10:12:27 GMT' \
--header 'authorization: hmac username="smsplus", algorithm="sha512", headers="date", signature="your_signature_here"' \
--header 'Content-Type: application/json' \
--data-raw '{
"txnId": ["Test123UPI"]
}'
UPI Integration Flow Types
1. Intent-Based Flow
For mobile applications, use the UPI intent data to launch UPI-enabled apps:
- Extract
intentURIData
from the response - Trigger UPI app with the intent data
- Handle the callback from UPI apps
2. Collect Request Flow
For web applications or when customer needs to enter UPI PIN:
- Present QR code or payment details
- Allow customer to complete payment in their UPI app
- Poll for payment status updates
3. Direct VPA Flow
When customer provides VPA directly:
- Validate VPA format
- Submit payment request with VPA
- Handle authentication if required