v1 → v2 API Migration Guide

Overview

This guide walks API clients through upgrading from Aeropay v1 to v2. For the full list of what changed and why, see the v2 release notes. This guide focuses on the how: the sequence of changes, what to test, and what to expect post-cutover.

Your existing sandbox and production credentials work for v2 — no new keys to provision.

Preparation

Backfilling your stored user IDs can happen before any code changes. It does not affect your v1 traffic.

In v1, userId could be either an integer or a UUID. In v2, it's always a UUID. The value you want is the v2-compatible UUID, which is the same value as the v1 aeroPassUserUuid.

To backfill:

• Call v1 searchCustomersForMerchant to retrieve UUIDs for all of your existing users.
• Update your stored references so that every user record holds the UUID.

Migration Steps

Step 1 — Code changes

These are the per-request changes you'll make across your integration. Do this in sandbox first.

A few of these deserve a closer look:

• referenceId: in v2, the transaction UUID is Aeropay's identifier. If you need a merchant-side identifier on a transaction, send referenceId on the /transaction call. It will be echoed back on transaction webhooks.
• MFA flow: by default, SMS 2FA is sent for all new and existing network users when POST /v2/user is called. Replace any logic that checks for existingUser with a check for non-null mfaType in the response.
• bankAccounts: the GET /v2/user response no longer includes a bankAccounts array. To display linked banks for a user, call GET /v2/bankAccounts.

Step 2 — Aerosync SDK upgrade

v2 APIs require the latest Aerosync SDK versions (Web NPM 2.0+, React Native 4.0+, etc.). Older SDK versions are not compatible with v2.

When configuring the widget for v2, you must pass:

• token from GET /v2/aggregatorCredentials
• aeroPassUserUuid from the POST /v2/user response
• configurationId — formerly consumerId. Reuse the same value; only the parameter name changed.

🚧

Missing any of these parameters will cause the onSuccess callback to return data that does not match the expected v2 format. See the Aerosync Integration Guides for the latest SDK-specific configuration details.

Step 3 — Webhook subscriptions

v1 and v2 webhook subscriptions are separate. v1 subscriptions will not fire for v2 API activity, so you'll need to add v2 subscriptions before cutting over. There's no need to delete your v1 subscriptions to use v2 — they'll continue firing for v1 traffic during the migration and afterward for any in-flight v1 transactions. Once v1 traffic has fully drained, you can optionally delete them (see Step 3.3).

You can identify v2 webhook payloads in your handler by the "payloadVersion": "2.0" field.

Step 3.1 — Retrieve your current v1 webhook subscriptions

If you want to confirm which topics you're subscribed to in v1, use the v1 GET /webhook endpoint:

curl --request GET \
     --url https://api.sandbox-pay.aero.inc/webhook \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{merchant token}}'

Step 3.2 — Subscribe using the v2 API

Use the v2 POST /v2/webhook endpoint to subscribe to the topics you want to receive v2 events for.

curl --request POST \
     --url https://api.sandbox-pay.aero.inc/v2/webhook \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{merchant token}}' \
     --data '{"topic": "{{topic}}", "url": "{{your webhook URL}}"}'

Repeat for each topic you want to receive events for.

Step 3.3 — Delete v1 webhook subscriptions (optional)

Once all v1 traffic has fully drained, you can clean up your v1 webhook subscriptions using the v1 DELETE /webhook endpoint. You'll need the webhookId for each topic (retrieved in Step 3.1).

curl --request DELETE \
     --url https://api.sandbox-pay.aero.inc/webhook \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{merchant token}}' \
     --data '{"topic": "{{topic}}", "webhookId": "{{webhookId}}"}'

Repeat for each topic.

Step 4 — Cutover

Once your code changes are tested in sandbox and your v2 webhooks are subscribed in prod, begin cutting over your prod traffic to the v2 base URL. All new traffic will hit v2 endpoints and emit v2 webhooks.

Testing

Before going live, run through the API Integrations Launch Checklist. This covers test scenarios and best practices for v2.

What to Expect Post-Cutover

• In-flight v1 transactions continue to settle. Any transaction created against v1 will continue to emit v1-format webhooks until it fully clears. Keep your v1 webhook handler running until v1 traffic fully drains.
• v2 webhooks fire from v2 API calls. Any transaction created against a v2 endpoint will emit v2-format webhooks ("payloadVersion": "2.0"), including the new referenceId field where applicable.
• User identity is stable across versions. The UUID returned by v1 searchCustomersForMerchant is the same value as userId in v2 (and aeroPassUserUuid in v1). The user is the same user across both versions.

FAQs

Can existing v1 users be reused in v2? Yes. Their UUID — retrieved from v1 GET /user (as aeroPassUserUuid) or v1 searchCustomersForMerchant — is the same value as userId in v2. You don't need to recreate users.

Are credentials the same between v1 and v2? Yes. Your existing sandbox and production credentials work for v2 — no new keys to provision.

Can I migrate endpoint by endpoint? Not recommended. v1 and v2 can't practically run side-by-side for the same user. You can cut users over in batches, but don't mix v1 and v2 endpoints within a single user's flow.

Is there a v1 deprecation deadline? TBD.

Is the latest Aerosync SDK backward compatible with v1? No. Latest versions of the Aerosync SDK require v2 APIs.

Does MFA always run on POST /v2/user? Yes, by default. SMS 2FA is sent for all new and existing network users. The mfaType field in the response indicates whether and how the code was sent. The default is SMS.

What is configurationId? It's the renamed consumerId from earlier SDK versions. Same concept, new name. Use it in your Aerosync SDK configurations where you previously passed consumerId.