​
UPI Payment Example

This example demonstrates a UPI (Unified Payments Interface) payment request for the Indian market, including browser information for verification.

​
Payment Request

{
  "name": "Test User",
  "upiId": "upi-id",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  }
}

​
Key Features

​
UPI-Specific Fields

  • UPI ID: Customer’s UPI identifier (e.g., “customer@paytm”, “9876543210@ybl”)
  • Browser Info: Required for transaction verification and fraud prevention
  • Indian Context: Optimized for Indian payment ecosystem

​
Customer Information

  • Name: Account holder name matching UPI registration
  • Phone: Mobile number linked to UPI account
  • Email: Contact for transaction notifications
  • Address: Billing address for verification

​
Transaction Details

  • Amount: Transaction amount (typically in INR for UPI)
  • Reference: Merchant transaction reference
  • Callback URLs: Success, failure, and notification endpoints

​
UPI Overview

​
What is UPI?

UPI (Unified Payments Interface) is India’s instant real-time payment system developed by the National Payments Corporation of India (NPCI). It enables:
  • Instant money transfers between bank accounts
  • 24/7 availability
  • Mobile-first payment experience
  • QR code-based payments
  • Merchant payments
  • Google Pay (@okaxis, @okhdfcbank)
  • PhonePe (@ybl, @ibl)
  • Paytm (@paytm)
  • Amazon Pay (@apl)
  • BHIM (@upi)

​
Implementation

​
JavaScript Example

const upiPayment = {
  name: "Rajesh Kumar",
  upiId: "rajesh.kumar@paytm",
  email: "rajesh.kumar@email.com",
  phoneNumber: "+919876543210",
  address: "123 MG Road",
  city: "Bangalore",
  state: "Karnataka",
  postalCode: "560001",
  country: "IN",
  amount: 500.00,
  unit: "INR",
  originDomain: "mystore.com",
  referenceId: "ORDER-UPI-001",
  notifyUrl: "https://mystore.com/webhook/upi",
  successUrl: "https://mystore.com/payment/success",
  failureUrl: "https://mystore.com/payment/failure",
  browserInfo: {
    browserAcceptHeader: navigator.userAgent,
    browserColorDepth: screen.colorDepth.toString(),
    browserIP: "127.0.0.1", // Get from server
    browserJavaEnabled: navigator.javaEnabled(),
    browserJavascriptEnabled: true,
    browserLanguage: navigator.language,
    browserScreenHeight: screen.height.toString(),
    browserScreenWidth: screen.width.toString(),
    browserTZ: new Date().getTimezoneOffset().toString(),
    browserUserAgent: navigator.userAgent
  }
};

// Send UPI payment request
const response = await fetch('https://your-h2h-endpoint.com', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify(upiPayment)
});

const result = await response.json();
console.log('UPI Payment ID:', result.paymentRequestId);
console.log('Payment URL:', result.redirectUrl);

​
UPI ID Validation

function validateUpiId(upiId) {
  // Basic UPI ID format: username@bankcode
  const upiRegex = /^[a-zA-Z0-9.\-_]{2,256}@[a-zA-Z]{2,64}$/;
  
  if (!upiRegex.test(upiId)) {
    return false;
  }
  
  // Common UPI handles
  const validHandles = [
    'paytm', 'ybl', 'ibl', 'okaxis', 'okhdfcbank', 
    'okicici', 'oksbi', 'apl', 'upi', 'axl'
  ];
  
  const handle = upiId.split('@')[1];
  return validHandles.includes(handle);
}

// Usage
const isValid = validateUpiId("customer@paytm"); // true
const isInvalid = validateUpiId("invalid-upi"); // false

​
Payment Flow

​
1. UPI Payment Initiation

  • Customer enters UPI ID
  • Validate UPI ID format
  • Submit payment request with browser info
  • Receive payment URL

​
2. UPI App Integration

  • Customer redirected to UPI payment page
  • UPI app opens automatically (mobile)
  • Customer authorizes payment with UPI PIN
  • Transaction processed instantly

​
3. Payment Completion

  • Instant payment confirmation
  • Webhook notification sent
  • Customer redirected to success/failure page
  • Transaction status updated

​
UPI Advantages

​
For Customers

  • Instant Transfers: Real-time money movement
  • 24/7 Availability: No banking hour restrictions
  • Mobile Convenience: Pay using smartphone
  • No Card Details: No need to share card information
  • Free Transfers: Most UPI transactions are free

​
For Merchants

  • Low Cost: Minimal transaction fees
  • Instant Settlement: Immediate payment confirmation
  • High Success Rate: Direct bank-to-bank transfer
  • Mobile Optimized: Perfect for mobile commerce
  • Wide Adoption: Popular across India

​
Testing

​
Test UPI IDs

{
  "name": "Test User",
  "upiId": "test@paytm",
  "email": "test@example.com",
  "phoneNumber": "+919999999999",
  "country": "IN",
  "amount": 100.00,
  "unit": "INR"
}

​
Test Scenarios

  1. Valid UPI ID: Test with correct UPI format
  2. Invalid UPI ID: Test validation error handling
  3. Successful Payment: Complete UPI payment flow
  4. Failed Payment: Insufficient balance or declined
  5. Timeout: Customer doesn’t complete payment

​
Common UPI Handles

Bank/ProviderUPI HandleExample
Paytm@paytmcustomer@paytm
PhonePe@yblcustomer@ybl
Google Pay@okaxiscustomer@okaxis
Amazon Pay@aplcustomer@apl
BHIM@upicustomer@upi
HDFC Bank@okhdfcbankcustomer@okhdfcbank
ICICI Bank@okicicicustomer@okicici
SBI@oksbicustomer@oksbi

​
Error Handling

​
Common UPI Errors

  • Invalid UPI ID: Incorrect format or non-existent ID
  • Insufficient Balance: Customer account has insufficient funds
  • Transaction Limit: Exceeds daily/monthly UPI limits
  • Bank Decline: Issuing bank declined the transaction
  • Timeout: Customer didn’t complete payment in time

​
Error Response Example

{
  "error": {
    "code": "038",
    "message": "Invalid UPI",
    "description": "The provided UPI ID is invalid or not found"
  }
}

​
Best Practices

​
UPI ID Handling

  • Validate UPI ID format before submission
  • Support popular UPI handles
  • Provide clear error messages for invalid IDs
  • Allow customers to edit UPI ID easily

​
Mobile Optimization

  • Optimize for mobile browsers
  • Support UPI app deep linking
  • Handle app switching gracefully
  • Provide fallback options

​
Security

  • Always use HTTPS
  • Validate webhook signatures
  • Log transactions for audit
  • Monitor for suspicious patterns

​
Regional Considerations

​
Indian Market

  • Currency: Use INR (Indian Rupees)
  • Phone Format: +91 country code
  • Address: Indian address format
  • Language: Support Hindi and regional languages
  • Timezone: IST (Indian Standard Time)

​
Compliance

  • RBI Guidelines: Follow Reserve Bank of India regulations
  • NPCI Rules: Adhere to NPCI UPI guidelines
  • KYC Requirements: Ensure proper customer verification
  • Transaction Limits: Respect UPI transaction limits

​
Next Steps

  1. Integrate with UPI payment gateway
  2. Implement UPI ID validation
  3. Set up webhook handling for instant notifications
  4. Test with different UPI apps and scenarios
  5. Optimize mobile user experience
  6. Monitor transaction success rates