AeronPay Payout API – Technical Handling Guidelines

HTTP Status Code	API `status`	Meaning	Developer Action
200	SUCCESS	Transaction fully processed and confirmed	Update to Success → Stop further checks
201	PENDING	Request accepted, processing initiated; transaction queued	Mark as Pending → Wait for Webhook / Poll after time window
202	ACCEPTED	Request accepted and sent to the bank server, but bank confirmation awaited (asynchronous flow)	Treat as Pending → Use Status Check API or Wait for Webhook Response
400	FAILED	Validation error / Business rule failure (wrong input)	Fix request → Create new transaction (DO NOT RETRY same Client Reference ID)
403	BAD_REQUEST_ERROR	Authentication, IP Whitelist, or Compliance restriction	Check client-id / secret / mapped mobile / IP whitelist and retry only after correcting the issue

Important Note:

If the status is shown as “Accepted” in the AeronPay Dashboard or returned as “ACCEPTED (202)” from the Status Check API, it indicates that the transaction request has been successfully submitted to our Partner Bank’s server and is currently awaiting final confirmation from the bank.

At this stage, the funds are already in bank-level processing, and AeronPay cannot cancel, reverse, or modify the transaction until the bank provides the final success/failure result. Any further action strictly depends on the Partner Bank’s response.

Detailed Interpretation

200 — SUCCESS

Meaning:

The bank confirmed the credit
utr (UTR number) available for IMPS/NEFT/RTGS/UPI
Funds were settled to the beneficiary

Merchant MUST:

Mark transaction SUCCESS
Send an acknowledgement in the Webhook handling

201 — PENDING

Used when:

Request stored and queued for processing
Bank processing will occur shortly

Merchant MUST:

Mark as PENDING
Wait for Webhook → If not received, use Status Check API
No duplicate retries

202 — ACCEPTED (Processing…)

Used when:

Our partner bank accepted the payout request
Final status will arrive asynchronously

Merchant MUST:

Treat as PROCESSING / PENDING
Query status only if not updated by Webhook

Recommendation:

Poll after a minimum of 5 minutes (if required)

400 — FAILED (Immediate Error)

Cause:

Wrong request format
Invalid IFSC / account / VPA
Insufficient wallet balance
Mandatory parameter missing

Merchant MUST:

Fix the issue
Trigger fresh transaction with a new client_referenceId

Do NOT retry automatically with the same ID — risk of duplicate failure routing.

403 — FAILED / BAD_REQUEST_ERROR

Cause:

Client ID / Secret mismatch
Mobile mapping mismatch
IP not whitelisted
API permission blocked by AeronPay

Merchant MUST:

Verify:
- client-id
- client-secret
- Whitelisted IP
- Mobile mapped with your merchant account

Retry only after correction.

Decision Tree (Quick Developer Guide)

API Response Code:
 |
 |-- 200 → SUCCESS → Update Ledger → Done
 |
 |-- 201 / 202 → PENDING → Wait Webhook → Poll only if required
 |
 |-- 400 → FIX request → Retry NEW transaction ID
 |
 |-- 403 → FIX credentials/IP/permissions → Retry SAME transaction ID after correction

Best Practices

✔ Always rely on Webhook for final settlement confirmation ✔ Use Transaction Status API only if Webhook not received ✔ Use unique client_referenceId for each logical payout ✔ Do not auto-retry 400 (business logic issue) ✔ Log all response codes with timestamps

Can Include Table in Developer Console UI

Status Code	Label in Panel / Dashboard	Final State
200	Success	Closed
201	Pending	Pending at AeronPay Server
202	Accepted	Pending at Bank Server
400	Failed	Closed
403	Not Status / Transaction Available in Panel	Closed (Manual Intervention)

1. API Response Samples

AeronPay Payout APIs use only the following HTTP status codes:

200 – SUCCESS (final)
201 – PENDING (queued)
202 – ACCEPTED (processing)
400 – FAILED (input/business error)
403 – BAD_REQUEST_ERROR / UNAUTHORIZED / ACCESS_DENIED

1.1. 200 – Success (Final)

Use case: Transaction successfully processed and credited.

{
  "status": "SUCCESS",
  "statusCode": "200",
  "message": "Transfer completed successfully.",
  "data": {
    "transactionId": "ARNPY17612928477231167",
    "client_referenceId": "PAYOUT_20251207_0001",
    "amount": 1500.50,
    "utr": "322017636298",
    "acknowledged": 1,
    "description": "Transaction Successful"
  }
}

How to handle (merchant side):

Mark transaction as SUCCESS in your system.
Store transactionId, client_referenceId, utr for reconciliation.
No further retries required.

1.2. 201 – Pending (Received)

Use case: Request is stored and pending for processing. Bank will be hit shortly.

{
  "status": "PENDING",
  "statusCode": "201",
  "message": "Payout request received and queued for processing.",
  "data": {
    "transactionId": "ARNPY17612928477230001",
    "client_referenceId": "PAYOUT_20251207_0002",
    "amount": 50000.00,
    "utr": "",
    "acknowledged": 0,
    "description": "Awaiting bank processing."
  }
}

Merchant action:

Mark transaction as PENDING.
Wait for Webhook.
If webhook not received within the allowed window, use Status API.

1.3. 202 – Accepted (Processing at Bank)

Use case: Request accepted and forwarded to partner bank. Final response is asynchronous.

{
  "status": "ACCEPTED",
  "statusCode": "202",
  "message": "Transfer request has been submitted to the bank and is under processing.",
  "data": {
    "transactionId": "ARNPY17612928477231168",
    "client_referenceId": "PAYOUT_20251207_0003",
    "amount": 999.00,
    "utr": "",
    "acknowledged": 0,
    "description": "Transfer request successfully submitted to the bank. Final status will be shared via webhook or status enquiry."
  }
}

Merchant action:

Treat as processing (PENDING).
Do not trigger another payout.
Wait for Webhook or use Status API if no webhook after the configured waiting period.

1.4. 400 – Failed (Validation / Business Error)

Use case: Input or business rule error. Nothing sent to bank.

Example 1 – Invalid account details

{
  "status": "FAILED",
  "statusCode": "400",
  "message": "Payout request validation failed.",
  "data": {
    "transactionId": null,
    "client_referenceId": "PAYOUT_20251207_0004",
    "error_code": "INVALID_ACCOUNT",
    "error_message": "Beneficiary account number or IFSC is invalid.",
    "acknowledged": 0,
    "description": "Please verify beneficiary bank details and try again with a new reference ID."
  }
}

Example 2 – Transaction not allowed

{
  "status": "FAILED",
  "statusCode": "400",
  "message": "Transaction not allowed for this account.",
  "data": {
    "transactionId": null,
    "client_referenceId": "PAYOUT_20251207_0005",
    "error_code": "TXN_NOT_ALLOWED",
    "error_message": "Payouts are restricted for this customer/tag. Contact support for enabling the service.",
    "acknowledged": 0,
    "description": "No amount has been debited. Do not retry automatically."
  }
}

Merchant action (for any 400):

Do not auto-retry with the same request.
Fix the root cause (data / config / permissions).
Initiate a new payout with a new client_referenceId if applicable.

1.5. 403 – Blocked / Unauthorized

Use case: Authentication / authorization / IP whitelist / compliance block.

{
  "status": "FAILED",
  "statusCode": "403",
  "message": "Access denied.",
  "data": {
    "transactionId": null,
    "client_referenceId": "PAYOUT_20251207_0006",
    "error_code": "ACCESS_DENIED",
    "error_message": "Your client credentials or IP address are not authorized for this API.",
    "acknowledged": 0,
    "description": "Verify client-id, client-secret, mapped mobile, API permissions and IP whitelisting."
  }
}

Merchant action:

Check:
- client-id / client-secret
- Whitelisted IP
- Merchant / mobile mapping
- API enablement (payout permissions)
Only retry after correction. Do not loop indefinitely on 403.

2. Webhook Response Guidelines

AeronPay sends webhooks for final payout status and other events.

2.1. Webhook HTTP Request (from AeronPay → Merchant)

Method: POST
Content-Type: application/json
Auth: HTTP Basic Auth (username & password configured in dashboard)
Body: JSON payload with final status

Sample Success Webhook Payload

{
  "status": "SUCCESS",
  "statusCode": "200",
  "transactionId": "ARNPY17612928477231167",
  "client_referenceId": "PAYOUT_20251207_0001",
  "txn_amount": 1500.50,
  "utr": "322017636298",
  "acknowledged": "1",
  "description": "Transaction Successful"
}

Sample Failure Webhook Payload

{
  "status": "FAILED",
  "statusCode": "400",
  "transactionId": "ARNPY17612929011399779",
  "client_referenceId": "PAYOUT_20251207_0007",
  "txn_amount": 9900.00,
  "acknowledged": "0",
  "description": "Transaction Failed at bank."
}

Sample Rejected Webhook Payload

{
  "status": "REJECTED",
  "statusCode": "400",
  "transactionId": "ARNPY17612929011399780",
  "client_referenceId": "PAYOUT_20251207_0008",
  "txn_amount": 1000.00,
  "acknowledged": "0",
  "description": "Transaction rejected due to beneficiary bank rules."
}

2.2. What Merchant MUST Do on Webhook

Verify Authentication
- Validate Basic Auth username:password.
- Reject with 401 if invalid (do not process the body).
Verify Payload
- Ensure required fields exist:
  - status, statusCode, transactionId, client_referenceId
- Validate txn_amount vs your original amount.
Update Ledger / DB
- Locate transaction by client_referenceId (and/or transactionId).
- Update final status, statusCode, utr, description.
- Ensure idempotency: if same webhook is received twice, do not double-post credit or change a final SUCCESS again.
Respond Quickly
- Always respond within a short timeout (e.g., 2–3 seconds).
- Use HTTP 200 on successful processing.

2.3. Recommended Merchant Webhook Response Body

While AeronPay primarily cares about HTTP 200, we recommend sending a JSON acknowledgement for your own logging and clarity.

On successful processing:

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

On failure to process (e.g., internal DB error):

{
  "http_status": false,
  "status": "FAILED",
  "client_referenceId": "PAYOUT_20251207_0001",
  "statusCode": "500",
  "acknowledged": "0"
}

Note:

From AeronPay’s side, a webhook is considered “delivered” if your server returns HTTP 200.

You should log all webhook attempts and responses for audit.

2.4. Webhook URL Configuration (in Partner Panel)

Path inside Partner Panel:

Login Partner Panel
  → Developers
    → Developer Settings
      → Credentials (Top-right)
        → Callback / Webhook URL Configuration

In this screen:

Enter your Webhook URL (HTTPS, e.g., https://merchant.com/aeronpay/webhook/payout).
Set Basic Auth Username & Password.
Save and test with a sample event if available.

3. Status Polling Strategies

Use the Transaction Status API only when needed—for example:

Webhook failed or not received.
Scheduled reconciliation.
Manual customer dispute / support ticket.

3.1. Recommended Rules

Primary Source of Truth = Webhook
- Always rely on webhook for final status whenever possible.
When to Poll
- For 201 / 202 responses:
  - Wait for at least 15 minutes after initiation before first status enquiry.
- Subsequent polling:
  - Maintain at least 2-hour gap between status calls for the same client_referenceId to avoid overload.
What to Send
- Always query with:
  - client_referenceId
  - Registered mobile / merchant identifier
What to Expect
- Status values like:
  - SUCCESS
  - FAILED
  - REJECTED
  - PENDING
- Along with transactionId, utr, and description.

3.2. Status Polling Behaviour per Code

When you call Status API, you again receive HTTP status in [200, 400, 403] set.

200:
- Check status field.
- SUCCESS → mark final success.
- FAILED / REJECTED → mark final failure.
- PENDING → schedule another check after 2 hours (if required).
400:
- Possibly bad client_referenceId or missing fields.
- Fix params before re-polling.
403:
- Auth / IP issue on status API.
- Fix configuration, but do not spam.

4. Retry Logic Examples

Below are reference snippets showing how to implement safe retry logic.

Never retry blindly on 400 or permanently on 403.
For payout initiation:
- Use same client_referenceId on retry only if previous attempt failed due to technical/network issue.
For status enquiry:
- Respect time windows (15 min + 2 hours).

5. Visual Flow Diagrams (Text / ASCII)

You can copy these into your docs or into tools like draw.io / Whimsical.

5.1. End-to-End Payout Flow

+-------------------+        +-------------------+        +---------------------+
|   Merchant System |        |    AeronPay API   |        |   Partner Bank      |
+-------------------+        +-------------------+        +---------------------+
          |                           |                             |
          | 1. Payout Request (IMPS)  |                             |
          |-------------------------->|                             |
          |                           |                             |
          |     2. HTTP 200/201/202   |                             |
          |<--------------------------|                             |
          |   (SUCCESS/CREATED/ACCEPTED)                            |
          |                           | 3. Send to Bank             |
          |                           |---------------------------->|
          |                           |                             |
          |                           |    4. Bank Final Status     |
          |                           |<----------------------------|
          |                           |                             |
          |    5. Webhook (SUCCESS/FAILED/REJECTED)                 |
          |<--------------------------|                             |
          |                           |                             |
          | 6. (Optional) Status API  |                             |
          |-------------------------->|                             |
          |   Final Status Response   |                             |
          |<--------------------------|                             |

5.2. Webhook Handling Flow (Merchant-side)

           +-----------------------------+
           |   AeronPay Webhook Sender   |
           +-----------------------------+
                         |
                         v
              POST /aeronpay/webhook/payout
                         |
                         v
         +------------------------------------+
         |   Merchant Webhook Endpoint        |
         +------------------------------------+
         | 1. Verify Basic Auth               |
         |    - If invalid → HTTP 401         |
         |                                    |
         | 2. Parse JSON Payload              |
         |    - status, statusCode,          |
         |      transactionId,               |
         |      client_referenceId, amount   |
         |                                    |
         | 3. Idempotency Check              |
         |    - Locate by client_referenceId |
         |    - If already FINAL, ignore     |
         |                                    |
         | 4. Update Ledger / DB             |
         |    - SUCCESS / FAILED / REJECTED  |
         |    - Store utr, description       |
         |                                    |
         | 5. Log event for audit            |
         |                                    |
         | 6. Return HTTP 200 + JSON ack     |
         +------------------------------------+

5.3. Status Polling & Retry Logic

 Start Payout
     |
     v
Receive HTTP 200 / 201 / 202 ?
     |
     +--> 400 ? ----> Log & show error to user
     |                (DO NOT RETRY same payload)
     |
     +--> 403 ? ----> Fix client-id / IP / permissions, then
     |                optionally retry once
     |
     +--> 200 (SUCCESS) ? --> Mark SUCCESS → End
     |
     +--> 201 / 202 (CREATED/ACCEPTED) ?
           |
           v
      Mark PENDING
           |
           v
   Wait for Webhook
           |
           +--> Webhook received ? --> Update final state → End
           |
           +--> No webhook (timeout)
                 |
                 v
        Call Status API (after 15 min)
                 |
                 v
       If PENDING → schedule next status call
                     (2-hour gap)
       If SUCCESS / FAILED / REJECTED → update and END