Guides
Start typing to search…

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

Description

transaction_completed

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

This topic will send a payload of a transaction object when the transaction is voided.

transaction_refunded

This topic will send a payload of a transaction object when the transaction is refunded.

transaction_declined

This topic will send a payload of a transaction object when the transaction declines.

preauthorized_transaction_created

This topic will send a payload of a preauthorized transaction object when the preauthorized transaction is created.

user_suspended

This topic will send a payload of a userid when a user is suspended.

user_active

This topic will send a payload of a userid when a previously suspended user has been reactivated.

merchant_reputation_updated

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 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.

Subscribing to a webhook

HTTP request

Sandbox - POST https://api.sandbox-pay.aero.inc/webhook

Production - POST https://api.aeropay.com/webhook

Code Example - Request

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/webhook \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "topic": "transaction_declined",
  "url": "https://your-callback-url.com"
}
'

Code Example - Payload from Webhook

{
  "topic": "transaction_declined",
  "data": {
    "locationId": "794",
    "paymentType": "payment+",
    "createdDate": "1694787546",
    "amount": "15.00",
    "merchantId": "582",
    "status": "declined",
    "uuid": "8bc20976-2e18-4c5c-93b4-20fd853d78a4",
    "attributes": [{ "value": "3.00", "name": "tip", "description": "flat" }],
    "id": "231933",
    "userId": "12695",
    "title": "Online Transaction",
    "apFee": "0.28",
    "returnCode": "R01"
  },
  "date": "2024-04-05 15:25:49"
}
{ 
  "topic" :  "user_suspended",
  "data" :  { "userid" :  "12695" },
  "date": "2024-04-05 15:25:49"
}

Webhook Responses

Webhook

Webhook response

transaction_completed

{
  "topic": "transaction_completed",
  "data": {
    "merchantId": "1602",
    "userId": "1102575",
    "paymentType": "payment",
    "status": "pending",
    "apFee": "0.75",
    "id": "1658635",
    "title": "test void webhook",
    "uuid": "e15db623-6727-4d56-a9a6-74af861ee75a",
    "createdDate": "1723735128",
    "locationId": "2985",
    "amount": "25.00",
    "attributes": []
  },
  "date": "2024-08-15 15:19:02"
}

transaction_refunded

{
  "topic": "transaction_refunded",
  "data": {
    "uuid": "5e571b4b-f182-48ef-8c5a-abc624e04f56",
    "title": "1658388", // transactionId of the original transaction
    "attributes": [],
    "id": "1658636", // transactionId of the refund
    "amount": "5.00",
    "status": "refunded",
    "paymentType": "reversal",
    "userId": "1102575",
    "locationId": "2985",
    "merchantId": "1602",
    "createdDate": "1723735777",
    "apFee": "0.25"
  },
  "date": "2024-08-15 15:29:40"
}

transaction_voided

{
  "topic": "transaction_voided",
  "data": {
    "merchantId": "1602",
    "userId": "1102575",
    "paymentType": "payment",
    "status": "void",
    "apFee": "0.75",
    "id": "1658635",
    "title": "test void webhook",
    "uuid": "e15db623-6727-4d56-a9a6-74af861ee75a",
    "createdDate": "1723735128",
    "locationId": "2985",
    "amount": "25.00",
    "attributes": []
  },
  "date": "2024-08-15 15:19:02"
}

transaction_declined

{
  "topic": "transaction_declined",
  "data": {
    "locationId": "794",
    "paymentType": "payment+",
    "createdDate": "1694787546",
    "amount": "15.00",
    "merchantId": "582",
    "status": "declined",
    "uuid": "8bc20976-2e18-4c5c-93b4-20fd853d78a4",
    "attributes": [{ "value": "3.00", "name": "tip", "description": "flat" }],
    "id": "231933",
    "userId": "12695",
    "title": "Online Transaction",
    "apFee": "0.28",
    "returnCode": "R01"
  },
  "date": "2024-04-05 15:25:49"
}

preauthorized_transaction_created

{
  "topic": "preauthorized_transaction_created",
  "data": {
    "id": "24141",
    "transactionId": "None",
    "merchantId": "1602",
    "merchantAccountId": "1190",
    "merchantLocationId": "2985",
    "userId": "1102575",
    "userAccountId": "749960",
    "userName": "Brett Neibarger",
    "userEmail": "[email protected]",
    "amount": "1500",
    "dollarAmount": "15.00",
    "originalAmount": "1500",
    "description": "Online Transaction",
    "merchantReputationStatus": "0",
    "userReputationStatus": "5",
    "uuid": "5dd8af88-8284-4a8a-aac1-058fbe40d85a",
    "createdDate": "1723735276",
    "expiryDate": "1723994476",
    "cancellationDate": null,
    "creditPartnerId": null,
    "status": "live"
  },
  "date": "2024-08-15 15:21:16"
}

user_suspended

{
  "topic": "user_suspended",
  "data": {
    "userid": "1102575"
  },
  "date": "2024-08-15 15:41:33"
}

user_active

{
  "topic": "user_active",
  "data": {
    "userid": "1102575"
  },
  "date": "2024-08-15 15:42:17"
}

merchant_reputation_updated

{
  "topic": "merchant_reputation_updated",
  "data": {
    "totalUsersUpdated": 3,
    "totalFailures": 0,
    "totalNotEligibleUsers": 0,
    "failedReputationUpdates": [],
    "notEligibleUsers": [],
    "successfulReputationUpdates": [
      {"userId": 12695, "previousReputation": null, "currentReputation": 1},
      {"userId": 1103154, "previousReputation": 1, "currentReputation": 0},
      {"userId": 13055, "previousReputation": 2, "currentReputation": 0}
    ]
  },
  "date": "2024-07-31 21:36:16"
}

Updated 6 days ago

What’s Next