Skip to content

India (UPI) H2H Integration

This guide covers H2H payment integration for India using UPI (Unified Payments Interface). UPI allows customers to pay directly from their banking or wallet apps using QR codes or deeplinks.

Overview

Currency: INR (Indian Rupee)
Payment Method: UPI (Unified Payments Interface)
User Experience: Customer stays on your website, scans QR code or clicks payment link

Payment Flow

  1. Initiate Payment: Call /h2h/initiate with INR currency
  2. Display Options: Show QR code for desktop users, payment buttons for mobile users
  3. Customer Pays: Customer scans QR code or clicks app-specific links
  4. Automatic Confirmation: Most (~70-95%) of payments confirm automatically within 60 seconds
  5. Manual Verification: Some payments (~5-25%) may require proof submission

Warning

The actual share of automatically and manually confirmed payments may vary based on the Merchant's business risk profile. Contact support to learn specifically about your situation.

HTTP Request

POST http://{{DOMAIN}}/h2h/initiate

Request Example

curl -X POST https://{{DOMAIN}}/h2h/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": 100.00,
  "currency": "INR",
  "customer": {
      "first_name": "Rajesh",
      "last_name": "Kumar",
      "email": "[email protected]",
      "mobile": "+919876543210"
  },
  "details": "Payment for order #123",
  "identifier": "order_123_unique_id",
  "ipn_url": "https://yourdomain.com/ipn",
  "success_url": "https://yourdomain.com/success",
  "cancel_url": "https://yourdomain.com/cancel",
  "site_name": "Your Store",
  "payment_method_type": "local"
}'

Response Example

{
  "status": "success",
  "trx": "UUID",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51...",
  "qr_content": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789",
  "paymentlinks": {
    "upi": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789",
    "upi1": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789&mode=01",
    "paytm": "paytmmp://cash_wallet?pa=merchant@upi&am=100.00&featuretype=money_transfer",
    "phonepe": "phonepe://pay?pa=merchant@upi&am=100.00",
    "gpay": "gpay://pay?pa=merchant@upi&am=100.00"
  }
}

Request Parameters

Parameter Required Description Example
public_key true Your API key "your_api_key"
amount true Amount in INR (minimum 1.00) 100.00, 250.50
currency true Must be "INR" for India "INR"
customer true Customer information See Customer Parameters
details true Payment description (max 255 chars) "Payment for order #123"
identifier true Unique payment ID (max 255 chars) "order_123_unique_id"
ipn_url true Webhook URL for status updates "https://yourdomain.com/ipn"
success_url true Success redirect URL "https://yourdomain.com/success"
cancel_url true Cancel redirect URL "https://yourdomain.com/cancel"
site_name true Your website name "Your Store"
payment_method_type false Set to "local" for UPI "local"
site_logo false Your logo URL "https://yourdomain.com/logo.png"

Customer Parameters

Parameter Required Description Example
first_name true Customer's first name "Rajesh"
last_name true Customer's last name "Kumar"
email true Customer's email "[email protected]"
mobile true Indian mobile number "+919876543210"

Response Parameters

Parameter Description Example
status Request status "success"
trx Transaction ID for status checking "UUID"
qr_code Base64-encoded QR code PNG image "iVBO..."
qr_content Raw UPI payment string "upi://pay?pa=merchant@upi..."
paymentlinks App-specific payment links See Payment Links section

The response includes various UPI payment links optimized for different apps:

Link Type Description Availability
upi Standard UPI link - works with most banking apps Always present
upi1 Alternative UPI link May or may not present
paytm PayTM-specific deeplink When PayTM supports the payment
phonepe PhonePe-specific deeplink When PhonePe supports the payment
gpay Google Pay-specific deeplink When GPay supports the payment

App Link Availability

  • App-specific links (paytm, phonepe, gpay) are only included when that app supports the specific payment. If missing, the app likely won't accept this payment due to internal policies.
  • You may try to re-generate the link to get the specific app's deeplink if you need by simply sending another payment request. However, such strategy may significantly increase payment initiation time.

Fallback Strategy

Always use the generic upi link as a fallback. Most UPI-enabled apps can handle it.

Implementation Demo

Tip

You can get the source code of that demo by contacting support, if you need it as a sample for the integration. The demo is written in NextJS.

The demo flow is not something that is "set in stone" – it exists only for demonstration, so some UI/UX elements may feel redundand and not optimal. In real-use scenario it is you who are in control of how the payment flow actually looks on your side. The H2H solution is designed to give you the most possible freedom to design the UI/UX that is best for your customers' needs.

What to Expect

Automatic Confirmation

  • Success Rate: ~70-95% of UPI payments confirm automatically (varies based on several factors)
  • Timing: Usually within 10-60 seconds
  • Status: Monitor via status polling or IPN webhooks

Manual Verification

  • Occurrence: ~5-25% of payments (varies based on several factors)
  • Reason: UPI system delays, bank processing issues, etc.
  • Process: Customer submits payment proof → manual verification (usually 5-30 minutes)
  • Implementation: Proof submission guide

Error Handling

Common Error Response

{
  "status": "error",
  "message": ["No H2H flows available for this currency and merchant"]
}

Error Scenarios

  • Currency Mismatch: Ensure currency is "INR"
  • Amount Too Low: Minimum amount is usually ₹100.00
  • Invalid Mobile: Mobile number must be valid Indian format
  • Merchant Not Enabled: Contact support to enable UPI H2H

Best Practices

User Experience

  1. Responsive Design: Show QR codes on desktop, buttons on mobile
  2. Clear Instructions: Guide users on how to scan/click payment links
  3. Loading States: Show progress while waiting for payment confirmation
  4. Fallback Options: Always provide generic UPI option alongside app-specific links

Technical Implementation

  1. Status Monitoring: Implement both IPN webhooks and status polling
  2. Timeout Handling: Wait for the time you seem reasonable before requesting proof
  3. Error Recovery: Handle network failures and retry logic
  4. Security: Validate all IPN signatures properly

Next Steps