This section describes the additional information on v2/payment API such as character limit and data type of each parameter or fields of various JSON objects.
Request headers
| Header | Description | Example |
|---|---|---|
date
mandatory
|
string Current date and time in GMT/UTC format (RFC 7231 / IMF-fixdate). This header is required for generating the authorization signature.
|
Wed, 28 Jun 2023 11:25:19 GMT |
authorization
mandatory
|
string HMAC signature generated using SHA512 algorithm. Format:
hmac username="[accountId]", algorithm="sha512", headers="date", signature="[calculated_signature]"
The signature is calculated as: sha512(request_body + '|' + date + '|' + merchant_secret)
This replaces the 'hash' parameter from v1 API.
|
hmac username=" |
content-type
mandatory
|
string Must be set to application/json.
|
application/json |
Request body
| Parameter | Description | Example |
|---|---|---|
accountId
mandatory
|
string The unique Merchant Key provided by PayU for your merchant account. In v2, this replaces the 'key' parameter from v1.
Character limit: 50
|
|
txnId
mandatory
|
string Unique Transaction ID generated at your (Merchant's) end to track a particular order. In v2, this replaces the 'txnid' parameter from v1. If a transaction using a particular txnId has already been processed at PayU, reusing the same txnId will fail.
Character limit: 50
* **Note**: Ensure that the txnId sent in every transaction request is unique.
|
txn_12345 |
currency
mandatory
|
string Three-letter ISO currency code for the transaction.
Character limit: 3
|
INR |
order
mandatory
|
object Contains order-related information including product details, payment charge specification, and user defined fields. See detailed fields in the order JSON object fields section below.
|
Refer to order JSON object fields. |
billingDetails
mandatory
|
object Customer billing information. Combines customer contact and address details. See detailed fields in billingDetails JSON object fields.
|
Refer to billingDetails JSON object fields. |
callBackActions
mandatory
|
object Callback URLs for different payment outcomes. Replaces individual 'surl', 'furl', and 'curl' parameters from v1. See detailed fields in callBackActions JSON object fields.
|
Refer to callBackActions JSON object fields. |
additionalInfo
mandatory
|
object Additional configuration parameters for routing and transaction flow. See flow-specific documentation for details.
|
{ "txnFlow": "nonseamless" } |
paymentMethod
mandatory for seamless
|
object Payment method details required for seamless integration. Replaces 'pg' and 'bankcode' parameters from v1. For more information, refer to paymentMethod JSON object fields.
|
Refer to paymentMethod JSON object fields. |
order JSON object fields
| Field | Description | Example |
|---|---|---|
productInfomandatory
|
string Brief description of the product(s) or service being purchased. Replaces the 'productinfo' parameter from v1.Character limit: 100
|
iPhone 13 |
paymentChargeSpecificationmandatory
|
object Contains payment charge information including the transaction price and convenience fees.
|
{ "price": 1000.00 } |
paymentChargeSpecification.pricemandatory
|
number The transaction amount. In v2, this is passed as a numeric value inside the order object.
|
1000.00 |
paymentChargeSpecification.convenienceFeeoptional
|
string Convenience fee specification if dynamic convenience fee is configured on your merchant account.
|
CC:12,AMEX:19 |
userDefinedFieldsoptional
|
object User-defined parameters for passing merchant metadata. These replace individual udf1–udf5 parameters from v1. Only udf1 through udf5 are supported and returned in payment responses.Character limit: 255 for each field
|
{ "udf1": "value1", "udf2": "value2" } |
userDefinedFields.udf1 – udf5optional
|
string Merchant-defined metadata strings.Character limit: 255
|
order_ref_meta |
billingDetails JSON object fields
| Field | Description | Example |
|---|---|---|
firstNamemandatory
|
string Customer's first name. Replaces the 'firstname' parameter from v1.Character limit: 60
|
John |
lastNameoptional
|
string Customer's last name. Replaces the 'lastname' parameter from v1.Character limit: 20
|
Doe |
emailmandatory
|
string Customer's valid email address. Replaces the 'email' parameter from v1.Character limit: 50
|
[email protected] |
phonemandatory
|
string Customer's contact phone number (10-digit mobile number for Indian transactions). Replaces the 'phone' parameter from v1.Character limit: 50
|
9876543210 |
address1optional
|
string Customer's billing address line 1. Replaces 'address1' from v1.Character limit: 100
|
123 Main Street |
address2optional
|
string Customer's billing address line 2. Replaces 'address2' from v1.Character limit: 100
|
Apartment 4B |
cityoptional
|
string Customer's billing city.Character limit: 50
|
Mumbai |
stateoptional
|
string Customer's billing state.Character limit: 50
|
Maharashtra |
countryoptional
|
string Customer's billing country.Character limit: 50
|
India |
zipCodeoptional
|
string Customer's billing postal/zip code.Character limit: 20
|
400001 |
callBackActions JSON object fields
| Field | Description | Example |
|---|---|---|
successActionmandatory
|
string Full HTTPS URL where PayU redirects the customer upon successful payment completion. Replaces 'surl' from v1.
|
|
failureActionmandatory
|
string Full HTTPS URL where PayU redirects the customer upon payment failure. Replaces 'furl' from v1.
|
|
cancelActionoptional
|
string Full HTTPS URL where PayU redirects the customer if the transaction is cancelled on the payment page. Replaces 'curl' from v1.
|
|
paymentMethod JSON object fields (only for Seamless Integration)
| Parameter | Description | Example |
|---|---|---|
name |
|
NetBanking |
bankCode |
|
SBIN |
paymentCard |
|
Refer to paymentCard section |
paymentCard JSON object fields (only for Seamless Card Payments)
| Field | Description | Example |
|---|---|---|
cardNumbermandatory for new card
|
string Credit/Debit card number. Must be between 13-19 digits and pass Luhn algorithm validation.Note: Omit when processing saved card tokens. |
4111111111111111 |
validThroughmandatory for card payments
|
string Card expiry date in MM/YYYY format.Character limit: 7 characters (MM/YYYY)
|
12/2026 |
ownerNamemandatory for new card
|
string Cardholder name printed on the card.Character limit: 50
|
John Doe |
cvvmandatory for card payments
|
string Card verification value (CVV/CVC).Character limit: 3-4 digits (3 for Visa/Mastercard, 4 for AMEX)
|
123 |
cardTokenmandatory for tokenized cards
|
string Saved card token for repeat / tokenized card transactions. Replaces 'store_card_token' from v1.
|
token_12345 |
cardTokenTypemandatory for tokenized cards
|
string Classification of the token.Allowed values: PAYU, NETWORK, ISSUER
|
NETWORK |
tavvconditional
|
string Token Authentication Verification Value (TAVV), required for network token transactions when performing device authentication.
|
kH8e... |
last4Digitsconditional
|
string Last 4 digits of the actual card number for tokenized transactions.
|
1111 |
Key Differences between v1 and v2 Payment API
Parameter Changes:
- key → accountId: Merchant key parameter renamed (max 50 chars).
- txnid → txnId: Transaction ID parameter renamed (max 50 chars).
- amount → order.paymentChargeSpecification.price: Amount passed as a number inside the order object.
- productinfo → order.productInfo: Product info organized inside the order object.
- firstname, lastname, email, phone → billingDetails object: Customer details grouped into a structured object.
- address1, address2, city, state, country, zipcode → billingDetails object: Address parameters structured under billingDetails.
- surl, furl, curl → callBackActions object: Direct string URLs for
successAction,failureAction, andcancelAction. - pg, bankcode → paymentMethod object: Grouped into
paymentMethod.nameandpaymentMethod.bankCode(seamless only). - ccnum, ccvv, ccexpmon, ccexpyr → paymentMethod.paymentCard object: Card parameters consolidated with
validThroughinMM/YYYY. - hash → authorization header: Cryptographic authentication generated per request and passed via HTTP headers.
- udf1-udf5 → order.userDefinedFields object: User-defined metadata passed as key-value pairs (udf1 to udf5 supported).
API Endpoints
- Test Environment:
https://apitest.payu.in/v2/payments - Production Environment:
https://api.payu.in/v2/payments - HTTP Method:
POST
Sample Request Format (Hosted Checkout):
{
"accountId": "<YOUR_MERCHANT_KEY>",
"txnId": "ORDER_TXN_1001",
"currency": "INR",
"order": {
"productInfo": "iPhone 13",
"paymentChargeSpecification": {
"price": 25000.00
},
"userDefinedFields": {
"udf1": "meta1",
"udf2": "meta2"
}
},
"billingDetails": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"phone": "9876543210",
"address1": "123 Main Street",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipCode": "400001"
},
"callBackActions": {
"successAction": "<redacted URL>",
"failureAction": "<redacted URL>",
"cancelAction": "<redacted URL>"
},
"additionalInfo": {
"txnFlow": "nonseamless"
}
}Sample Responses
Success Response (Seamless Final Status)
{
"status": "success",
"result": {
"paymentId": "PAY_abc123xyz789",
"txnId": "ORDER_TXN_1001",
"amount": 25000.00,
"currency": "INR"
},
"message": "Transaction successful"
}Pending Response (Hosted / 3DS Redirect)
{
"status": "PENDING",
"result": {
"checkoutUrl": "https://checkout.payu.in/pay/PAY_pending456"
},
"message": "Awaiting customer authentication"
}Failure Response
{
"status": "failed",
"error": {
"code": "PAYMENT_DECLINED",
"message": "Declined by bank"
},
"result": {
"paymentId": "PAY_failed789",
"txnId": "ORDER_TXN_1001"
}
}Error Codes
| Code | HTTP Status | Description | Resolution |
|---|---|---|---|
INVALID_AMOUNT | 400 | Invalid amount value | Ensure price is positive number |
INVALID_CURRENCY | 400 | Unsupported currency | Use supported currency code (e.g. INR) |
AUTHENTICATION_FAILED | 401 | Invalid HMAC signature or key | Verify authorization signature format and merchant secret |
DUPLICATE_REFERENCE | 409 | txnId already processed | Provide a new unique txnId |
PAYMENT_DECLINED | 422 | Payment declined by downstream issuer | Retry with another payment mode |
Next Steps
- Verify Transaction: Always call the Verify Payment API to retrieve the final transaction state.
- Handle Webhooks: Configure webhooks on the PayU merchant dashboard for server-to-server notifications.
