PayU offers multiple payment workflows suitable for your online payment collection and disbursement strategy with diverse requirements and operational realities. Your website’s payment workflow is an integral part of your customer’s shopping experience. After the customer adds the products to the shopping cart on your website and checkout, you need to offer various payment modes to make the shopping experience complete.

What is a payment gateway?

A payment gateway is a technology used by merchants to accept debit or credit card, UPI, wallets, EMI, etc. for purchases made by customers.

Benefits

Safer, faster, smoother transactions that give customers peace of mind.
Secure and protect customers from frauds.
Improves user experience, saves time, and empowers your customers.
Enables you to accept multiple payment types and cards securely
Reduces declined payments with real time transactions.

Why v2 APIs?

PayU v2 APIs represent a significant evolution in payment integration, offering improved developer experience, enhanced security, and better organization. This guide outlines the key advantages of migrating to v2 APIs.

📘
v1 APIs support:

PayU will continue support v1 APIs. No disruption to existing integrations

No immediate migration required - Continue operations without interruption

Seamless coexistence - v1 and v2 APIs can work together during transition

Optional migration - Upgrade to v2 for enhanced features when ready

Simplified Authentication

v2 APIs vs v1 APIs Authentication:

Feature	v1 APIs	v2 APIs
Method	Complex hashing mechanism	Header-based authentication
Response Parsing	Requires reverse hashing	Direct JSON parsing
Implementation	Complex hash generation	Simple header configuration
Debugging	Difficult due to hashing	Easy with standard headers

Benefits of v2 Authentication:

✅ Easier implementation and debugging
✅ Reduced complexity in handling authentication
✅ No need for reverse hashing to parse responses
✅ More secure and standard authentication approach

Better Parameter Organization

v2 APIs vs v1 APIs Parameter Structure:

Aspect	v1 APIs	v2 APIs
Structure	Large, flat list of parameters	Grouped JSON objects
Maintainability	Complex parameter management	Clean, organized structure
Readability	Difficult to understand relationships	Logical grouping of related data
Error Handling	Higher chances of mapping errors	Reduced parameter mapping errors

v2 API Structured Objects:

paymentMethod - Payment method details
paymentCard - Card-specific information
order - Order and product details
paymentChargeSpecification - Pricing information
additionalInfo - Additional configuration
callBackActions - Success/failure URLs
billingDetails - Customer billing information
authorization - 3DS authorization data

Enhanced Developer Experience

Developer Experience Improvements:

Feature	v1 APIs	v2 APIs	Impact
Learning Curve	Steeper due to hashing complexity	Gentler with standard practices	🟢 Faster onboarding
Code Readability	Complex parameter lists	Structured JSON objects	🟢 Better maintainability
Error Debugging	Hash validation issues	Clear parameter validation	🟢 Easier troubleshooting
Integration Time	Longer due to complexity	Faster with modern patterns	🟢 Reduced development time

v2 API request structure

Sample Request Structure

{
    "accountId": "smsplus",
    "txnId": "b5f2d8785768087678fm9",
    "amount": "1000",
    "paymentMethod": {
        "name": "CreditCard",
        "bankCode": "CC",
        "paymentCard": {
            "cardNumber": "5497774415170603",
            "validThrough": "05/2025",
            "cvv": "123",
            "ownerName": "Ashish"
        }
    },
    "order": {
        "productInfo": "Product details",
        "orderedItem": [
            {
                "itemId": "1",
                "description": "Product A",
                "quantity": 1,
                "amount": 1000
            }
        ],
        "userDefinedFields": {
            "udf1": "test1",
            "udf2": "test2",
            "udf3": "test3",
            "udf4": "test4",
            "udf5": "test5"
        },
        "paymentChargeSpecification": {
            "price": "1000"
        }
    },
    "additionalInfo": {
        "enforcePaymethod": "CC",
        "createOrder": true,
        "authOnly": false
    },
    "callBackActions": {
        "successAction": "https://checkout.payu.in/testCB/success",
        "failureAction": "https://checkout.payu.in/testCB/failure",
        "cancelAction": "https://checkout.payu.in/testCB/cancel"
    },
    "billingDetails": {
        "firstName": "Ashish",
        "lastName": "Kumar",
        "address1": "123 Main Street",
        "phone": "9123456789",
        "email": "[email protected]",
        "city": "Bharatpur",
        "state": "Rajasthan",
        "country": "India",
        "zipCode": "321028"
    },
    "authorization": {
        "eci": "05",
        "cavv": "AAABAWFlmQAAAABjRWWZEEFgFz",
        "flowType": "Frictionless",
        "threeDSTransID": "67b4c71f-19bf-4d97-bd09-4e3687dc9e42",
        "threeDSServerTransID": "eea30d14-71cf-41af-b961-f95b7d67dc93",
        "threeDSTransStatus": "Y",
        "threeDSTransStatusReason": "01",
        "aquirer_bin": "401200",
        "additionalInfo": {
            "authUdf1": "string",
            "authUdf2": "string"
        }
    },
    "threeDS2RequestData": {
        "threeDSVersion": "2.2.0",
        "deviceChannel": "APP"
    }
}

JSON Object Breakdown

Key JSON Objects in v2 APIs:

JSON Object	Purpose	Key Benefits
`paymentMethod`	Payment method configuration	Centralized payment type management
`paymentCard`	Card-specific details	Secure card data handling
`order`	Order and product information	Complete transaction context
`billingDetails`	Customer billing information	Organized customer data
`callBackActions`	Success/failure URLs	Clear flow management
`authorization`	3DS authentication data	Enhanced security handling

Recommended migration strategy

For Existing Merchants

Continued Support & Flexibility:

✅ v1 APIs remain fully supported - No disruption to existing integrations
✅ No immediate migration required - Continue operations without interruption
✅ Seamless coexistence - v1 and v2 APIs can work together during transition
✅ Optional migration - Upgrade to v2 for enhanced features when ready

Migration Benefits:

Enhanced security with header-based authentication
Better code maintainability with structured parameters
Access to new features and improvements
Future-proof integration approach

For New Merchants

v2-First Approach:

✅ Encouraged to use v2 APIs only - Start with the latest technology
✅ Access to latest features - All new capabilities available immediately
✅ Better long-term support - Priority support for v2 implementations
✅ Integration team guidance - Dedicated support for v2 implementation

Advantages for New Merchants:

Modern API design patterns from day one
Reduced complexity in initial setup
Better developer experience
Future-ready integration

🔗 API Availability & Compatibility

Current API Landscape:

Aspect	Status	Details
v2 API Coverage	🟢 Comprehensive	Covers most common payment use cases
Duplicate API Elimination	🟡 In Progress	v1 APIs with duplicate functionality being phased out
v1 Documentation	🔄 Being Updated	Adding disclaimers and v2 alternative links
Compatibility	✅ Full Support	Both versions work together seamlessly

🏗️ Modern Architecture

Built for Today's Standards:

Modern API Design: Following current REST API best practices
JSON-First Approach: Native JSON structure for better integration
Stateless Design: Improved scalability and reliability
Standard HTTP Methods: Conventional HTTP verb usage

🔒 Enhanced Security

Security Improvements:

Header-Based Authentication: Eliminates complex hashing requirements
Standard Security Practices: Industry-standard authentication methods
Reduced Attack Surface: Simplified authentication reduces vulnerabilities
Better Debugging: Easier to troubleshoot security issues

🛠️ Developer Experience

Development Advantages:

Clear Structure: Logical parameter grouping for better understanding
Reduced Complexity: No need for reverse hashing or complex calculations
Better Documentation: Structured approach enables clearer documentation
Faster Integration: Modern patterns reduce development time

🔮 Future-Proof Design

Long-Term Benefits:

New Feature Priority: All new features developed for v2 first
Enhanced Support: Priority support and maintenance for v2 APIs
Technology Evolution: Aligned with modern payment industry standards
Scalability: Better prepared for future growth and requirements

Get support

Our dedicated support team is here to assist you if you encounter any issues or have questions during your integration process. Visit https://help.payu.in and raise a ticket.