🚀 AeronPay Webhooks — Advanced Integration & Security Guidelines (2025 Release)

AeronPay uses secure, real-time webhook callbacks to notify your system about payout status updates. To ensure high-availability, zero-duplicate settlement, and robust financial compliance, merchants must strictly follow this integration guide.

Version Release

Product	Release Status	Version	Compliance Required	Date of Release
Transaction Notify Webhook	Live	`"2.3.12"`	Mandatory	04-12-2025
Validation-Based Webhook	Live	`"3.7.1"`	Mandatory	16-11-2025

Allowed Domain & Validation

The domain example.com represents your official brand / entity domain. All API, webhook, and callback endpoints must be hosted only on your registered brand domain or its approved subdomains.

This policy ensures security, brand authenticity, and regulatory compliance.

Allowed Domain Structure

Only the following domain patterns are permitted:

Base Brand Domain	Allowed Usage	Example URL
`example.com`	Primary website	`https://example.com/path`
`example.com`	API endpoint	`https://api.example.com/path`
`example.com`	Webhook endpoint	`https://webhook.example.com/path`
`example.com`	Callback endpoint	`https://callback.example.com/path`

Validation Rules

The domain must exactly match the brand domain registered in your account
Only first-level subdomains of the approved domain are allowed
The webhook/callback domain must match your whitelisted website domain
HTTPS (SSL) is mandatory

Not Allowed

The following are strictly prohibited:

Third-party or unrelated domains
Free hosting domains (e.g., *.ngrok.io, *.vercel.app, *.herokuapp.com)
Redirected or shortened URLs
IP-based endpoints (e.g., http://123.45.67.89)

Security Enforcement

The system continuously validates webhook and callback URLs.

If any of the following are detected:

Domain mismatch
Unapproved or unrelated subdomain
Domain not matching the registered website

then the webhook will be automatically disabled by the security algorithm.

Compliance Deadline:

Non-compliant webhook or callback URLs will be blocked automatically without prior notice.

🔔 Supported Event Types

Event	status	statusCode	Severity	Description
Transaction Successful	SUCCESS	`"200"`	🟢 Normal	Amount settled & credited to beneficiary
Transaction Failed	FAILED	`"400"`	🔴 High	Reversal/refund triggered as per system
Duplicate Update	DUPLICATE	`"208"`	⚠️ Medium	Already processed earlier — no changes required
Transaction Rejected	REJECTED	`"422"`	🚫 Critical	Validation/Compliance rejection

📤 Webhook Request — AeronPay → Merchant

🟢 SUCCESS Event

{
  "status": "SUCCESS",
  "statusCode": "200",
  "transactionId": "ARNPY1761214621245562",
  "client_referenceId": "{{unique_id}}",
  "txn_amount": 8500,
  "acknowledged": "1",
  "utr": "5124558962145631",
  "description": "Transaction Successful"
}

🔴 FAILED Event

{
  "status": "FAILED",
  "statusCode": "400",
  "transactionId": "ARNPY1761214621245562",
  "client_referenceId": "{{unique_id}}",
  "txn_amount": 9900,
  "description": "Transaction Failed"
}

📥 Mandatory Merchant Acknowledgment — Merchant → AeronPay

Return JSON response within 0–7 seconds and HTTP 200 OK

⚠ Must echo same client_referenceId

1️⃣ If processed successfully in your system

{
  "http_status": true,
  "status": "SUCCESS",
  "client_referenceId": "{{unique_id}}",
  "statusCode": "200",
  "acknowledged": "1"
}

2️⃣ If received but failed internally

{
  "http_status": true,
  "status": "FAILED",
  "client_referenceId": "{{unique_id}}",
  "statusCode": "400",
  "acknowledged": "1"
}

3️⃣ If duplicate (already processed)

{
  "http_status": true,
  "status": "DUPLICATE",
  "client_referenceId": "{{unique_id}}",
  "statusCode": "208",
  "acknowledged": "1"
}

🔁 Retry Logic & Delivery Confirmation

Merchant Reaction	AeronPay Action
Valid SUCCESS response	🟢 Stop Retry
DUPLICATE response	⚠️ Stop Retry
Delayed / No Response / Error	🔁 Retry up to 3 times
Continual failure	❌ Webhook marked as Failed Delivery

👉 Full visibility available in 📍 Partner Panel → Webhooks → Delivery History

🛡 Security Best Practices (Strongly Enforced)

AeronPay meets financial compliance benchmarks including PCI-DSS, RBI Mandate, and ISO 27001. To retain security throughout communication, merchants must comply with:

🔐 Endpoint Level Security

Control	Mandate	Notes
HTTPS (TLS 1.2+)	✔ Required	Self-signed certs not allowed
Domain + Valid SSL	✔ Required	Regular expiry check
Publicly Accessible Endpoint	✔ Required	No VPN-restricted URL
Do not expose logs/debug	✔ Required	Prevent data leaks

🧾 Request Validation Guidelines

✔ Validate JSON body ✔ Validate presence of all fields ✔ Validate transaction amount matches order ✔ Validate your known reference IDs (client_referenceId) ✔ Sanitize all incoming strings ✔ Reject invalid parameters immediately

🆔 Authentication & Protection (Enabled Options)

Feature	Support	Recommendation
HMAC SHA-256 Signature Verification	✔	Adopt for fraud safety
Basic Authentication	✔	Username + password should be rotated every 90 days
IP Allow-Listing	✔	Recommended (ask AeronPay for static CIDRs)
Anti-Replay Timestamp & Nonce	✔	Required for high-risk transactions

📌 No sensitive info like server stack, port, token should be revealed in response.

🧠 Idempotency Handling (Mandatory)

✔ Always use client_referenceId as a unique reference token ✔ Prevent double credit, double refund, or repeated status updates ✔ Store the first processed webhook status — ignore duplicates

🚀 Webhook Performance Expectations

Requirement	Benchmark
Processing time	≤ 10 seconds
Availability	99.9% uptime
Error Display	Silent handling (no debug traces)
JSON Response	Must always return HTTP 200

🧭 Webhook Configuration — Partner Panel Guide

To configure your Webhook URL:

1️⃣ Login to Partner Panel 2️⃣ Navigate → Developers 3️⃣ Open Developer Setting 4️⃣ Click Credentials (Top Right Corner) 5️⃣ Under Callback URL, enter your valid HTTPS webhook endpoint 6️⃣ Save & perform webhook Test Fire

📍 Ensure callback is reachable before activating live transactions.

🧪 Testing Recommendations

Use the following tools before switching to production:

✔ curl command tests ✔ Postman mock server tests ✔ Custom staging environment tests

Example test:

curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test":"webhook"}'

🆘 Support Channels

Channel	Details
Production Email Support	integration.support@aeronpay.in
Documentation	https://developers.aeronpay.in/
SLA	10AM–7PM IST, Mon–Sat

✨ Why This Upgrade?

Eliminates duplicate settlement risks
Ensures stricter financial security
Improves reconciliation speed
Supports upcoming HMAC-based validation
Enables full audit-grade transaction tracking

🏁 Final Compliance Checklist

Check	Status
Webhook URL HTTPS valid certificate	☐
JSON parsing + strict schema validation	☐
Idempotency enforcement implemented	☐
Successful test webhook acknowledgment sent	☐
Logging of transaction events enabled	☐

🎖️ AeronPay — Secure. Fast. Reliable.

Give your customers & beneficiaries a supersmart payout experience with zero operational risk ✨