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

Popular UPI Apps

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

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

Common UPI Handles

Bank/Provider	UPI Handle	Example
Paytm	@paytm	customer@paytm
PhonePe	@ybl	customer@ybl
Google Pay	@okaxis	customer@okaxis
Amazon Pay	@apl	customer@apl
BHIM	@upi	customer@upi
HDFC Bank	@okhdfcbank	customer@okhdfcbank
ICICI Bank	@okicici	customer@okicici
SBI	@oksbi	customer@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

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

Token

Home

Merchant API

Customer

Open Banking API

H2H

​UPI Payment Example

​Payment Request

​Key Features

​UPI-Specific Fields

​Customer Information

​Transaction Details

​UPI Overview

​What is UPI?

​Popular UPI Apps

​Implementation

​JavaScript Example

​UPI ID Validation

​Payment Flow

​1. UPI Payment Initiation

​2. UPI App Integration

​3. Payment Completion

​UPI Advantages

​For Customers

​For Merchants

​Testing

​Test UPI IDs

​Test Scenarios

​Common UPI Handles

​Error Handling

​Common UPI Errors

​Error Response Example

​Best Practices

​UPI ID Handling

​Mobile Optimization

​Security

​Regional Considerations

​Indian Market

​Compliance

​Next Steps