Webhooks
About Aeropay Webhooks
Aeropay allows you to subscribe to a number of webhooks which will send information about transactions when they update. These webhooks allow you to understand in real-time when transactions are created, succeed, decline, or are refunded.
Webhook Topics
| Topic Name | Payment Rails | Description |
|---|---|---|
| transaction_completed | ACH, RfP, RTP | This topic will send a payload of a transaction object when the transaction is approved by Aeropay. Note: Approved transactions will batch and settle at the next batch window, < 24 hours. When approved, a transaction will be in "Pending" status until 3 business days after the transaction was created. |
| transaction_voided | ACH, RfP, RTP | This topic will send a payload of a transaction object when the transaction is voided. |
| transaction_refunded | ACH, RfP, RTP | This topic will send a payload of a transaction object when the transaction is refunded. If a transaction is voided or partially voided before the payment is batched, this topic will not be sent. Please see transaction_voided topic. The data object's refundTransaction array lists reversals that already have a reversal transaction created, and queuedRefunds lists reversals that are still queued or were abandoned (e.g. NSF/void) - the status on each item distinguishes the two. Both arrays are always present and are empty when not applicable. |
| transaction_declined | ACH, RfP, RTP | This topic will send a payload of a transaction object when the transaction declines. |
| preauthorized_transaction_created | ACH | This topic will send a payload of a preauthorized transaction object when the preauthorized transaction is created. |
| user_suspended | N/A | This topic will send a payload of a userid when a user is suspended. |
| user_active | N/A | This topic will send a payload of a userid when a previously suspended user has been reactivated. |
| merchant_reputation_updated | N/A | This topic will send a payload of a users whose reputations have been updated after a successful call to POST /merchantReputation. |
Webhook Flowchart for ACH Payment
Webhook Flowchart for RfP Payment
Aeropay Webhook Outbound IP Addresses to Whitelist (if Applicable)
Sandbox Server
- 3.223.196.167
- 34.235.82.59
Production Server
- 54.237.135.163
- 54.81.239.48
Webhook Retries
If your webhook endpoint temporarily can't process events, Aeropay will automatically resends the undelivered events to your endpoint, increasing the time for your webhook endpoint, with exponential backoff and jitter, to eventually receive and process all events.
Aeropay will retry webhooks if:
- Callback URL fails to respond within 3000ms
- Callback URL fails to respond with 200 status code
Aeropay will attempt up to 5 total retries.
In the case of a major outage event of your platform, you can contact your dedicated Aeropay CSM to handle missed events during your downtime.
Subscribing to a webhook
HTTP request
Sandbox - POST https://api.sandbox-pay.aero.inc/v2/webhook
Production - POST https://api.aeropay.com/v2/webhook
Code Example - Request
curl --request POST \
--url https://api.sandbox-pay.aero.inc/v2/webhook \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer {{merchantScopedToken}}' \
--data '
{
"topic": "transaction_declined",
"url": "https://your-callback-url.com"
}
'Code Example - Payload from Webhook
{
"topic": "transaction_completed",
"data": {
"id": "b1ebceb4-74f3-4702-928f-df655798084f",
"amount": {
"amount": 123,
"currency": "USD"
},
"status": "pending",
"paymentType": "payment",
"userId": "0908b07b-01a3-4226-b48a-44c0984b2906",
"title": "Online Transaction",
"referenceId": "newReferenceID-TestinMatt21",
"apFee": "0.02",
"createdDate": "2026-01-23T18:53:03+00:00",
"isRtp": false,
"merchantId": 582,
"locationId": 541,
"userAccountId": 192637
},
"payloadVersion": "2.0",
"date": "2026-01-23 18:53:13"
}
{
"topic": "user_suspended",
"data": {
"userid": "a1b2c3d4-5e6f-7890-abcd-ef1234567890"
},
"payloadVersion": "2.0",
"date": "2024-04-05 15:25:49"
}Webhook Responses
| Webhook | Webhook response |
|---|---|
| transaction_completed | |
| transaction_refunded | |
| transaction_voided | |
| transaction_declined | |
| preauthorized_transaction_created | |
| user_suspended | |
| user_active | |
| merchant_reputation_updated | |