UPI Integration

PayU allows you to collect payments using UPI handles. For the list of UPI providers supported, refer to UPI Handles.

Steps to Integrate:

1. Validate the UPI handle

Validate the card type using the Validae VPA API

2. Initiate the Payment to PayU

Initiate the payment to PayU with pg=UPI and bankcode=UPI

3. Check response from PayU

Check the response from PayU

4. Verify the payment

Verify the payment using verify_payment and monitor using webhooks

👍
Before you begin:
Register for an account with PayU before you start integration. For more information, refer to Register for a Merchant Account.

Step 1: Validate the UPI handle

When your customer makes payment through UPI, you can validate the customer's Virtual Payment Address (VPA) and then initiate payment. The validateVpa API is used to validate the UPI handle. Validate the VPA (UPI handle) using the validateVpa API. For Try-It experience of validateVpa API, refer to Validate VPA Handle API.

Environment


Test Environment	`<https://test.payu.in/merchant/postservice.php?form=2>`
Production Environment	`<https://info.payu.in/merchant/postservice.php?form=2>`

Sample request

Validate VPA

curl -X POST "https://test.payu.in/merchant/postservice?form=2" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "key=JP***g&command=validateVPA&var1=9999999999@upi&hash=75bb573dce34375a5fa2970afa21023d53e1cf5b8cd80a6472fff9b7c964c7a5da9146c9007df8b7391cbaf2d7d7d91dcaae8bf1d19d1837315a3376d6dc827e"

</Accordion>

<Accordion title="Sample response" icon="fa-reply">
**Success scenario**

if successfully validated:

```plaintext
{
   "status":"SUCCESS",
   "vpa":"9999999999@upi",
   "isVPAValid":1,
   "isAutoPayVPAValid":1,
   "isAutoPayBankValid":"NA",
   "payerAccountName":"ABC"
}

📘
Notes:

The payerAccountName parameter can be empty or NA or will have a payer name based on the value given by the bank.

If both isVPAValid and isAutoPayVPAValid is 1, you must initiate payment for Recurring Payments.

Ignore the isAutoPayBankValid parameter in the response.

Failure scenarios

If invalid VPA, the response is similar to the following:

{
 "status":"SUCCESS","vpa":"abc@upi","isVPAValid":0,"payerAccountName":"NA"
}

Invalid VPA but handle supporting SI (Autopay):

{
 "status":"SUCCESS","vpa":"abc@upi","isVPAValid":0,"isAutoPayVPAValid":1,"isAutoPayBankValid":"NA","payerAccountName":"NA"
}

Customer valid but handle not supporting SI (Autopay):

{
  "status":"SUCCESS","vpa":"xyz@freecharge","isVPAValid":1,"isAutoPayVPAValid":0,"isAutoPayBankValid":"NA","payerAccountName":"XYZ"
}

Neither customer valid nor handle supporting Autopay:

{
  "status":"SUCCESS","vpa":"xyz@freecharge","isVPAValid":0,"isAutoPayVPAValid":0,"isAutoPayBankValid":"NA","payerAccountName":"NA"
}

Sample VPA validation code

    	// JavaScript example for VPA validation before payment submission
    // This should be run on your server, not client-side

    async function validateVpa(vpa) {
        try {
            // Get hash from server endpoint
            const hashResponse = await fetch('/generate-vpa-hash', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ vpa })
            });
            const { hash } = await hashResponse.json();
            
            // Validate VPA with PayU
            const response = await fetch('https://test.payu.in/merchant/postservice?form=2', {
                method: 'POST',
                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                body: new URLSearchParams({
                    key: 'YOUR_MERCHANT_KEY',
                    command: 'validateVPA',
                    var1: vpa, // VPA to validate
                    hash: hash
                })
            });
            
            const result = await response.json();
            
            // Sample response:
            // {"status":1,"msg":"VPA is valid","isVPAValid":1,"isUPIBarredBank":0}
            // OR
            // {"status":0,"msg":"VPA is invalid","isVPAValid":0}
            
            return {
                isValid: result.isVPAValid === 1,
                message: result.msg
            };
        } catch (error) {
            console.error('VPA validation error:', error);
            return { isValid: false, message: 'Validation service error' };
        }
    }

# Once you have the hash, make the API call

curl -X POST "https://test.payu.in/merchant/postservice?form=2"       -H "Content-Type: application/x-www-form-urlencoded"       -d "key=YOUR_MERCHANT_KEY"       -d "command=validateVPA"       -d "var1=customer@upi"       -d "hash=$HASH"

Step 2: Initiate the payment to PayU

Post request syntax & composition

Post Request Syntax & Composition for UPI

<body>
<form action='https://test.payu.in/_payment' method='post'>
<input type="hidden" name="key" value="JP***g" />
<input type="hidden" name="txnid" value="t6svtqtjRdl34W" />
<input type="hidden" name="productinfo" value="iPhone" />
<input type="hidden" name="amount" value="10" />
<input type="hidden" name="email" value="[email protected]" />
<input type="hidden" name="firstname" value="Ashish" />
<input type="hidden" name="lastname" value="Kumar" />
<input type="hidden" name="pg" value="UPI" />
<input type="hidden" name="bankcode" value="UPI" />
<input type="hidden" name="vpa" value="test123@okhdfcbank" />
<input type="hidden" name="surl" value="your own success url" />
<input type="hidden" name="furl" value="your own failure url" />
<input type="hidden" name="phone" value="9988776655" />
<input type="hidden" name="hash" value="eabec285da28fd0e3054d41a4d24fe9f7599c9d0b66646f7a9984303fd6124044b6206daf831e9a8bda28a6200d318293a13d6c193109b60bd4b4f8b09c90972" />
<input type="submit" value="submit"> </form>
</body>
</html>

📘
Note
The above HTML code block is for Merchant Checkout integration on the UPI call for the test environment.

Request parameters

The following parameters vary for the UPI payment mode in the Collect Payment API (_payment API).

Environment


Test Environment	<https://test.payu.in/_payment>
Production Environment	<https://secure.payu.in/_payment>

📘
Reference:
For the Try It experience and response, refer to Collect Payment API - Merchant Hosted Checkout under API Reference.

Parameter	Description	Example
key `mandatory`	`String` Merchant key provided by PayU during onboarding.	JPg***r
txnid `mandatory`	`String` The transaction ID is a reference number for a specific order that is generated by the merchant.	ypl938459435
amount `mandatory`	`String` The payment amount for the transaction.	10.00
productinfo `mandatory`	`String` A brief description of the product.	iPhone
firstname `mandatory`	`String` The first name of the customer.	Ashish
email `mandatory`	`String` The email address of the customer.	[email protected]
phone `mandatory`	`String` The phone number of the customer.	9988776655
pg `mandatory`	`String` It defines the payment category that the merchant wants the customer to see by default on the PayU's payment page. This field must contain the value as "UPI" for UPI transactions.	UPI
bankcode `mandatory`	`String` Each payment option is identified with a unique bank code at PayU. The merchant must post this parameter with the corresponding payment option's bank code value in it. For a detailed list of bank codes, please contact the PayU Support.	UPI
vpa `mandatory`	`String` The VPA of the customer. For the list of bank name part of the handles, refer to UPI Handles. Reference: For the list of test card numbers for EMI, refer to Test Cards, UPI ID and Wallets	test123@okhdfcbank
furl `mandatory`	`String` The success URL, which is the page PayU will redirect to if the transaction is successful.	https://example.com/success
surl `mandatory`	`String` The Failure URL, which is the page PayU will redirect to if the transaction is failed.	https://example.com/failure
hash `mandatory`	`String` It is the hash calculated by the merchant. The hash calculation logic is: `sha512(key\|txnid\|amount\|productinfo\|firstname\|email\|udf1\|udf2\|udf3\|udf4\|udf5\|\|\|\|\|\|SALT)`	eabec285da28fd...
address1 `optional`	`String` The first line of the billing address. For Fraud Detection: This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.	123 Main Street
address2 `optional`	`String` The second line of the billing address.	Apt 4B
city `optional`	`String` The city where your customer resides as part of the billing address.	New Delhi
state `optional`	`String` The state where your customer resides as part of the billing address.	Delhi
country `optional`	`String` The country where your customer resides.	India
zipcode `optional`	`String` Billing address zip code is mandatory for the cardless EMI option. `Character Limit`: 20	110001
udf1 `optional`	`String` User-defined fields (udf) are used to store any information corresponding to a particular transaction. You can use up to five udfs in the post designated as udf1, udf2, udf3, udf4, udf5.	Custom Data 1
udf2 `optional`	`String` User-defined fields (udf) are used to store any information corresponding to a particular transaction. You can use up to five udfs in the post designated as udf1, udf2, udf3, udf4, udf5.	Custom Data 2
udf3 `optional`	`String` User-defined fields (udf) are used to store any information corresponding to a particular transaction.	Custom Data 3
udf4 `optional`	`String` User-defined fields (udf) are used to store any information corresponding to a particular transaction.	Custom Data 4
udf5 `optional`	`String` User-defined fields (udf) are used to store any information corresponding to a particular transaction.	Custom Data 5

Hashing

You must hash the request parameters using the following hash logic:

sha512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT)

For more information, refer to Generate Hash.

Sample request

    curl -X      POST "https://test.payu.in/_payment" -H      "accept: application/json" -H      "Content-Type: application/x-www-form-urlencoded" -d "key=JP***g&txnid=xdB9G7qYpfqszo&amount=10&firstname=PayU User&[email protected]&phone=9876543210&productinfo=iPhone&pg=UPI&bankcode=UPI&vpa=VPA-anything@payu&surl=https://apiplayground-response.herokuapp.com/&furl=https://apiplayground-response.herokuapp.com/&hash=649bc87e0e8ee7bbd1e930d43c99a9165eb9fa7a3f4542a33e8d66bd207a63d631708fd9781e56b133581f7dabeaa67baa5609d5e5c9990f986792d59e7d41cb"

Step 3: Check response from PayU

Hash validation logic for payment response (Reverse Hashing)

While sending the response, PayU takes the exact same parameters that were sent in the request (in reverse order) to calculate the hash and returns it to you. You must verify the hash and then mark a transaction as a success or failure. This is to make sure the transaction has not tampered within the response.

The order of the parameters is similar to the following code block:

sha512(SALT|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)

Sample Response

    Array
    (
        [mihpayid] => 403993715523409521
        [mode] => UPI
        [status] => success
        [unmappedstatus] => captured
        [key] => JPM7Fg
        [txnid] => 5jJ9xRceXX1ydT
        [amount] => 10.00
        [discount] => 0.00
        [net_amount_debit] => 1000
        [addedon] => 2021-07-02 15:03:50
        [productinfo] => iPhone
        [firstname] => PayU User
        [lastname] => 
        [address1] => 
        [address2] => 
        [city] => 
        [state] => 
        [country] => 
        [zipcode] => 
        [email] => [email protected]
        [phone] => 9876543210
        [udf1] => 
        [udf2] => 
        [udf3] => 
        [udf4] => 
        [udf5] => 
        [udf6] => 
        [udf7] => 
        [udf8] => 
        [udf9] => 
        [udf10] => 
        [hash] => 716f92a6452adadba68d133ba7f5ca3f3403f03f554e3ef850911f3e6727ee73402b249054170ad276c8b55ca12368a5e27cc69ffb0642ef6403dae9a5708794
        [field1] => vpa-anything@payu
        [field2] => 5jJ9xRceXX1ydT
        [field3] => 
        [field4] => PayU User
        [field5] => AXIhh4ExnaJ9dKiJvPxsewHwxMMmT3ba7UY
        [field6] => 
        [field7] => Transaction completed successfully
        [field8] => 
        [field9] => Transaction completed successfully
        [payment_source] => payu
        [PG_TYPE] => UPI-PG
        [bank_ref_num] => 5jJ9xRceXX1ydT
        [bankcode] => UPI
        [error] => E000
        [error_Message] => No Error
    )

Step 4: Verify the payment

Upon receiving the response, we recommend performing a reconciliation step to validate all transaction details.
You can verify your payments using either of the following methods:

Configure the webhooks to monitor the status of payments.
Webhooks enable a server to communicate with another server by sending an HTTP callback or message.
These callbacks are triggered by specific events or instances and operate at the server-to-server (S2S) level.

👉 For more details, refer to Webhooks for Payments.

Recommended integrations for UPI

Recurring Payments: Enable recurring payments or subscriptions for wallets. For more information, refer to Recurring Payments Integration.
- Offers: Configure offers for cards on Dashboard and then collect payments with offers. For more information, refer to Offers Dashboard and Offers Integration APIs

Before you begin:

Step 1: Validate the UPI handle

Notes:

Step 2: Initiate the payment to PayU

Note

Request parameters

Reference:

Hashing

Step 3: Check response from PayU

Hash validation logic for payment response (Reverse Hashing)

Step 4: Verify the payment

Recommended integrations for UPI

EXAMPLE QUESTIONS