🚀 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

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:

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

📤 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

👉 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

🧾 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)

📌 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

🧭 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

✨ 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

🎖️ AeronPay — Secure. Fast. Reliable.

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