UPI Integration - TPV
Integrate TPV through UPI using the procedure described in this section.
Prerequisites
Merchant Hosted or S2S (Seamless) integration has to be done as per the standard kit. For more information, refer to UPI Integration.
Step 1: Validate VPA
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, refer to Validate VPA Handle API.
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"
Validate VPA for Recurring Payment
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&var2={"validateAutoPayVPA":"1"}&hash=75uy573dce34375a5fa2970afa21023d53e1cf5b8cd80a6472poy9b7c964c7a5da9146c9007df8b7391cbaf2d7d7d91dcaae8bf1d19d1837315a3376d6dc827e"
Sample response
Success scenario
if successfully validated:
{
"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"
}
Step 2: Post the parameters to PayU
With the following parameters, make the transaction request with the customer’s bank account number to the PayU using the Collect Payment (_payment) API.
Environment
Test Environment | https://test.payu.in/_payment> |
Production Environment | https://secure.payu.in/_payment> |
Request parameters
Parameter | Description | Example |
keymandatory
|
String Merchant key provided by PayU during onboarding.
|
JPg***r |
---|---|---|
txnidmandatory
|
String The transaction ID is a reference number for a specific order that is generated by the merchant.
|
ypl938459435 |
amountmandatory
|
String The payment amount for the transaction.
|
10.00 |
productinfomandatory
|
String A brief description of the product.
|
iPhone |
firstnamemandatory
|
String The first name of the customer.
|
Ashish |
emailmandatory
|
String The email address of the customer.
|
[[email protected]](mailto:[email protected]) |
phonemandatory
|
String The phone number of the customer.
|
|
mandatory
|
String It defines the payment category for which you wish to perform TPV. For Net Banking, pg= 'UPI'.
|
UPI |
mandatory
|
String It defines the bank with which you wish to perform TPV using the bank code. The values can be any one of the following values:
|
UPI |
vpamandatory
|
String The VPA or UPI handle of the customer.
|
|
beneficiarydetailmandatory
|
JSON This is a JSON format text and there should be key named **beneficiaryAccountNumber** with the list of account numbers and the ifscCode key with the list of corresponding IFSC codes (in the same order as provided in the beneficiaryAccountNumber key). You can post up to five account details in this parameter.
|
Refer to beneficiarydetail JSON object fields |
api_version |
String The api_version "6" must be passed fro this parameter.
|
|
furlmandatory
|
String The success URL, which is the page PayU will redirect to if the transaction is successful.
|
|
surlmandatory
|
String The Failure URL, which is the page PayU will redirect to if the transaction is failed.
|
|
hashmandatory
|
String It is the hash calculated by the merchant. The hash calculation logic is:sha512(key|txnid|amount|productinfo|
|
|
address1optional
|
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.
|
|
address2optional
|
String The second line of the billing address.
|
|
cityoptional
|
String The city where your customer resides as part of the billing address.
|
|
stateoptional
|
String The state where your customer resides as part of the billing address,
|
|
countryoptional
|
String The country where your customer resides.
|
|
zipcodeoptional
|
String Billing address zip code is mandatory for the cardless EMI option.Character Limit -20
|
|
udf1optional
|
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.
|
|
udf2optional
|
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.
|
|
udf3optional
|
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.
|
|
udf4optional
|
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.
|
|
udf5optional
|
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.
|
beneficiarydetail JSON object fields
It must contain the list of account numbers and the ifscCode key with the list of corresponding IFSC codes (in the same order as provided in the beneficiaryAccountNumber key). You can post up to five account details in this parameter. For example:
{"beneficiaryAccountNumber":"002001600674|00000031957292212|00000035955239352|00000035955239352",
"ifscCode":"KTKB0000046|KTKB0000023|KTKB0000035|KTKB0000035"}
Checksum Logic for Hash
Step 3: Check the 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|beneficiarydetail|status||||||udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)
Store the mihpayid and txnid parameter values in response:PayU recommends you to make provisions to store the mihpayid and txnid parameter values (in the response) in your server as proof that TPV has been completed for a customer.
Sample response
The formatted response from PayU:
Array
(
[mihpayid] => 403993715524308315
[mode] => UPI
[status] => success
[unmappedstatus] => captured
[key] => JP***g
[txnid] => Job7NydtwPVAmy
[amount] => 10.00
[discount] => 0.00
[net_amount_debit] => 10
[addedon] => 2021-10-05 12:51:20
[productinfo] => iPhone
[firstname] => Ashish
[lastname] =>
[address1] =>
[address2] =>
[city] =>
[state] =>
[country] =>
[zipcode] =>
[email] => [email protected]
[phone] => 9876543210
[udf1] =>
[udf2] =>
[udf3] =>
[udf4] =>
[udf5] =>
[udf6] =>
[udf7] =>
[udf8] =>
[udf9] =>
[udf10] =>
[hash] => de4f82af65458c84080d6515c1a80d42af703be390346ef020974e520efeb4ab9ebe4752e63e70d6f00dedd671c663dfdb22d0f0c818c52790e911e8babd3f6e
[field1] => anything@payu
[field2] => Job7NydtwPVAmy
[field3] =>
[field4] => Ashish
[field5] => AXImAH1BxekGdTLY7qgjMXffAAjJj5Q75mY
[field6] =>
[field7] => Transaction completed successfully
[field8] =>
[field9] => Transaction completed successfully
[payment_source] => payu
[PG_TYPE] => UPI-PG
[bank_ref_num] => Job7NydtwPVAmy
[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.
Updated 4 days ago