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 has released a new major version of our API documentation: v2. This update is Aeropay's first major version update of all API endpoints. The v2 API endpoints are more efficient, standardized, and secure.
Notable changes from v1 to v2
RESTful API URIs
Aeropay has updated the API URIs to more RESTful.
OLD URL
NEW v2 URL
POST /token
POST /v2/token
GET /preauthTransaction
GET /v2/preauthTransaction/preauthTransactionId
Standardized Error Messages
All error messages follow the same standard format, below.
// example error message 1
{
"error": {
"help": "contact [email protected] for help",
"code": "AP113",
"message": "User does not exist"
}
}
// example error message 2
{
"error": {
"code": "AP701",
"message": "Improperly formatted parameter: ['id']"
}
}
Transaction Identifiers
In the Aeropay v2 API transaction UUID values were merchant identifiers and unique transaction identifiers. In v2 API, transaction UUIDs are still unique, idempotent values for transactions. But the referenceId field, a new parameter, is used as a merchant identifier of a transaction.
In the Aeropay v2 API userId values will all follow standard UUID format. In v1 API, userIds were integers.
OLD userId v1
New userId v2
15456
49681f36-bbe0-4038-b024-a5d86584255a
User MFA Flow
In the Aeropay v2 API, Aeropay added support for SMS 2FA on both new and network users. By default, SMS 2FA will be sent for all new and existing network users when POST /v2/user is called.
mfaType
The new mfaType parameter can have a value of 'sms', 'email', or null, and can be used to determine both if an MFA code as been sent and by what protocol.
When migrating from v1 to v2 endpoints, your current logic to look for 'existingUser' can be replaced with looking for a non-null mfaType.
bankAccounts
The response structure for POST /v2/user has also been updated to remove the bankAccounts array. A user's linked bankAccounts are now fetched from a new endpoint GET /v2/bankAccounts.
When migrating from v1 to v2 endpoints, you will now rely on the new bankAccounts endpoint to fetch and display a user's linked banks.
Idempotency-Key Header Support
V2 introduces support for the Idempotency-Key header on POST /v2/reverseTransaction. When included, Aeropay stores the response for that key and returns the same outcome on any retry, preventing duplicate refunds on network errors or timeouts. The same key cannot be used with a different request body. Idempotency is optional; if no key is sent, duplicate protection is not applied.
Aerosync SDK v2.0+
Aeropay v2 APIs require Aerosync SDK v2.0+. If you are migrating from v1 to v2, you must also migrate to Aerosync SDK v2.0+.
Additional Changes from v1 to v2
Authentication header — header key renamed from authorizationToken to authorization
Amount format — amount is no longer a string in dollars; v2 expects an object with value in pennies and a currency code
/reverseTransaction — changed from a GET to a POST
/linkAccountFromAggregator — no longer accepts user_id and user_password; v2 expects connectionId from the Aerosync SDK (v2.0+ only)
As part of recent reporting enhancements, Aeropay has added an explicit RTP identifier. As of October 1st 2025, a new column will be added to the daily SFTP reports called ACH/RTP Identifier. Accepted values in this column are either RTP or ACH depending on which rails the payment was processed through.
Ensure your reporting systems are setup to properly handle this change and accept this new column.
As part of recent architecture updates, Aeropay released a new URL for the Aeropay Merchant Portal in both sandbox and production. Beginning Monday, July 14th 2025, Aeropay will begin forwarding all old portal URLs to the new URL format.
While the old URL format will continue to be active as it forwards to the new site, we recommend updating any bookmarks or saved links to our new portal URL. Please see the URL changes below:
Aeropay released a new sandbox environment for testing purposes which will replace Aeropay's existing staging environment. This new environment is more stable and efficient, providing more reliable testing and faster integrations.
During this transition period, Aeropay will share data between the sandbox environment and staging environment to ensure a smooth transition between environments if this change is occurring during your integration.
When will staging be deprecated?
The staging environment will be available until May 22nd, 2025, at which point all Aeropay testing must use the sandbox environment. This means updating any testing API URLs to sandbox and using the new sandbox merchant portal.
🚀 Aerosync Web SDK v1.1.1 - Release Date: 4/22/2025
✨ New Feature
Embedded Bank View (Optional)
You can now embed a list of Aerosync-supported banks directly into your webpage using the new embedded view feature. This offers a smoother and more integrated user experience.
Learn more here: https://dev.aero.inc/docs/embedded-view
🐛 Bug Fixes
Fixed flashing issue when launching the widget in dark mode.
Resolved unintended onClose event trigger during successful bank linking.
General code cleanup and several minor bug fixes for better performance and stability.
⚠️ Breaking Changes (for v1.1.0 and earlier)
If you're upgrading from v1.1.0 or below, take note of the following breaking changes:
openWidget() ➡️ renamed to initAeroSyncWidget()
– Use the new function name to initiate the widget.
Widget Config: id ➡️ renamed to elementId
– Update your HTML reference in the widget configuration.
Event Handling Change:
– Now, only onSuccess() is triggered after a successful bank link and widget close.
– Previously, both onSuccess and onClose were fired together.
– Make sure to listen to onSuccess() to handle success actions like updating your UI or navigating to the next step.
ℹ️ Note for v2.x.x Users
If you're already using v2.x.x, no changes are needed.
This update is specifically targeted at 1.x.x clients who haven’t migrated yet.
Updated end user experience across all Aeropay SDK integrations and payment links. These changes include a new landing page UI with more scalable customization capabilities.
Fixed bugs affecting search for preauthorized transactions by user name or transaction id
Enhancements
Aeropay
New aeropassUUID parameter added to response to POST /user and GET /user. AeropassUUIDs are unique identifiers for users across Aeropay's suite of products.
