Introduction
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 detailspaymentCard
- Card-specific informationorder
- Order and product detailspaymentChargeSpecification
- Pricing informationadditionalInfo
- Additional configurationcallBackActions
- Success/failure URLsbillingDetails
- Customer billing informationauthorization
- 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.
Updated 3 days ago