PayU Hosted Payment Integration

This section describes how to integrate Cross-Border Subscriptions with PayU Hosted Checkout integration using _payment API. This integration following steps:

1. Post the Payment Request with PayU

Post the payment parameters to PayU's _payment API with required UDFs for cross-border.

2. Check Response from PayU

Handle the URL-format response from PayU and validate using reverse hashing.

3. Verify the Payment

Reconcile and validate transaction details using verification methods.

4. Update Invoice ID (Conditional)

Update the invoice ID associated with the transaction

5. Upload the Invoices / Shipping Document (Conditional)

Upload invoice documents related to the completed transaction

Step 1: Post the Payment Request with PayU

📘
Note: For Cross-Border Payments, the UDF parameters (udf1, udf2, udf3, udf4, and udf5) have specific requirements as described in the Request parameters table below.

Request parameters

In the merchant-initiated POST REQUEST, Hash is a mandatory parameter. It is critical to calculate the hash correctly and post it to PayU in the request.

Parameter	Description	Example
key `mandatory`	`varchar` This parameter is the unique Merchant Key provided by PayU for your merchant account.	Your Test Key
txnid `mandatory`	`varchar` 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 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 the same Transaction ID again would fail. Hence, you must post a unique transaction ID for every new transaction. `Character limit`: 25 Note: Ensure this transaction ID hasn't been processed successfully before.	fd3e847h2
amount `mandatory`	`float` This parameter should contain the payment amount for the specific transaction. Note: Typecast the amount to a float type. The amount can vary based on use cases: • For Net Banking, 0 INR • For Cards & UPI, a minimum of 1 INR (penny transactions)	1000
productinfo `mandatory`	`varchar` A brief product description. Short information about the product/service. Character limit: 100	Time Magazine Subscription
email `mandatory`	`varchar` Contains the email of the customer; highly recommended accuracy as fraud detection relies on this. Character limit: 50.	[email protected]
firstname `mandatory`	`varchar` The customer's first name. Character limit is 60.	John
lastname `mandatory`	`varchar` The customer's middle & last name (wherever applicable). Character limit is 60.	Doe
phone `optional`	`varchar` Customer phone number for fraud detection and user tracking. Character limit: 50.	9843176540
address1 `optional but recommended for higher approval rate`	`varchar` The customer's primary billing address line. This field is required for billing and fraud prevention purposes. Character limit: 255.	123 Main Street
city `optional but recommended for higher approval rate`	`varchar` The customer's billing city. This field is required for billing and fraud prevention purposes. Character limit: 50.	New Delhi
state `optional but recommended for higher approval rate`	`varchar` The customer's billing state or province. This field is required for billing and fraud prevention purposes. Character limit: 50.	Delhi
country `optional but recommended for higher approval rate`	`varchar` The customer's billing country code. This field is required for billing and fraud prevention purposes. Use ISO 3166-1 alpha-2 country codes. Character limit: 2.	India
zipcode `mandatory`	`varchar` The customer's billing postal/zip code. This field is required for billing and fraud prevention purposes. Character limit: 6 digit (India Zipcode)	110075
surl `mandatory`	`URL` The success URL to which PayU redirects after a successful transaction.	https://example.com/success
furl `mandatory`	`URL` The failure URL to which PayU redirects after a failed transaction.	https://example.com/failure
udf1 `optional but recommended for higher approval rate`	`String` The Permanent Account Number (PAN primary taxation ID in India) of the buyer must be collected in this field. Character limit: 10 character alphanumeric	ABCDE1234K
udf2 `optional`	`String` User-defined field for storing transaction-specific data. Character limit: 255.	Additional transaction data
udf3 `optional but recommended for higher approval rate`	`String` Date of Birth (DOB) of buyer in DD-MM-YYYY	02-02-1980
udf4 `mandatory for payment aggregators`	`String` End merchant legal entity name. For UPI, this field should not be passed. Character limit: 255.	XYZ Pvt. Ltd.
udf5 `mandatory`	`String` Contains invoice ID for the transaction. Invoice ID / number should be the ID present on the invoice issued to the customer. Character limit: 255.	INV123456
buyer_type_business `optional in case of B2B transaction for cross-border payments`	`Binary` To be sent as "1" in case the buyer is a business. In case of individual buyers, it can be skipped. Default is "0". Note: This will be included in hash if posted (covered in next section).	1
udf_params `optional`	`String JSON` UDF7 value to capture "Import or Export Code" of the buyer UDF8 value to capture Airway Bill Number / Consignment Number (in case of goods imports)	{"udf7":"0100000029", "udf8":"99953729071"}
hash `mandatory`	`String` Crucial security parameter using SHA512 hash encryption. Formula incorporates key, txnid, amount, productinfo, firstname, email, udf fields, si_details, and merchant salt.	<Generated Hash>

Hashing

Parameters in the below sequence needs to be checked before generating the hash, if these params are being posted, it needs to be added in the hash calculation:

|additional_charges|miles|base_payuid|base_merchantid|paisa_mecode|subvention_amount|subvention_eligibility|merchant_data|payoutdetails|loan_id|twid_customer_hash|splitrequest|percentage_additional_charges|force_pa|udf_params|buyer_type_business|tcs_amount

Case1 example: Simple Hashing, if the merchant is not sending the api_version in the payment request, then it will be treated as hash sequence version 1.

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||si_details|salt

Case2 example: if the merchant is passing the additional_charges in the payment request then they have to append the additional_charges value in the raw hash sequence as below.

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||si_details|salt|additional_charges

Case3 example: If the merchant wants to pass additional_charges, buyer_type_business in the payment request, then hash formula for payment request will be:

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||si_details|salt|additional_charges|buyer_type_business

Case4 example: if the merchant wants to pass the api_version = 7 and buyer_type_business, udf_params in the payment request.

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||si_details|salt|udf_params|buyer_type_business

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5|udf6|udf7|udf8|udf9|udf10|salt|additional_charges|buyer_type_business

Case4 example: if the merchant wants to pass the api_version = 7 and buyer_type_business, udf_params in the payment request.

key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5|udf6|udf7|udf8|udf9|udf10|si_details|salt|udf_params|buyer_type_business

📘
Reference: PayU recommends you to use PayU Hash Verification Tool to verify the hashing. For more information, refer to Using PayU Hash Verification Tool

Sample request

curl -X POST "https://test.payu.in/_payment" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=JPM7Fg&txnid=payuTestTxn12345&amount=100.00&productinfo=iPhone&firstname=Ashish&lastname=Kumar&[email protected]&phone=9876543210&zipcode=110075&surl=https://example.com/success&furl=https://example.com/failure&udf1=AELPR1234E&udf3=02-02-1980&udf4=XYZ Pvt. Ltd.&udf5=INV123456&buyer_type_business=1&udf_params={\"udf7\":\"<IE_CODE>\",\"udf8\":\"<AWB Num>\"}&hash=<generated_hash>"

Step 2: Check Response from PayU

The response URL returned from PayU is in the form URL format (application/x-www-form-urlencoded). You must implement the reverse hashing as described in the following:

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

Parsed response

Array
(
    [mihpayid] => 403993715525331373
    [mode] => ENACH
    [status] => success
    [unmappedstatus] => captured
    [key] => JPM7Fg
    [txnid] => oRWSUMU4XSQBZn
    [amount] => 100.00
    [discount] => 0.00
    [net_amount_debit] => 0
    [addedon] => 2022-02-03 19:06:55
    [productinfo] => iPhone Subscription
    [firstname] => PayU User
    [lastname] => 
    [address1] => 
    [address2] => 
    [city] => 
    [state] => 
    [country] => 
    [zipcode] => 
    [email] => [email protected]
    [phone] => 9876543210
    [udf1] => AELPR1234E
    [udf2] => 
    [udf3] => 02-02-1980
    [udf4] => XYZ Pvt. Ltd.
    [udf5] => INV123456
    [hash] => f3f8e4088231b190930fc4b87d3f39397d1a1d02622ef4683a983244e1cd5158f39adbb67c3d87dcb4da25ae4a941ebbf55918e4575fa1c39677a774d02c0d2d
    [field1] => ENACH285259747472911093
    [field2] => 337026657857179355
    [field9] => Mandate successfully scheduled at bank end: Your payment is scheduled successfully
    [payment_source] => sist
    [PG_TYPE] => ENACH-PG
    [bank_ref_num] => 450699821592111537
    [bankcode] => ICICENCC
    [error] => E000
    [error_Message] => No Error
)

Step 3: Verify the Payment

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

Upon receiving the response, PayU recommends you 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.

Know how to manage Webhooks for Payments.

Step 4: Update Invoice ID [Conditional]

If the Invoice ID value was unavailable when posting the transaction at Step 1, it can be updated using the UDF Update API by posting it in the UDF5 parameter.

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 other then UPI AutoPay

  curl --location --globoff 'https://test.payu.in/merchant/postservice.php?form=2' \
  --form 'key="PRiQvJ"' \
  --form 'command="udf_update"' \
  --form 'var1="my_order_642"' \
  --form 'var2="AAAPZ1234C"' \
  --form 'var4="22/08/1972"' \
  --form 'var5="SellerName"' \
  --form 'var6="INV000000005"' \
  --form 'hash="{{hash}}"'

Sample request for UPI AutoPay

curl --location 'https://test.payu.in/merchant/postservice.php?form=2' \
--form 'key="PRiQvJ"' \
--form 'command="udf_update"' \
--form 'var1="my_order_642"' \
--form 'var2="AAAPZ1234C||22-08-1972"' \
--form 'var4="INV_121312||SellerName"' \
--form 'hash="{{hash}}"'

Sample response

Success Scenario

If successfully updated for cards or Net Banking

{
    "status": "UDF values updated",
    "transaction_id": "my_order_64240",
    "udf1": "AAAPZ1234C",
    "udf2": "",
    "udf3": "22/08/1972",
    "udf4": "SellerName",
    "udf5": "INV000000005"
}

If successfully updated for UPI autopay:

{
  "status": "UDF values updated",
  "transaction_id": "my_order_64240",
  "udf1": "AAAPZ1234C||22-08-1972",
  "udf2": "",
  "udf3": "INV_121312||SellerName"
}

Failure Scenarios

If the transaction ID is empty

( 
[status] => 0 
[msg] => Parameter missing 
)

If the transaction ID is invalid

( 
[status] => 0 
[msg] => Invalid TXN ID 
)

If Hash is invalid:

{
    "status": 0,
    "msg": "Invalid Hash."
}

If the merchant is not enabled for UDF updates:

{
  "status": "0",
  "msg": "Update not allowed on provided Field"
}

If no data found in the transaction ID:

{
  "status": "0",
  "msg": "No Data Found for txnid: 3424"
}

If the merchant is inactive:

{
  "msg": "Merchant is not authorized to use PayU API",
  "status": 0
}

Step 5: Upload the Invoices [Optional]

The invoices / Airway Bill can be uploaded using the Invoice Upload API API. AWB details are mandatory for Goods transactions. Invoice copies can be uploaded optionally.

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

curl --location -g --request POST '{{baseUrl}}/merchant/postservice?form=2' \ 
--form 'key="{{merchantKey}}"' \ 
--form 'command="opgsp_upload_invoice_awb"' \ 
--form 'var1="403993715525825059"' \  - PayuId 
--form 'var2="TestInv0001234568"' \ - invoice Id 
--form 'var3="Invoice"' \ - type of upload - Invoice/AWB 
--form 'file=@"/path/to/file"' \ - file 
--form 'hash="{{hash}}"'

Sample response

Success Scenario

When a file is uploaded successfully:

{
"responseCode":"00",
"responseMsg":"File Uploaded Successfully"
}

Failure Scenarios

When there is an error in uploading the file:

{ 
"responseCode": "103", 
"responseMsg": "Failed to Upload" 
}

When the file format is not supported:

{ 
"responseCode": "105", 
"responseMsg": "Not an PACB merchant, contact KAM" 
}

When the payuid is invalid:

{
"responseCode":"107",
"responseMsg":"The PayuID in request is invalid"
}

When a mandatory field is missing:

{
"responseCode":"109",
"responseMsg":"All fields are mandatory, please check!"
}

Response Code and Description

Refer to Response Code and Description - Invoice Upload API.

Step 1: Post the Payment Request with PayU

Hashing

Step 2: Check Response from PayU

Hash validation logic for payment response (Reverse Hashing)

Step 3: Verify the Payment

Step 4: Update Invoice ID [Conditional]

Success Scenario

Failure Scenarios

Step 5: Upload the Invoices [Optional]

EXAMPLE QUESTIONS