1. Home
  2. Docs
  3. Developers Guide
  4. Web Checkout
  5. Merchant Hosted Checkout
  6. Merchant Hosted Integrations

Merchant Hosted Integrations

Merchant-hosted checkout allows the merchants with the complete freedom to collect and handle the payment information of their customers through a website interface customized as per their requirements.
The following document attempts a detailed account of the elements and best practices that are crucial for the successful integration of the merchant with the PayU systems through this route.

Prerequisites

  • Develop a mature business website to collect the complete payment details of the users at the merchant’s end.
  • Attain the Payment Card Industry Data Security Standard (PCI-DSS) certification, mandatory for all entities seeking to store, process, and transmit cardholder data.
  • Deploy enough technical bandwidth to manage the end-to-end web checkout processes in-house consistently.

Integration Security

It is absolutely mandatory that the hash (or checksum) is computed again after you receive response from PayU and compare it with request and post back parameters. This will protect you from any tampering by the user and help in ensuring a safe and secure transaction experience. It is mandate that you secure your integration with PayU by implementing Verify webservice and Webhook/callback as a secondary confirmation of transaction response. Detailed integration process of Verify webservice and webhook and be found further in this document. 

Please ensure that sensitive information related to the integration is not part of the payment request to PayU. The details including — but not limited to — the following are considered sensitive information.

1. salt value

2. plain text hash string

Along with the request, the sensitive information should not be a part of any merchant-level URL. The following are considered sources for the merchant-level URL.

1. The last web address accessed by a browser before loading PayU’s checkout page

2. URLs shared as part of payment request to PayU in the parameter surl, furl, curl, nurl, and termUrl

3. Notification URLs configured with the merchant account

4. Invoice Completion URLs configured with the merchant account

Please note that PayU will not be responsible for any security breaches (including any data breaches) that may occur due to non-implementation of the aforesaid security features at your end or any loss or damage arising therefrom, to you or to any third party.  

Base URLs

Environment{base_url}
Sandboxhttps://test.payu.in
Productionhttps://secure.payu.in

Method – POST

PATH – {base_url}/_payment

Request Headers

accept (mandatory)application/json
Content-Typeapplication/x-www-form-urlencoded

Parameters to be posted by Merchant to PayU in Transaction Request

There are certain parameters that are mandatory and few are optional, while one calls the Merchant Hosted Web Checkout.

Mandatory Request Parameters

S.NoParameter*DescriptionTypeExample
1.keyThe merchant key is provided by PayU and acts as a unique identifier for a specific merchant account in the PayU’s database. VarcharJPM7Fg
2. txnidThe transaction ID is the order reference number generated by the merchant to track a particular order. It can be used only once and PayU’s system does not accept a duplicate Transaction ID.
Varchar
Character Limit – 25
s7hhDQVWvbhBdN
3. amountIt should contain the payment amount of the particular transaction. Float/Int10.53/10
4. productinfoIt should be a string containing a brief description of the product. Varchar
Character Limit – 100
iPhone
5.firstnameThe first name of the customer.Varchar
Character Limit – 60
Ashish
6. emailThe email of the customer. Varchar
Character Limit – 50
test@gmail.com
7.phoneThe phone number of the customer.Varchar
Character Limit – 50
(numeric value only)
9876543210
8.surlSuccess URL(surl) – It must contain the URL on which PayU will redirect the final response if the transaction is successful.Varchar (URL)https://apiplayground-response.herokuapp.com/
9.furlFailure URL (furl) – It must contain the URL on which PayU will redirect the final response in case of failure.Varchar (URL)https://apiplayground-response.herokuapp.com/
10.hashIt is used to avoid the possibility of transaction tampering. Click here to know more about the hash generation process.Varchareabec285da28fd
0e3054d41a4d24fe
9f7599c9d0b6664
6f7a9984303fd612
4044b6206daf831
e9a8bda28a6200d
318293a13d6c193
109b60bd4b4f8b09
c90972
11.pgIt defines the payment category that the merchant wants the user to see by default on the PayU’s payment page. If this field is empty, the system assumes the Credit Card payment option by default. The pg value for each payment category is defined below. Example: if pg= ’NB’ then after redirection to PayU’s payment page, the Net Banking option would be opened by default.(Refer to table below)VarcharCC
12.bankcodeEach payment option is identified with a unique bank code at PayU. The merchant must post this parameter with the corresponding payment option’s bankcode value in it.
For a detailed list of bank codes, please contact the PayU team
String
cc

PG Value

Payment OptionCode
Net BankingNB
Credit CardCC
Debit CardDC
Cash Card CASH
EMI EMI
Cardless EMI CLEMI
Cash On Delivery COD
IVR IVR

Bankcode values (Card Payment)

SchemeCode
VisaVISA
Master CardMAST
American ExpressAMEX
RuPayRUPAY

Mandatory in Credit / Debit Card option

Parameter*DescriptionExample
ccnumThis parameter must contain the card (credit/debit) number entered by the customer for the transaction.5123456789012346
ccnameThis parameter must contain the name on card – as entered by the customer for the transaction.Ashish
ccvvThis parameter must contain the cvv number of the card – as entered by the customer for the transaction.123
ccexpmonThis parameter must contain the card’s expiry month – as entered by the user for the transaction. It must always be 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.
05
ccexpyrThis parameter must contain the card’s expiry year – as entered by the customer for the transaction. It must be of 4 digits.2022
Consent_sharedThis is applicable for Cardless EMI transactions only. Values can be 0 or 1 based on whether the merchant has taken customer’s consent to share data or not.1

Note: While pg and bankcode are mandatory parameters for all transactions through seamless integrations, the above parameters must be used on a case by case basis.

For example, if the transaction is executed using net banking pg=NB and the bankcode of the respective bank is sufficient. However, if the customer is using the CC/DC option, the merchant must pass the value of ccnum, ccname, ccvv, ccexpmon and ccexpyr to PayU in the POST request. In card transactions the bankcode will include the scheme that the respective card operates within.

Optional Request Parameters

S.NoVariableDescriptionData TypeExamples
1. address1The first line of the billing address. It is mandatory for the cardless EMI option.Varchar, Character Limit – 100, Characters allowed: A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)H.No- 17, Block C, Kalyan Bldg, Khardilkar Road, Mumbai
2. address2The second line of the billing address. Varchar, Character Limit – 100, Characters allowed: A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)34 Saikripa-Estate, Tilak Nagar
3.cityBilling address city is mandatory for the cardless EMI option.Varchar, Character Limit – 50, Characters allowed : A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)Mumbai
4.stateBilling address state is mandatory for the cardless EMI option.Varchar, Character Limit – 50, Characters allowed : A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)Maharashtra
5.countryBilling address country is mandatory for the cardless EMI option.Varchar, Character Limit – 50, Characters allowed : A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)India
6.zipcodeBilling address zip code is mandatory for the cardless EMI option.Varchar, Character Limit – 20, Characters allowed : A to Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)400004
7.udf1User-defined fields(udf) are used to store any information corresponding to a particular transaction. Merchants can use up to 5 udfs in the post designated as udf1, udf2, udf3, udf4, udf5. ()Data type – Varchar, Character Limit – 255test123
8. udf2User-defined fields(udf) are used to store any information corresponding to a particular transaction,
which may be useful for you to keep in the database.
Data type – Varchar, Character Limit – 255copy789
9.udf3User-defined fields(udf) are used to store any information corresponding to a particular transaction,
which may be useful for you to keep in the database.
Data type – Varchar, Character Limit – 255check789
10.udf4User-defined fields(udf) are used to store any information corresponding to a particular transaction.Data type – Varchar, Character Limit – 255pass12345
11.udf5User-defined fields(udf) are used to store any information corresponding to a particular transaction.Data type – Varchar, Character Limit – 25501234
8.curlCancel URL(curl) – It must contain the URL on which PayU will redirect the final response if the transaction is cancelled by the user.varchar (URL)www.abc1234.com
9. lastnameLast name of the customerVarchar
Character Limit – 20
Verma

Post Request Syntax & Composition

Here is a sample post request that the merchant needs to send to PayU:

<html>

<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="test@gmail.com" />
		<input type="hidden" name="firstname" value="Ashish" />
		<input type="hidden" name="bankcode" value="TESTPGNB" />
		<input type="hidden" name="pg" value="" />
		<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 code block is for Merchant Checkout integration on the netbanking call for the test environment.

However, it can be called for production environment incorporating the values of pg and bankcode for net banking. Similarly it can be called for Credit/debit card, Wallet & other flows by adding mandatory params.

Run Request in Real Time:

In API playground , select category Merchant Hosted and run the request for the flow you want.

You will get below screen on API playground to try it in real time:

CURL 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=s7hhDQVWvbhBdN&amount=10&firstname=Ashish&email=test@gmail.com&phone=9876543210&productinfo=iPhone&pg=cc&bankcode=cc&surl=https://apiplayground-response.herokuapp.com/&furl=https://apiplayground-response.herokuapp.com/&ccnum=5123456789012346&ccexpmon=05&ccexpyr=2022&ccvv=123&ccname=&hash=a869993b16fab076dbff8670ed6f6b46eb5fc2bf3a6494baac82c09c0f0e168d7e159d8496907f0b50df201c7a61560acf106c555d79ef160a508b8a9bb72e05"

Success Response

Below is the response body for a Success Status. Read more about different error codes

{
  "mihpayid": "403993715522785570",
  "mode": "CC",
  "status": "success",
  "unmappedstatus": "captured",
  "key": "JPM7Fg",
  "txnid": "s7hhDQVWvbhBdN",
  "amount": "10.00",
  "cardCategory": "domestic",
  "discount": "0.00",
  "net_amount_debit": "10",
  "addedon": "2021-03-15 03:17:17",
  "productinfo": "iPhone",
  "firstname": "Ashish",
  "address1": "",
  "address2": "",
  "city": "",
  "state": "",
  "country": "",
  "zipcode": "",
  "email": "test@gmail.com",
  "phone": "9876543210",
  "udf1": "",
  "udf2": "",
  "udf3": "",
  "udf4": "",
  "udf5": "",
  "udf6": "",
  "udf7": "",
  "udf8": "",
  "udf9": "",
  "udf10": "",
  "hash": "ac8cc2046e71a18f21f88a29aaf00e02ef34a6e28d982e3664f89fa40ada26359b9410eefc181f74697bbc38dd4cfedc1a2608e0c9ceb04a8abc7e25d4d92921",
  "field1": "",
  "field2": "",
  "field3": "",
  "field4": "",
  "field5": "",
  "field6": "",
  "field7": "",
  "field8": "",
  "field9": "Transaction Completed Successfully",
  "payment_source": "payu",
  "PG_TYPE": "CC-PG",
  "bank_ref_num": "44a7983c-682e-4d29-8cd9-44d0a1fb18a4",
  "bankcode": "CC",
  "error": "E000",
  "error_Message": "No Error",
  "name_on_card": "payu",
  "cardnum": "512345XXXXXX2346",
  "cardhash": "This field is no longer supported in postback params."
}

Response Parameters posted by PayU to Merchant

Please verify amount and txnid parameters at your end in response from PayU.

Understanding Response Parameters

S.NoVariable Description
1. mihpayidIt is a unique reference number created for each transaction at PayU’s end. Please save this transaction id at your end because this will be used as a reference for all the future actions on this transaction like Inquiry or Refund.
2.modeThis parameter describes the payment category by which the transaction was completed/attempted by the customer. The payment categories have been mentioned above under pg values.
3. statusThis parameter gives the status of the transaction as either success, failed or pending.
Possible values: success, failure, pending
If the value of the ‘status’ parameter is ’success’, the transaction is successful.
If the value of ‘status’ is ‘failure’ or ‘pending’, must be treated as a failed transaction only
4. keyThis 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 the merchant’s end to PayU.
5.txnidThis parameter would contain the transaction ID value posted by the merchant during the transaction request.
6.amountThis parameter would contain the original amount which was sent in the transaction request by the merchant.
7.productinfoThis parameter would contain the same value of productinfo which was sent in the transaction request from the merchant’s end to PayU.
8.firstnameThis parameter would contain the same value of firstname which was sent in the transaction request from the merchant’s end to PayU.
9.emailThis parameter would contain the same value of email which was sent
10.phoneThis parameter would contain the same value of phone which was sent in the transaction request from the merchant’s end to PayU.
11.udfThis parameter would contain the same value of udf values which were sent in the transaction request from merchant’s end to PayU. It ranges from udf1 to udf5.
12.hashPayU 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|firstname|p roductinfo|amount|txnid|key)
Note: 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.
13.errorFor the failed transactions, this parameter provides the reason of
failure.
Note: the reason of failure depends upon the error codes provided by different banks and hence the detailing of error reasons may differ from one transaction to another. The merchant can use this parameter to retrieve the reason of failure for a particular transaction.
14.bankcodeThis 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. For example, Visa Debit Card – VISA, Master Debit Card – MAST.
15.PG_TYPEThis parameter gives information on the payment gateway used for the transaction. For example, if CC PG was used, it would contain the value CC-PG. Similarly, it would have a unique value for all different types of payment gateways.
16.bank_ref_numFor each successful transaction – this parameter would contain the bank reference number generated by the bank.
17.unmappedstatusThis parameter contains the status of a transaction as per the internal database of PayU. PayU’s system has several intermediate status which are used for tracking various activities internal to the system. Hence, this status contains intermediate states of a transaction also – and hence is known as unmappedstatus.
For example: dropped/
bounced/ captured/ auth/ failed/ usercancelled/ pending
Read here for status description.