1. Home
  2. Docs
  3. Developers Guide
  4. Private: Payment Products
  5. Recurring Payments

Recurring Payments

PayU’s recurring platform allows merchant to offer standing instruction feature for Credit, selected Debit cards and Net Banking through various integration methods. The feature is intended to automate repeat payments in Subscription Business where billing amount and billing cycle is usually fixed and consumer’s preferred payment instrument (Credit Card / Debit Card / Net Banking) is used to charge for subscribed service regularly.

Recurring payments readily support Cards and Bank payment methods. However, there are slight changes in both the flows as explained in detailed in following sections.

Cards Recurring platform

Since recurring payments don’t require consumer’s involvement for completing transaction, they are processed without CVV and 2nd factor authentication. This results into frictionless payment experience given the fact that consumer has already provided his/her consent for allowing merchant to charge his card regularly. Since recurring payments don’t have 2nd factor authentication, there are strict guidelines around offering the same to consumers by RBI as stated below –

• The first transaction must go through a standard 2FA flow (OTP / MasterCard Secure password / Verified by Visa Password) where consumer’s consent for further recurring payments needs to be taken either by merchant (seamless flow) or PayU (non-seamless flow)

• Once consent is taken then merchant can use either S2S APIs or File Upload utility of PayU to charge consumer over recurring basis going forward without 2FA

How Recurring Payment works in case of Cards?

Consumer lands on merchant website and proceeds for payment.

• Merchant presents an option to sign up for recurring platform where consumer needs to provide his/her consent.

• Billing details like amount, frequency, start date and end date of the subscription needs to be presented to customer and passed to PayU during payment request.

• Once consumer validates subscription plan and enters preferred card details, consumer is redirected to 3DS flow where authentication and authorization process is taken place.

• There are couple of ways to process First transaction or Consent transaction and taking consumer’s consent – o Consent transaction can be actual subscription for 1st billing cycle so consumer will be charged for whole amount through 3DS (2 factor) flow and sub-sequent transactions will be processed through recurring payment

o Consent transaction can be a penny transaction (5rs) where consumer’s card is taken on file along with consent and then amount is refunded back by merchant on calling Refund API. This is popular in cases where merchant is offering free services for 1st billing cycle and then charges sub-sequent bills through recurring payments

• Once consumer’s consent is taken then consumer’s card details are saved in PayU’s secure Vault and a card token is generated.

• This card token is returned to merchant in the payment response along with PayU’s id. Merchant is supposed to map this PayU Id it against consumer’s profile so that henceforth it can be used charging consumer through recurring platform.

• Please note that the card token is not actual card number and hence merchant is not having any PCI DSS hassles in storing the same at his end

Currently Standing Instruction is supported for following payment instruments

• Credit Card (scheme vise, all issuers are supported)

1. Visa

2. Master Card

3. American Express

4. Diners

• Debit Card (Only Visa and Master Card schemes and selected issuers)

1. ICICI Bank

2. Kotak Bank

3. Canara Bank

4. Citi Bank

5. Deutsch Bank Bank

6. Standard Chartered Bank

7. Dena Bank Bank

8. Axis Bank (required additional permission)

9. HDFC Bank (required additional permission)

Net Banking Recurring (e-Mandate and e-NACH)

Net Banking recurring like cards is processed seamlessly without customer’s intervention without any 2nd factor authentication.

There are 2 common terms when it comes Net Banking recurring – e-Mandate and e-NACH. Let’s look at both in detail

On higher level there are 2 transaction types –

• Registration transaction (also called e-Mandate transaction)

• Payment transaction (also called e-NACH transaction or SI transaction)

Registration Transaction (e-Mandate) –

• This is usually 0 Rs. transaction and hence it is called as registration transaction.

• Merchant presents an option to sign up for recurring platform where consumer needs to provide his/her consent.

• Billing details like amount, frequency, start date and end date of the subscription needs to be presented to customer and passed to PayU during payment request.

• On redirecting to PayU, customer selects preferred bank and enters account details like account number, name of the account and account type– SAVINGS or CURRENT

• Once entering the same, customer is redirected to bank’s login page and authenticates himself with either net banking username and password or debit card number and ATP PIN depending upon preferred bank

• On successful authentication, customer sees registration details like billing amount, billing frequency, start date and end date of the subscription plan

• Customer approves the subscription details from bank page and redirected back to PayU.

• The response of the registration process is not real time but offline. Hence PayU on real time, PayU returns “Pending” status with message “Mandate Initiated Successfully” along with unique PayU’s id.

• In most of cases, the confirmation of registration transaction is not received from banks on T+2 and same is notified to merchants by triggering Web hook API

SI Transaction (e-NACH) –

• Once registration is successful, merchant can call recurring payment API of PayU by passing unique PayU id received in the response of registration transaction.

• Since most of the time even payment processing for Net Banking recurring is offline, all the transaction request coming from merchant are queued and forwarded to acquirers through file

• At the end of the day response of transaction is received over SFTP from acquirers which is then stored in PayU’s dB and same is communicated to merchant over webhook API call.

• Similar to registration transaction, TAT for receiving either Success or Failure case of eNACH transactions is T+2

Here are banks supported for Net Banking recurring platform –

1. HDFC Bank

2. ICICI Bank

3. Axis Bank

4. Bank OF Baroda

5. Kotak Mahindra Bank

6. Punjab National Bank

7. YES Bank

8. City Union Bank

9. IndusInd Bank

10. IDFC Bank

11. Central Bank of India

12. IDBI First Bank

13. Tamilnad Mercantile Bank

14. Indian Overseas Bank

15. RBL Bank

16. Bank of Maharashtra

17. Deutsch Bank

18. PayTm Payments Bank

19. Ujjivan Small Finance Bank

20. Equitas Small Finance Bank

21. Federal Bank

Understanding Consent / Registration Transaction

Consent transaction is nothing, but customer’s explicit permission given to merchant for charging preferred payment method for subscribed payment plan. It is a standard guideline for

setting up any kind of subscription service and is mandatory for merchants to implement as per

RBI

There are couple of ways to perform Consent transaction –

• Consent transaction can deduct 1st Instalment Amount or Deposit Amount depending upon merchant’s use case and then subsequent transactions can be processed as per over recurring interface without customer’s intervention.

Note – This use case is supported primarily on Credit and Debit cards and only selected Net Banks (ICICI and HDFC). So, it is advisable to speak with Integration team and understand how different payment methods can be leveraged in implementing 1st instalment flow.

• Consent transaction can be a 0.00 Rs transaction (in case of Net Banking) or Penny transaction of min. 1.00 Rs (in case of Cards) where payment instrument is taken, and subscription is setup. This can be considered as “Free trial” use case where subsequent payments can be trigged over recurring interface without customer’s intervention

Note – The difference of amount between Net Banking (0.00 Rs) and Cards (min 1.00

Rs) is due to nature of architecture behind these payment methods. In case of Net Banking, the platform is built on top of existing ESC debit system, so consent is considered as just registration. Whereas in Cards, the transaction still flows throw Card schemes where 0.00 Rs transaction doesn’t supported today.

The result of Consent transaction is storing customer’s preferred payment instrument in PayU’s secure vault and generating unique PayU Id which needs be associated with Subscription at merchant’s eco system.

Please note that this PayU Id is mandatory to charge customer over recurring platform for all the subsequent transactions.

From integration approach perspective, Consent transaction can be integrated in either of the below approach.

§ Seamless Integration

§ Non-Seamless Integration

In case of Seamless flow merchant needs to present card entry screen (in case of Cards) or

Account details entry screen along with Bank preference on checkout page and consumer’s consent needs to be taken by merchant. This is applicable for PCI DSS compliant merchant so that card details are handled at merchant’s site directly.

Also, in case of Seamless flow, it is recommended to use PayU’s BIN API to detect card scheme and card issuer of the credit / debit card entered by customer. This helps to filter out not applicable card types for recurring before even calling Consent interface of PayU.

In case of Non-Seamless flow, merchant needs to pass billing details to PayU during Consent transaction however card details / bank account details will be taken by PayU as shown below –

The steps for integrating with PayU can technically be described as below:

1. To start off the integration process, you would be provided a test setup by PayU where you would be given a test merchant account and test credit card credentials to have a first-hand experience of the overall transaction flow. Here, you need to make the transaction request on our test server (and not the production server). Once your testing is complete, then only you will be ready to move to the PayU production server.

2. To initiate a transaction, the merchant needs to generate a POST REQUEST – which must consist of mandatory and optional parameters mentioned in the later section. This POST REQUEST needs to be hit on the below mentioned PayU URLs:

For PayU Test Server:

POST URL: https://test.payu.in/_payment

For PayU Production Server:

POST URL: https://secure.payu.in/_payment

3. In the merchant-initiated POST REQUEST, one of the mandatory parameters is named as hash. The details of this hash parameter have been covered in the later section. But it is critical for the merchant to calculate the hash correctly and post to us in the request.

4. When the transaction POST REQUEST hits the PayU server, a new transaction entry is created in the PayU Database. To identify each new transaction in the PayU Database, a unique identifier is created every time at PayU’s end.This identifier is known as the PayU ID (or mihpayid).

5. With the POST REQUEST, customer would be re-directed to PayU’s payment page. Customer now selects the particular payment option on PayU’s page (Credit Card/Debit Card/Net Banking /Sodexo etc.) and clicks on ‘Pay Now’. PayU redirects the customer to the chosen payment method. The customer goes through the necessary authorization/authentication process at bank’s login page, and the bank gives the success/failure response back to PayU.

6. PayU marks the transaction status on the basis of response received from Bank. PayU provides the final transaction response string to the merchant through a POST RESPONSE. The parameters in this response are covered in the subsequent sections.

7. In the POST RESPONSE sent by PayU, you would receive the final status of the transaction. You will receive the hash parameter here also. Similar to step 3, it is absolutely crucial to verify this hash value at your end and then only accept/reject the invoice order. This is done to strictly avoid any tampering attempt by the user.

Disclaimer

  1. Test URL: The Test URL is provided to PayU merchants to test the integration of their server with that of PayU or Bank. It is understood that since this is merely a Test URL, the Merchant should not treat any transactions done on this Test server as live and should not deliver the products/services with respect to any such test transactions even in the case your server receives a successful transaction confirmation from PayU/Bank.
  2. Merchants are herein forth requested to set up required control checks on their (merchant) systems/servers to ensure that only those transactions should get routed to the PayU test server which are initiated with sole intention of test the environment.

Standard Request Parameters to be passed for Consent Transactions

Parameter (All mandatory)   Description  
key   This parameter is the unique Merchant Key provided by PayU for your merchant account. The Merchant Key acts as the unique identifier (primary key) to identify a Merchant Account in our database. While posting the data to us, you need to put this Merchant Key value for you merchant account in this parameter. Also, please note that during integration with PayU, you would need to first integrate with our Test Server.   PayU would be providing you the necessary Merchant Key for test server.   Please do not use your live account’s merchant key here. It would not work. Once testing is done, you are ready to move to live server. Here, you would need to replace the test Merchant Key with Live Merchant Key. This is a critical step for successfully moving to live PayU server.   Example: smsplus  
txnid   This parameter is known as Transaction ID (or Order ID). It is the order reference number generated at your (Merchant’s) end. It is an identifier which you (merchant) would use to track a particular order. If a transaction using a particular transaction ID has already been successful at PayU, the usage of same Transaction ID again would fail. Hence, it is essential that you post us a unique transaction ID for every new transaction. (Please make sure that the transaction ID being sent to us hasn’t been successful earlier. In case of this duplication, the customer would get an error of ‘duplicate Order ID’).   Data Type – Varchar Character Limit – 25 characters Example: fd3e847h2
   
amount   This parameter should contain the payment amount of the particular transaction.   Note: Please type-cast the amount to float type Example: 10.00   Depending upon merchant use case, this value will vary.   It can be either 0 Rs (for Net Banking) or min 1 Rs (for Cards) in penny transaction use case    In case of 1stinstallment use cases, this amount can be equal to initiate setup amount, but this use case will be supported only against selected Net banks (ICICI and HDFC) and all Credit / Debit Cards  
productinfo This parameter should contain a brief product description. It should be a string describing the product (The description type is entirely your choice).   Data type – Varchar Character Limit – 100 characters Example: tshirt100  
firstname   Self-Explanatory (Must contain the first name of the customer)   Data Type – Varchar Character Limit – 60 characters Example: Ankit  
email   Self-explanatory (Must contain the email of the customer)   Data type – Varchar Character Limit – 50   Example: ankitverma@gmail.com   This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.   Also, MIS reporting is shared with few issuing banks where email and mobile number is used to keep track of users using SI transactions  
phone   Self-explanatory (Must contain the phone number of the customer)   Data type – Varchar Character Limit – 50 (numeric value only) Example:9843176540   This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information Also, MIS reporting is shared with few issuing banks where email and mobile number is used to keep track of users using SI transactions
surl   Success URL – This parameter must contain the URL on which PayU will redirect the final response if the transaction is successful.   The response handling can then be done by you after redirection to this URL  
furl   Failure URL – This parameter must contain the URL on which PayU will redirect the final response if the transaction is failed.   The response handling can then be done by you after redirection to this URL  
api_version Always needs to be passed as 7  
si Always needs to be passed as 1  
user_credentials   Parameter to define the unique customer Id. Its format is <key: unique_identifer>   Example – gtKFFx: vikas@test.com, gtKFFx:9999999999   PayU will store consumer’s payment details against this user identifier and return an encrypted card token in the payment response as explained in document further.   This parmater is not mandatory in case of Net Banking recurring  
free_trial **    This is mandatory only if merchant wants to support free trial use case with card and net banking together on non-seamless integrations   In this case, PayU adjusts transaction amount as 2 Rs for cards and 0 Rs for Net Banking registration irrespective of what amount is passed against amount field in the request.    This parameter has no significance in case of seamless flow
   
si_details This parameter represents mandatory details which need to be passed to during registration transaction from merchant system to PayU.    Please note that it is mandatory as per latest RBI guidelines to pass this information to payment processor so that same can be forwarded to acquirers and issuers ( for more details please refer – https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=11668&Mode=0   This is JSON object and it includes set of parameters are described below –  
  billingCycle Billing Cycle defines whether customer needs to be charged over Daily, Weekly basis, Monthly or Yearly basis or one time Sample Values –  DAILYWEEKLYMONTHLYYEARLYONCEADHOC billingCycle = ONCE is used when merchant wants to execute Split / Partial payment use cases where partial amount is paid upfront during Consent transaction and reaming amount needs to be paid on later.  billingCycle = ADHOC is used in use cases like post-paid bills where there is no definite billing cycle and billing amount.    
billingInterval Billing Interval is closely coupled with value of “billingCycle” and denotes at what frequency, the subscription plan needs to be executed. For example, if merchant wants to run a biweekly subscription then values will be as below billingCycle = WEEKLY
      billingInterval = 2 So, customer will be charged once in every 2 weeks. For monthly subscriptions, parameter values need to be sent in request are – billingCycle = MOHTHLYbillingInterval = 1 Similarly, by keeping below values customer will be charged once in every 3 days – billingCycle = DAILYbillingInterval = 3 In some use cases if, billingCycle is required to be used as ONCE or ADHOC, then billingInterval needs to be always passed as “1” as shown in below example – billingCycle = ONCEbillingInterval = 1   billingCycle = ADHOCbillingInterval = 1    
billingAmount   Billing amount in XX. XX format In use cases where billingCylce = ADHOC, then amount passed is treated as maximum amount since here billing amount and billing cycle varies as per usage of the subscription service. In this case, merchant is free to charge any amount for customer up to amount specified in defined subscription call  
billingCurrency Billing currency. Need to be passed as “INR”   
paymentStartDate Start Date of the billing plan. Format should be YYYY-MM-DD
       
    paymentEndDate            End Date of the billing plan. Format should be YYYY-MM-DD   Please note that it is important to pass correct end date to PayU. Depending upon start date and end date, number of payment iterations are internally calculated and same information is passed to acquirers / banks     For a yearly plan starting from 1st Jan 2019, having monthly billing amount 100 Rs, the plan details look like below –   {“billingAmount”: “100.00”,”billingCurrency”: “INR”,”billingCycle”: “MONTHLY”,”billingInterval”: 1,”paymentStartDate”: “2019-09- 01″,”paymentEndDate”: “2019-12-01”}   In above example, number of charges executed over recurring against customer’s payment instrument will be 12, once per month.   For a quarterly plan starting from 20th September 2019 for next 2 years, having billing amount as 5000 Rs will look like as below –   {“billingAmount”: “5000.00”,”billingCurrency”: “INR”,”billingCycle”: “MONTHLY”,”billingInterval”: 3,”paymentStartDate”: “2019-09- 20″,”paymentEndDate”: “2021-09-20”}   In above example, number of charges executed over recurring against customer’s payment instrument will be 9, once per 3 months.  
hash Hash is a crucial parameter used to ensure that any date is not tampered while redirecting customer form merchant website to PayU’s payment interface while registration transaction.   It is SHA512 hash generated by encrypting values of merchant key, txnid, amount, productinfo, firstname, email, udf and si_details by merchant salt.   In case of registration transaction, the formula is used to calculate this hash is as below –  
  HASH = SHA512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4 |udf5||||||si_details|SALT)   For example –    HASH = SHA512(a2cqBC|fa3359f205d621c07383|2|Product Info|PayuAdmin|test@example.com|||||||||||{“billingAmount”: “150.00”,”billingCurrency”: “INR”,”billingCycle”: “WEEKLY”,”billingInterval”: 1,”paymentStartDate”: “2019-09-18″,”paymentEndDate”: “2020-1020”}|dEvD9ABD)   HASH = 8541bbbcce8bd2eb71abfaf697b901e23b09a4f818028cb9fef4bad36f989f95 87685a6177c1444c484ebb071dc2e3f13db38237b766310605faaa0e8bfd8e14  

For your reference, please find sample code below which shows the basic set of parameters being posted. Please execute this piece of code in browser to observe the POST request being re-directed to PayU page and then you can form the complete transaction request in your code base (with the mandatory and optional parameters)

<html>
<body>
<form action='https://test.payu.in/_payment'method='post'>
<input type="hidden"name="firstname"value="Vikas Kumar" />
<input type="hidden"name="lastname"value="" />
<input type="hidden"name="surl"value="https://www.google.com" />
<input type="hidden"name="phone"value="9999999999" />
<input type="hidden"name="key"value="C0Dr8m" />
<input type="hidden"name="hash"value = 
"c2522a8d561e7c52f7d6b2d46c96b924afac8554313af4b80edef3e237e179bd6e202
0e8 c548060306d9fa2cf5c75c35205bcc4b09bcf5b9a9becec8de2952d0"/>
<input type="hidden"name="curl"value="http://www.google.com" />
<input type="hidden"name="furl"value="https:/www.yahoo.in" />
<input type="hidden"name="txnid"value="PLS-10061-3" />
<input type="hidden"name="productinfo"value="SAU Admission 2014" />
<input type="hidden"name="amount"value="5.00" />
<input type="hidden"name="email"value="chota.bheem@gmail.com" /><input type= "submit"value="submit">
</form>
</body>
</html>

Extra Parameters required for Seamless flow

Apart from above standard parameters, below are the extra mandatory parameters required in the payment request to perform Consent transaction in case of Seamless flow if as merchant is not using PayU’s payment pages and card / bank details are accepted by merchant before sending request to PayU.

Parameters (mandatory)   Description  
pg   In case of SI, value will be CC in case of Credit Cards and DC in case of selected Debit cards which support SI.   Please note that NOT all Debit Cards support SI. Hence while passing this value, merchant needs to confirm what issuers are supporting Debit Card SI with PayU’s team and then only pass only applicable Debit Cards for SI by using BIN APIs   In case of Net Banking recurring, this value needs to be passed as ENACH  
bankcode   This parameter would contain the code indicating the payment option used for the transaction.   For example, in Debit Card mode, there are different options like Visa Debit Card, Mastercard, Maestro etc.   For each option, a unique bankcode exists and it would be returned in this bankcode parameter.   For example, Visa Debit Card – VISA, Master Debit Card – MAST   In case of Net Banking recurring, this value will represent bank codes. Please refer table below to know list of banks supported and respective bank codes.    For example – KKBKENCC  
ccnum   This parameter must contain the card (credit/debit) number entered by the customer for the transaction.   Not required to be passed for Net Banking recurring registration  
ccname   This parameter must contain the name on card – as entered by the customer for the transaction.   Not required to be passed for Net Banking recurring registration  
ccvv   This parameter must contain the cvv number of the card – as entered by the customer for the transaction.   Not required to be passed for Net Banking recurring registration  
ccexpmon   This parameter must contain the card’s expiry month – as entered by the customer for the transaction. Please make sure that this is always in 2 digits.   For months 1-9, this parameter must be appended with 0 – like 01, 02…09.   For months 10-12, this parameter must not be appended – It should be 10, 11 and 12 respectively.   Not required to be passed for Net Banking recurring registration  
ccexpyr   The customer must contain the card’s expiry year – as entered by the customer for the transaction. It must be of 4 digits.   For example – 2017, 2029 etc.   Not required to be passed for Net Banking recurring registration  
beneficiarydetail This object represents bank account details of the customer which involves account number, name on the account and account type and needs to be passed if recurring transaction needs to be setup against Net Banking    beneficiaryName   Registered name against customer’s account   beneficiaryAccountNumber   Account number against which recurring transactions need to be executed   beneficiaryAccountType   SAVINGS or CURRENT   Here is sample example – 
    {“beneficiaryName”: “Sachin Tendulkar”,”beneficiaryAccountNumber”: “1211450021”,”beneficiaryAccountType”: “SAVINGS”}    

Bank Codes for Net Banking Recurring

Sr. No. Bank name Code against bankcode parameter  
1 State Bank Of India SBINENCC
2 HDFC Bank HDFCENCC
3 ICICI Bank ICICENCC
4 Axis Bank UTIBENCC
5 Bank OF Baroda BARBENCC
6 Kotak Mahindra Bank KKBKENCC
7 Punjab National Bank PUNBENCC
8 YES Bank YESBENCC  
9 City Union Bank CIUBENCC
10 IndusInd Bank INDBENCC
11 IDFC Bank IDFBENCC
12 Central Bank of India CBINENCC
13 IDBI First Bank IBKLENCC
14 Tamilnad Mercantile Bank TMBLENCC
15 Indian Overseas Bank IOBAENCC
16 RBL Bank RATNENCC
17 Bank of Maharashtra MAHBENCC
18 Deutsch Bank DEUTENCC
19 PayTm Payments Bank PYTMENCC
20 Ujjivan Small Finance Bank USFBENCC
21 Equitas Small Finance Bank ESFBENCC
22 Federal Bank FDRLENCC
23 IDBI Bank IBKLENCC
24 IDFC Bank IDFBENCC
25 Oriental Bank Of Commerce ORBCENCC
26 Andhra Bank ANDBENCC
27 United Bank Of India UTBIENCC
28 Standard Chartered Bank SCBLENCC
29 Canara Bank CNRBENCC
30 Karnataka Bank KARBENCC
31 Citi Bank CITIENCC
32 South Indian Bank SIBLENCC
33 AU Small Finance Bank Ltd AUBLENCC

Important Things to remember: Characters allowed for parameters

  • For parameters address1, address2, city, state, country, product info, email, and phone following characters are allowed:
  • Characters: A to Z, a to z, 0 to 9
  • -(Minus)
  • _ (Underscore)
  • @ (At the Rate)
  • / (Slash)
  • (Space)
  • . (Dot)

If the merchant sends any other special characters, then they will be automatically removed. The address parameter will consider only first 100 characters.

Formula for hash (checksum) after transaction     

This time the variables are in reverse order and status variable is added between salt and udf1.

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

It is mandatory that the hash (or checksum) is computed again after you receive response from PayU and compare it with post back parameters below. This will protect you from any tampering by the user and help in ensuring safe and secure transaction experience.

For PHP

Example code:

$output = hash (“sha512”, $text)

For .NET

http://msdn.microsoft.com/en-us/library/system.security.cryptography.sha512.aspx

Example code:

byte[] data = new byte[DATA_SIZE];byte[] result;

SHA512 shaM = new SHA512Managed();

result = shaM.ComputeHash(data);

For JSP

Example code:

importjava.io.FileInputStream;import java.security.MessageDigest;public class SHACheckSumExample {

public static void main(String[] args) throws Exception {

MessageDigest md = MessageDigest.getInstance(“SHA512”);FileInputStreamfis = new FileInputStream(“c:\\loging.log”);byte[] dataBytes = new byte[1024];

intnread = 0;while ((nread = fis.read(dataBytes)) != -1) {

md.update(dataBytes, 0, nread);

};

byte[] mdbytes = md.digest();

StringBuffersb = new StringBuffer();//convert the byte to hex format method      

for (inti = 0; i<mdbytes.length; i++)

{

sb.append(Integer.toString((mdbytes[i] & 0xff) +

0x100, 16).substring(1)); }

System.out.println(“Hex format : ” + sb.toString()); //convert the byte to hex format method 2 StringBufferhexString = new StringBuffer();for (inti=0;i<mdbytes.length;i++) hexString.append(Integer.toHexString(0xFF &mdbytes[i]));

}

System.out.println(“Hex format : ” + hexString.toString());

}

Response Parameters posted by PayU to Merchant

Parameters Descriptions  
mihpayid It is a unique reference number created for each transaction at PayU’s end for given Registration request.   In case of recurring transaction, this value will be further used as a reference point always against given payment instrument holder.   So, it is imperative to map this value with user profile at merchant end so that same will be used in the recurring transaction platform.  
mode This parameter describes the payment category by which the transaction was completed/attempted by the customer. The values are mentioned below: CC or DC or ENACH  
status This parameter gives the status of the transaction. Hence, the value of this parameter depends on whether the transaction was successful or not. Merchant must map the order status using this parameter only.   The values are as below: If the transaction is successful, the value of ‘status’ parameter would be ‘success’.   The value of status as ‘pending’ will be received in case of Net Baking registration.  This means the registration request has been successfully initiated with the bank and system is waiting for final confirmation which can be received within T+2.   The value of status as ‘failure’ must be treated as a failed transaction only.    For charging any payment instrument over recurring platform the status of Consent transaction should be returned as success.  
key   This parameter would contain the merchant key for the merchant’s account at PayU. It would be the same as the key used while the transaction request is being posted from merchant’s end to PayU.  
txnid   This parameter would contain the transaction ID value posted by the merchant during the transaction request.  
amount   This parameter would contain the original amount which was sent in the transaction request by the merchant.  
productinfo   This parameter would contain the same value of productinfo which was sent in the transaction request from merchant’s end to PayU  
email   This parameter would contain the same value of email which was sent in the transaction request from merchant’s end to PayU  
phone   This parameter would contain the same value of phone which was sent in the transaction request from merchant’s end to PayU  
hash   This parameter is crucial and is similar to the hash parameter used in the transaction request send by the merchant to PayU.   PayU calculates the hash using a string of other parameters and returns to the merchant.   The merchant must verify the hash and then only mark a transaction as success/failure. This is to make sure that the transaction hasn’t been tampered with.   The calculation is as below: sha512(SALT|status||||||udf5|udf4|udf3|udf2|udf1|email|firstn ame|productinfo|amount|txnid|key)   The handling of udf1 – udf5 parameters remains similar to the hash calculation when the merchant sends it in the transaction request to PayU.   If any of the udf (udf1-udf5) was posted in the transaction request, it must be taken in hash calculation also. If none of the udf parameters were posted in the transaction request, they should be left empty in the hash calculation too.  
error   For the failed transactions, this parameter provides the reason of failure. Please note that the reason of failure depends upon the error codes provided by different banks and hence the detailing of error reason may differ from one transaction to another.  
  The merchant can use this parameter to retrieve the reason of failure for a particular transaction.  
bankcode   This parameter would contain the code indicating the payment option used for the transaction. For example, in Debit Card mode, there are different options like Visa Debit Card, Mastercard, Maestro etc. For each option, a unique bankcode exists. It would be returned in this bankcode parameter.    
bank_ref_num   For each successful transaction – this parameter would contain the bank reference number generated by the bank.  
payment_source   Value needs to be returned as sist
cardToken   This is the secure card token generated by PayU against user_credentails parameter sent by merchant and returned in the payment response.   This value will be used by merchant going forward for charging consumer over recurring payments, so it is imperative for merchant to map this against right consumer profile.   Sample value – f59f6vc6f2e7d18c3d476  

Capturing successful registration response for Cards – 

Please note that registration transaction must be successfulin order to make it eligible for Recurring platform. 

In case of Cards, merchant must verify the below 4 values received in the payment response from PayU before considering it as successfully registered for recurring plan / subscription for customer –

  • status = success (Indicates that transaction is successful)
  • card_token = <Must be a non-empty string value>(Indicates that carddetails are saved correctly in PayU Database)
  • payment_source = sist(Indicates that card details have been markedcorrectly for Standing Instruction)
  • mihpayid = <Must be non-empty value>(Indicates PayU’s transactionacknowledgement for Consent transaction)

If any of the above 4 checks are not satisfied, that means the transaction hasn’t been correctly authorized for Standing Instruction. The merchant must not consider this transaction eligible for Recurring platform. 

At this step, if status of the consent transaction is returned as success along with other 3 conditions explained above, merchant can consider that Subscription setup is completed successfully

Capturing successful registration response for Banks –

For Net Banking, mostly real time status received from PayU is “pending” because e-NACH registration is in the background of offline nature.

In some scenarios, it can be returned as “success” but that too in case of ICICI and HDFC bank currently. For this merchant need to be get in touch with Account manager to activate these 2 banks via PayU’s direct integration

As summary, merchant should ensure that below criteria should be satisfied to consider Net Banking registration is successful or initiated successfully with customer’s bank 

  • status = success (Indicates that transaction is successful) or pending(indicates request has been successfully raised with banks)
  • payment_source = sist(Indicates that card details have been markedcorrectly for Standing Instruction)
  • mihpayid = <Must be non-empty value>(Indicates PayU’s transactionacknowledgement for Consent transaction)

In case of “pending” status, PayU notifies merchant the exact status of the registration as either “success” or “failure” on T+2 as soon as it is received from bank over Server to Server API. 

To achieve this, merchant needs to expose a webhook and needs to request PayU team to configure the same against “ws_online_response” parameter. 

If this webhook is configured, merchant will receive above response object over HTTP form post method as mentioned below – unmappedstatus=success&phone=9999999999&txnid=FCDA1R100870163781&hash=84e3350 94bbcb2ddaa0f9a488eb338e143b273765d89c9dfa502402562d0b6f3c7935e28194ca92f380be7 c84c3695415b106dcf52cb016a15fcf6adc98d724&status=success&curl=https://www.abc.in/pay ment/handlepayuresposne&firstname=NA&card_no=519619XXXXXX5049&furl=https://www. abc.in/payment/handlepayuresposne&productinfo=2&mode=DC&amount=800.00&field4=68 07112311042810&field3=6807112311042810&field2=838264&field9=SUCCESS&email=NA&mi hpayid=175477248&surl=https://www.ABC.in/payment/handlepayuresposne&card_hash=9e88 cb0573d4a826b61d808c0a870ed4a990682459b0ec9e95ea421e8e47be8c&field1=42812

If by any means mandate registration is rejected from banks, then status will be returned as “failure” over webhook.

Note – 

If merchant doesn’t want to use web-hook implementation, then query API can be also used over T+1 and T+2 basis to know exact status of the Registration.

Only those registration transactions, where status is later changed from “pending” to “success” are eligible for recurring.

Understanding Recurring Transaction

All successful registration transactions can be charged over recurring interface with server to server API without any additional factor authentication or customers’ involvement. 

Below section details out how to achieve same for Net Banking as well as Cards through common platform.

Assumption – 

Merchant has already performed successful registration transaction with either Net Banking or Card and mihpayidreceived in the response of registration transaction is captured successfully and mapped to given customer at merchant’s end

Base URLs    
(XML based) Test   https://test.payu.in/merchant/postservice.php?form=1
Production   https://info.payu.in/merchant/postservice.php?form=1  
 (JSON based)   Test https://test.payu.in/merchant/postservice.php?form=2  
  Production   https://info.payu.in/merchant/postservice.php?form=2
Content-Type application/x-www-form-urlencoded  

Request Parameters for Recurring Payment API

Variable  Description  
key (mandatory)   This parameter is the unique Merchant Key provided by PayU for your merchant account. The Merchant Key acts as the unique identifier (primary key) to identify a Merchant Account in our database.   Sample value – YbfVda  
command (mandatory)   Value of the parameter will be always passed as – si_transaction
hash (mandatory)   512 SHA hash strings generated by encrypting request parameters so that any tampering can be avoided.   Sample Value – a6105d0e5c8726fd37713d02ace8f63652bfe1337f14e4a3652084ba9787e4ee 601a503bcc42ba101fb1c378b910d5637e9806b92fc89322db01806 97ff906b3   hash = sha512(key|command|var1||SALT)  
var1 (mandatory)   var1 is constructed by combination of some mandatory and non- mandatory fields under JSON object.   Please note that sequence of this parameter needs to be maintained as it is given in the below JSON object. i.e. authpayuId, amount, txnid, phone and email   Sample Value – {     “authpayuid”: “6611192557”,     “amount”: 3,     “txnid”: “REC15113506209”,     “phone”: “9999999999”,     “email”: “chota.bheem@gmail.com”,
      “udf2”: “”,     “udf3”: “”,     “udf4”: “”,     “udf5”: “” }   Let’s look at each of every field in detail.   authpayuid(Mandatory)     The value of mihpayidreturned in the payment response of Registration transaction when transaction is successfully completed   As explained earlier in the document, merchant needs to map this value against consumer profile at his end so that correct authpayuid will be passed in the request.  
amount (Mandatory) Recurring amount which needs to be charged for given consumer in XX.XX format.   Example 12.25   Please note that this is the same amount for which consumer has given Consent for charging his card recurring.  
txnid(Mandatory) This parameter is known as Transaction ID (or Order ID).   It is the order reference number generated at your (Merchant’s) end.   It is an identifier which you (merchant) would use to track a order.   If a transaction using a particular transaction ID has already been successful at PayU, the usage of same Transaction ID again would fail.   Hence, it is essential that you post us a unique transaction ID for every new transaction. (Please make sure that the transaction ID being sent to us hasn’t been successful earlier.  
         
phone (Non-Mandatory) Email id of the customer
email (Non-Mandatory) Mobile number of the customer
UDF2 to UDF5 Extra fields to pass any transactional information  

Calculating hash value for Recurring API –

Hash value is integral part of PayU’s API since it provides highest security standards as well as avoid any kind of tampering in the payment request.

For recurring API, hash is calculated by concatenating key, command, var1 and salt and generating 512 HASH for the resultant string.

hash = sha512(<key> + “|” + <command> + “|” + <var1> + “|” + <salt>)

For example, Merchant key – YBfVda Merchant salt – 2b1b1

Generated var1 –  {

    “authpayuid”: “6611192557”,

    “amount”: 3,

    “txnid”: “REC15113506209”,

    “phone”: “9999999999”,

    “email”: “chota.bheem@gmail.com”

}

Please note the sequence of the var1 is maintained as per the guidelines given above. Then hash value will be calculated as below, 

Hash = sha512 {YBfVda|si_transaction|{“authpayuid”: “6611192557”,”amount”: 3,”txnid”:

“REC15113506209″,”phone”: “9999999999”,”email”: “chota.bheem@gmail.com”}|2b1b1} 

Hash = bf4a0c610737c9c0acf45f40c1d914b1b4d45c447f877ed23cff53b5fbb4f9cbc3a8793c5bef 2485c46cd9d03d143a0060fc2832bcc5802c1ff5260b35a68da0

Response Object returned in Recurring Payment API

Here is sample response object returned against recurring payment API when transaction is successfully charged.

{

     “status”: 1,

     “message”: “Transaction Processed successfully”,

     “details”: {

         “REC15113506209”: {

             “transactionid”: “REC15113506209”,

             “amount”: “3”,

             “payuid”: “6611427463”,

             “status”: “captured”,

             “field9”: “Transaction Completed Successfully”,

             “phone”: “9999999999”,

             “email”: “chota.bheem@gmail.com”,

             “udf2”: “”,

             “udf3”: “”,

             “udf4”: “”,

             “udf5”: “”

         }

     }

}

Parameter Name Description  
status Status defines acknowledgement from PayU. When it is returned as 1 it means that the request posted by merchant is valid.  
message Message defines acknowledgement from PayU and returned as Transaction Processed Successfully when valid request is posted by merchant  
transactionid Value of txnid parameter which is echoed back in the response. This is unique transaction id generated by merchant during calling recurring API  
amount Requested transaction amount is echoed back in the payment response  
payuid PayU’s transaction id for processed recurring transaction. Merchant can use this field for reference point in the settlement report  
status This parameter gives the status of the transaction. Hence, the value of this parameter depends on whether the transaction was successful ornot.   You must map the order status using this parameter only.   If the transaction is successful, the value of ‘status’ parameter would be “captured”   If the status value is returned as “pending” which will be common in case of Net Banking recurring transaction, then merchant should consider this as successful initiation of payment with bank.    Now the status will be notified back to merchant over T+2 when payment processing with individual bank gets completed.    In some cases, the response of Net banking recurring can be success over real time basis as well.    The value of status as ‘failed or blank must be treated as a failed transaction only.  
field9 Description of the transaction status   
phone Mobile number of the customer echoed back  
email Email id of the customer echoed back  
udf2 to udf5 Extra information received in the request echoed back
   

Few Sample Error response scenarios are mentioned here – 

{

    “status”: 0,

    “msg”: “Invalid Hash.”

}

{

    “status”: 1,

    “message”: “Transaction Processed successfully”,

    “details”: {

        “REC9812123123”: {

            “authpayuid”: “6611192559”,

            “transactionid”: “REC9812123123”,

            “amount”: “1”,

            “user_credentials”: ” “,

            “card_token”: ” “,

            “payuid”: “”,

            “status”: “failed”,

            “field9”: “Basic authentication check failed”,

            “phone”: “”,

            “email”: “”

        }

    }

}

Capturing Successful Recurring transaction in case of Net Banking –

Since most of the Net Banking recurring payment is file based, the response of transaction is not real time. 

When PayU receives such recurring request against Net Banking, it validate the request parameters and registration details. If they are aligned, then PayU returns “pending” status to merchant over real time API call.

For these “pending” cases, PayU notifies merchant the exact status of the transaction as either “success” or “failure” upto T+2 as soon as it is received from bank over Server to Server API. 

To achieve this, merchant needs to expose a webhook and needs to request PayU team to configure the same against “ws_online_response” parameter. 

If this webhook is configured, merchant will receive above response object over HTTP form post method as mentioned below –

unmappedstatus=success&phone=9999999999&txnid=FCDA1R100870163781&hash=84e3350 94bbcb2ddaa0f9a488eb338e143b273765d89c9dfa502402562d0b6f3c7935e28194ca92f380be7 c84c3695415b106dcf52cb016a15fcf6adc98d724&status=success&curl=https://www.abc.in/pay ment/handlepayuresposne&firstname=NA&card_no=519619XXXXXX5049&furl=https://www. abc.in/payment/handlepayuresposne&productinfo=2&mode=DC&amount=800.00&field4=68 07112311042810&field3=6807112311042810&field2=838264&field9=SUCCESS&email=NA&mi hpayid=175477248&surl=https://www.ABC.in/payment/handlepayuresposne&card_hash=9e88 cb0573d4a826b61d808c0a870ed4a990682459b0ec9e95ea421e8e47be8c&field1=42812

If by any means transaction is rejected from banks, then status will be returned as “failure” over webhook.

Supporting Query and Refund APIs –

For Query and Refund transaction, please refer SECTION II: WEB SERVICES – APIs from PayU’s standard integration guide since there is no change in the request and response format for these functions either for Consent transaction or for Recurring transaction.