API Reference
Start typing to search…

Additional Info for Payment APIs

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. 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: 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. 		username="smsplus",
algorithm="sha512",headers="date",
signature="abcd1234..."

Request body

Parameter Description Example
accountId
mandatory 		string This parameter is the unique Merchant Key provided by PayU for your merchant account. In v2, this replaces the 'key' parameter from v1.
Character limit: 10 		smsplus
referenceId
mandatory 		string This parameter is known as Transaction ID (or Order ID). It is the order reference number generated at your (Merchant's) end. In v2, this replaces the 'txnid' parameter from v1. It is an identifier that you (merchant) would use to track a particular order. If a transaction using a particular reference ID has already been successful at PayU, the usage of the same Reference ID again would fail. Hence, you must post us a unique reference ID for every new transaction.
Character limit: 25 * **Note**: Ensure that the reference ID sent in every transaction request is unique. 		order_12345
order
mandatory 		object Contains order-related information including product details, payment charge specification, and user defined fields. See detailed fields in the order Object Fields section below. Refer to order JSON object field description.
billingDetails
mandatory 		object Customer billing information. This object combines and replaces individual v1 parameters like 'firstname', 'email', 'phone'. See detailed fields. For more information, refer to billingDetails JSON object field description. Refer to billingDetails JSON object field description.
callBackActions
mandatory 		object Callback URLs for different payment outcomes. This object replaces the individual 'surl' and 'furl' parameters from v1. For more information, refer to callBackActions JSON object field description. Refer to callBackActions JSON object field description.
additionalInfo
mandatory 		object Additional information required for payment processing. { "txnFlow": "nonseamless" }
additionalInfo.txnFlow
mandatory for non-seamless 		string Specifies the transaction flow type. Must be set to "nonseamless" for PayU-hosted integration. Not required for seamless integration. nonseamless
paymentMethod
mandatory for seamless 		object Payment method details required for seamless integration. This object replaces the 'pg' and 'bankcode' parameters from v1. For more information, refer to paymentMethod JSON object fields. Refer to paymentMethod JSON object fields.
paymentCard
mandatory for seamless card payments 		object Card details for seamless card payments. This object combines v1 parameters like 'ccnum', 'ccvv', 'ccexpmon', 'ccexpyr'. For more information, refer to paymentCard JSON object fields. Refer to paymentCard JSON object fields.

order JSON object fields

Field Description Example
productInfo
mandatory 		string Brief description of the product(s). This parameter replaces the 'productinfo' parameter from v1.
Character limit: 100 		iPhone
paymentChargeSpecification
mandatory 		object Contains payment charge information including the transaction amount. {
  "price": "1000.00"
}
paymentChargeSpecification.price
mandatory 		float The payment amount for the transaction. In v2, this is nested within the order object instead of being a top-level parameter like 'amount' in v1. 1000.00
userDefinedFields
optional 		object User-defined parameters that can be used for various purposes. These replace the individual udf1-udf5 parameters from v1. Available fields: udf1, udf2, udf3, udf4, udf5
Character limit: 255 for each field 		{
  "udf1": "value1",
  "udf2": "value2",
  "udf3": "value3",
  "udf4": "value4",
  "udf5": "value5"
}
userDefinedFields.udf1
optional 		string User defined field 1. This replaces the 'udf1' parameter from v1.
Character limit: 255 		value1
userDefinedFields.udf2
optional 		string User defined field 2. This replaces the 'udf2' parameter from v1.
Character limit: 255 		value2
userDefinedFields.udf3
optional 		string User defined field 3. This replaces the 'udf3' parameter from v1.
Character limit: 255 		value3
userDefinedFields.udf4
optional 		string User defined field 4. This replaces the 'udf4' parameter from v1.
Character limit: 255 		value4
userDefinedFields.udf5
optional 		string User defined field 5. This replaces the 'udf5' parameter from v1.
Character limit: 255 		value5

billingDetails JSON object fields

Field Description Example
firstName
mandatory 		string Customer's first name. This replaces the 'firstname' parameter from v1.
Character limit: 60 (Production), 20 (Test) 		John
lastName
optional 		string Customer's last name. This replaces the 'lastname' parameter from v1.
Character limit: 20 		Doe
email
mandatory 		string Customer's email address. This replaces the 'email' parameter from v1.
Character limit: 50 		[email protected]
phone
mandatory 		string Customer's phone number. This replaces the 'phone' parameter from v1.
Character limit: 50 		9876543210
address1
optional 		string Customer's billing address line 1. This replaces the 'address1' parameter from v1.
Character limit: 100 		123 Main Street
address2
optional 		string Customer's billing address line 2. This replaces the 'address2' parameter from v1.
Character limit: 100 		Apartment 4B
city
optional 		string Customer's billing city. This replaces the 'city' parameter from v1.
Character limit: 50 		Mumbai
state
optional 		string Customer's billing state. This replaces the 'state' parameter from v1.
Character limit: 50 		Maharashtra
country
optional 		string Customer's billing country. This replaces the 'country' parameter from v1.
Character limit: 50 		India
zipCode
optional 		string Customer's billing postal code. This replaces the 'zipcode' parameter from v1.
Character limit: 20 		400001

callBackActions JSON object fields

Field Description Example
successAction
mandatory 		object Action to be taken upon successful payment completion. This replaces the 'surl' parameter from v1. {
  "redirectUrl": "https://example.com/success"
}
successAction.redirectUrl
mandatory 		string URL to redirect after successful payment. This replaces the 'surl' parameter from v1.
Character limit: 50

Requirements: Must use HTTP/HTTPS protocol and be accessible for handling PayU responses. 		https://example.com/success
failureAction
mandatory 		object Action to be taken upon payment failure. This replaces the 'furl' parameter from v1. {
  "redirectUrl": "https://example.com/failure"
}
failureAction.redirectUrl
mandatory 		string URL to redirect after failed payment. This replaces the 'furl' parameter from v1.
Character limit: 50

Requirements: Must use HTTP/HTTPS protocol and be accessible for handling PayU responses. 		https://example.com/failure
cancelAction
optional 		object Action to be taken when payment is cancelled by the user. This replaces the 'curl' parameter from v1. {
  "redirectUrl": "https://example.com/cancel"
}
cancelAction.redirectUrl
optional 		string URL to redirect when payment is cancelled. This replaces the 'curl' parameter from v1.
Character limit: 50

Requirements: Must use HTTP/HTTPS protocol and be accessible for handling PayU responses. 		https://example.com/cancel

paymentMethod JSON object Fields (only for Seamless Integration)

Parameter Description Example

accountId
mandatory

String The merchant key provided by PayU during onboarding.

MERCHANT123

referenceId
mandatory

String Reference ID for transaction tracking and this must be unique for every transaction.

REF123456

amount
optional

String Amount of the transaction.
Note: This value will not be considered as the transaction. Only the details in the order.paymentChargeSpecificationparameter.pricefield will be considered.

1000

paymentMethod
mandatory

Object Details about the payment method used. For more information, refer to paymentMethod object fields description.

{
"name": "NetBanking",
"bankCode": "TESTNB"
}

order
mandatory

Object Details about the transaction order including product information, ordered items, user-defined fields, and payment charge specifications. For more information, refer to order object fields description

additionalInfo
mandatory

Object Additional information including enforced payment methods, single instalment, virtual payment address (VPA), and various options for user preferences during the transaction. For more information, refer to additionalInfo object fields description

callBackActions
mandatory

Object Actions to perform on the payment server in different scenarios. For example, success, failure, cancellation, cash on delivery, etc. For more information, refer to callbackActions object fields description

billingDetails
mandatory

Object Billing details of the customer including name, address, phone number, email, etc. For more information, refer to billingDetails object field descriptions.

paymentCard JSON object fields (only for Seamless Card Payments)

Field Description Example
cardNumber
mandatory for new card payments 		string Credit/Debit card number. This replaces the 'ccnum' parameter from v1. Must be between 13-19 digits (15 digits for AMEX, 13-19 digits for Maestro) and must be validated using the LUHN algorithm.
Character limit: 13-19 digits

Note: Not required when using saved card tokens. 		4111111111111111
validThrough
mandatory for card payments 		string Card expiry date in MM/YY format. This replaces the separate 'ccexpmon' and 'ccexpyr' parameters from v1.
Character limit: 5 characters (MM/YY)
Format: MM/YY where MM is two-digit month (01-12) and YY is two-digit year 		12/25
ownerName
mandatory for new card payments 		string Cardholder name as printed on the card. This replaces the 'ccname' parameter from v1.
Character limit: 50

Note: Not required when using saved card tokens. 		John Doe
cvv
mandatory for card payments 		string Card verification value. This replaces the 'ccvv' parameter from v1.
Character limit: 3-4 digits
Format: 3-4 digit number (3 digits for most cards, 4 digits for AMEX) 		123
cardToken
mandatory for saved card payments 		string Saved card token for repeat transactions. This replaces the 'store_card_token' parameter from v1.
Character limit: Variable length

Usage: When using saved cards, provide this token instead of cardNumber and ownerName. 		token_12345
tokenType
mandatory for saved card payments 		string Type of token being used. This replaces the 'storecard_token_type' parameter from v1.
Character limit: Variable length

Possible values:
• NETWORK_TOKEN (Network tokenization)
• ISSUER_TOKEN (Bank issued tokens)
• PAYU_TOKEN (PayU generated tokens) 		NETWORK_TOKEN

Character Limits Summary

Production vs Test Environment Differences:

  • firstName: 60 characters (Production), 20 characters (Test)
  • All other parameters have the same limits across both environments

Key Parameter Limits:

  • referenceId (txnid): 25 characters
  • productInfo: 100 characters
  • firstName: 60 characters (Production), 20 characters (Test)
  • lastName: 20 characters
  • email: 50 characters
  • phone: 50 characters
  • address1: 100 characters
  • address2: 100 characters
  • city: 50 characters
  • state: 50 characters
  • country: 50 characters
  • zipCode: 20 characters
  • successAction/failureAction/cancelAction URLs: 50 characters
  • userDefinedFields (udf1-udf5): 255 characters each

Card-Specific Formats:

  • cardNumber: 13-19 digits (15 for AMEX, 13-19 for Maestro)
  • validThrough: MM/YY format (MM: 01-12, YY: two-digit year)
  • cvv: 3-4 digits (3 for most cards, 4 for AMEX)

Key Differences between v1 and v2 _payment API

Parameter Changes:

  1. key → accountId: Merchant key parameter renamed
  2. txnid → referenceId: Transaction ID parameter renamed
  3. amount → order.paymentChargeSpecification.price: Amount moved to nested object
  4. productinfo → order.productInfo: Product info moved to order object
  5. firstname, lastname, email, phone → billingDetails object: Customer details grouped into object
  6. address1, address2, city, state, country, zipcode → billingDetails object: Address fields grouped
  7. surl, furl, curl → callBackActions object: Callback URLs restructured
  8. pg, bankcode → paymentMethod object: Payment method details grouped (seamless only)
  9. ccnum, ccvv, ccexpmon, ccexpyr → paymentCard object: Card details grouped (seamless only)
  10. hash → authorization header: Authentication moved to header
  11. udf1-udf5 → order.userDefinedFields object: User defined fields grouped

New Parameters in v2:

  • currency: Transaction currency (mandatory)
  • paymentSource: Payment source identifier (optional)
  • additionalInfo.txnFlow: Flow type for non-seamless integration
  • callBackActions.cancelAction: Cancel callback support

Integration Flow Changes:

  • Non-seamless: Must include additionalInfo.txnFlow = "nonseamless"
  • Seamless: Requires paymentMethod and paymentCard objects
  • Headers: Authentication moved to headers with date-based signature
  • Structure: More modular with nested objects for better organization

API Endpoints

v2 Endpoints:

  • Test Environment: https://apitest.payu.in/v2/payments
  • Production Environment: https://api.payu.in/v2/payments
  • HTTP Method: POST

Request Format:

{
  "accountId": "merchant_key",
  "referenceId": "unique_transaction_id",
  "currency": "INR",
  "order": {
    "productInfo": "Product description",
    "paymentChargeSpecification": {
      "price": "1000.00"
    }
  },
  "billingDetails": {
    "firstName": "John",
    "email": "[email protected]",
    "phone": "9876543210"
  },
  "callBackActions": {
    "successAction": {
      "redirectUrl": "https://example.com/success"
    },
    "failureAction": {
      "redirectUrl": "https://example.com/failure"
    }
  },
  "additionalInfo": {
    "txnFlow": "nonseamless"
  }
}
Ask AI Beta

Hi! I am an AI Assistant. Ask me about PayU and get help with your integration.
Responses are generated by AI, may contain some mistakes.

EXAMPLE QUESTIONS