API Integration - Non-Seamless

This document provides a comprehensive guide for integrating with v2 Non-Seamless using the v2/payments API. The hosted checkout integration allows you to redirect customers to PayU's secure payment page, minimising PCI compliance requirements while providing a seamless payment experience.

👍
Before you begin:

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

PayU recommends you integrate with Test environment for testing and then move to the Production environment.

Integration Overview

The v2 non-seamless integration consists of two main steps:

Make the transaction request to PayU's v2/payments API
Verify the payment status using the verification API

Step 1: Make the Transaction Request to PayU

Environment


Test Environment	https://apitest.payu.in/v2/payments
Production Environment	https://api.payu.in/v2/payments>

Request Headers

Parameter	Description
date	The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT.
authorization	The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description.

authorization fields description

Field	Description
username	Represents the username or identifier for the client or merchant, for example smsplus.
algorithm	Use SHA512 algorithm for hashing and send this as header value.
headers	Specifies which headers have been used in generating the hash, for example date.
signature	The HMAC signature generated using the specified algorithm. For more information, refer to hashing algorithm.

hashing algorithm

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

Hash logic: sha512(<Body data> + '|' + date + '|' + merchant_secret)

Where <Body data> contains the request body posted with the request.

Sample header code

var merchant_key = 'smsplus';
var merchant_secret = 'izF09TlpX4ZOwmf9MvXijwYsBPUmxYHD';
// date
var date = new Date();
date = date.toUTCString();

// authorization
var authorization = getAuthHeader(date);

function getAuthHeader(date) {
    var AUTH_TYPE = 'sha512';
    var data = isEmpty(request['data']) ? "" : request['data'];
    var hash_string = data + '|' + date + '|' + merchant_secret;
    var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
    return `hmac username="${merchant_key}", algorithm="${AUTH_TYPE}", headers="date", signature="${hash}"`;
}

Request Parameters

The v2/payments API request contains the following main parameters:

Parameter	Description	Example
accountId `mandatory`	`String` Merchant key provided by PayU. Character limit: 50	`"smsplus"`
txnId `mandatory`	`String` Unique transaction ID for the transaction. Character limit: 50	`"REF_123456789"`
order `mandatory`	`Object` Order details containing product information and pricing. For more information, refer to order object	`{"productInfo": "Product Name", "paymentChargeSpecification": {"price": 1000.00}}`
billingDetails `mandatory`	`Object` Customer billing information. For more information, refer tobillingDetails object	`{"firstName": "John", "email": "[email protected]", "phone": "9876543210"}`
callBackActions `mandatory`	`Object` Callback URLs for different payment outcomes. For more information, refer to callBackActions object	`{"successAction": "https://merchant.com/success", "failureAction": "https://merchant.com/failure"}`
additionalInfo `mandatory`	`Object` Additional transaction parameters including flow type. For more information, refer toadditionalInfo object	`{"txnFlow": "non-seamless", "enforcePaymethod": "NB"}`

Order Object

Parameter	Description	Example
productInfo `mandatory`	Product details.	Product details
orderedItem `optional`	Details about the items ordered.	Array of Objects
userDefinedFields `optional`	Custom fields for additional information. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10. For more information, refer to	Object
paymentChargeSpecification `mandatory`	Includes amount and charges. For more information, refer to paymentChargeSpecification object fields description	Object

paymentChargeSpecification object fields description

Parameter	Description	Example
price `mandatory`	The transaction amount.	1000
netAmountDebit `optional`	Net amount to be debited.	1000
taxSpecification `optional`	Tax details of the product/order.	Object
convenienceFee `optional`	Fees format (e.g., CC:12).	CC:12
offers `optional`	Offers applied or available for the payment.	Object

userDefinedFields object fields description

Field	Description
udf1	User defined field.
udf2	User defined field.
udf3	User defined field.
udf4	User defined field.
udf5	User defined field.
udf6	User defined field.
udf7	User defined field.
udf8	User defined field.
udf9	User defined field.
udf10	User defined field.

Payment Charge Specification Object

Parameter	Description	Example
price `mandatory`	The transaction amount.	1000
netAmountDebit `optional`	Net amount to be debited.	1000
taxSpecification `optional`	Tax details of the product/order.	Object
convenienceFee `optional`	Fees format (e.g., CC:12).	CC:12
offers `optional`	Offers applied or available for the payment.	Object

Additional Info Object

Parameter	Description	Example
enforcePaymethod `optional`	Force a transaction with a specified method (e.g., CC, DC).	CC
forcePgid `optional`	Forces identification for payment gateway.	PG123
partnerHoldTime `optional`	Time held by the partner for the transaction.	60
userCredentials `optional`	Credentials for user authentication.	string
userToken `optional`	Token for the customer.	user_token_123
subventionAmount `optional`	Amount paid through EMI subvention payments.	100
authOnly `optional`	Initiates an authentication-only payment (true/false).	false
createOrder `optional`	A flag to store the order details (true/false).	true
txnS2sFlow `optional`	For defining seamless/non-seamless flows in handling payments.	seamless

Callback Actions Object

Parameter	Description	Example
successAction `mandatory`	URL to be called on payment success.	https://example.com/success
failureAction `mandatory`	URL to be called on payment failure.	https://example.com/failure
cancelAction `mandatory`	URL to be called if user cancels the payment.	https://example.com/cancel
codAction `optional`	URL for Cash on Delivery (COD) action.	https://example.com/cod

Billing Details Object

Parameter	Description	Example
firstName `mandatory`	First name of the billing contact.	Ashish
lastName `optional`	Last name of the billing contact.	Kumar
address1 `mandatory`	Primary billing address.	123 Main Street
address2 `optional`	Secondary billing address.	Apt 4B
phone `optional`	Phone number of the billing contact.	9123456789
email `mandatory`	Email address of the billing contact.	[email protected]
city `optional`	City of the billing address.	Bharatpur
state `optional`	State of the billing address.	Rajasthan
country `optional`	Country of the billing address.	India
zipCode `optional`	Postal/Zip code of the billing address.	321028

Sample Request

Request Headers:

Content-Type: application/json
date: Wed, 28 Jun 2023 11:25:19 GMT
authorization: hmac username="smsplus", algorithm="sha512", headers="date", signature="<calculated_hmac_signature>"

Request Body:

{
  "accountId": "smsplus",
  "referenceId": "b5f2d8785768087678fm9",
  "currency": "INR",
  "paymentSource": "WEB",
  "order": {
    "productInfo": "Test Product",
    "orderedItem": [
      {
        "itemId": "ITEM001",
        "description": "Test Product Description",
        "quantity": 1
      }
    ],
    "paymentChargeSpecification": {
      "price": 10.00
    }
  },
  "additionalInfo": {
    "txnFlow": "nonseamless"
  },
  "callBackActions": {
    "successAction": "https://example.com/success",
    "failureAction": "https://example.com/failure",
    "cancelAction": "https://example.com/cancel"
  },
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "9876543210",
    "email": "[email protected]",
    "address": {
      "address1": "123 Main Street",
      "city": "Mumbai",
      "state": "Maharashtra",
      "country": "India",
      "zipCode": "400001"
    }
  }
}

Sample Response

{
  "result": {
    "checkoutUrl": "https://pp78secure.payu.in/_payment_options?mihpayid=<mihpayuid>&userToken="
  },
  "status": "PENDING"
}

Step 2: Verify the Payment

After the customer completes the payment on the PayU checkout page, you must verify the payment status using the verification API.

Environment

Environment	URL
Test	`https://test.payu.in/v3/transaction`
Production	`https://api.payu.in/v3/transaction`

Request Headers

The verification API requires the following headers:

Header	Description	Required
`Content-Type`	Must be `application/json`	Yes
`date`	Current date in GMT format	Yes
`authorization`	HMAC signature for authentication	Yes
`Info-Command`	Must be `verify_payment`	Yes

Request Parameters

Parameter	Type	Description	Required
`txnId`	Array	Array of transaction reference IDs to verify	Yes

Response Parameters

Parameter	Description
txnId	This parameter contains the transaction ID of the transaction.
paymentId	This parameter contains the payment ID of the transaction.
message	This parameter contains the status message of the transaction.

Sample Verification Request

Request Headers:

Content-Type: application/json
date: Thu, 27 Mar 2025 06:35:21 GMT
authorization: hmac username="PRiQvJ", algorithm="sha512", headers="date", signature="<calculated_hmac_signature>"
Info-Command: verify_payment

Request Body:

{
  "txnId": ["b5f2d8785768087678fm9"]
}

Sample Verification Success Response

{
  "message": "Success",
  "status": 1,
  "result": [
    {
      "mihpayId": 21612493009,
      "bankReferenceNumber": "2411194544",
      "amount": 10.00,
      "mode": "CC",
      "requestId": "",
      "originalAmount": 10.00,
      "additionalCharges": 0.00,
      "discount": 0.00,
      "netDebitAmount": 10.00,
      "productInfo": "Test Product",
      "firstName": "John",
      "bankcode": "VISA",
      "nameOnCard": "JOHN DOE",
      "cardNo": "XXXXXXXXXXXX1234",
      "cardType": "VISA",
      "udf1": null,
      "udf2": null,
      "udf3": null,
      "udf4": null,
      "udf5": null,
      "field2": "140455",
      "field9": "Transaction is Successful",
      "errorCode": "E000",
      "errorMessage": "No Error",
      "addedOn": "2024-11-19 21:17:55",
      "settledAt": "0000-00-00 00:00:00",
      "paymentSource": "WEB",
      "pgType": "CC-PG",
      "status": "success",
      "unmappedStatus": "captured",
      "merchantUTR": null,
      "rupayAuthRefNo": null,
      "authRefNo": "123456789",
      "originalCurrency": "INR",
      "threeDSVersion": "2.2.0",
      "message": "Found TxnId",
      "txnId": "b5f2d8785768087678fm9"
    }
  ]
}

Sample Verification Failure Response

{
  "status": 0,
  "msg": "Invalid Transaction ID"
}