v1 → v2 API Migration Guide

Overview

This guide walks API clients through upgrading from Aeropay v1 to v2. 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

One of the most significant changes between v1 and v2 is the user identifier. In v1, userId could be either an integer or a UUID. In v2, it is always a UUID. That UUID is the same value as v1’s aeroPassUserUuid.
Prepare your stored user identifiers before cutting existing users over to v2. This does not affect your v1 traffic.

1. Start storing UUIDs for new users. While your integration still uses v1, save each new user’s aeroPassUserUuid alongside their existing Aeropay user ID and your own customer identifier. Retain legacy IDs for historical reconciliation.
2. Request a CSV for existing users. Contact your Aeropay Solutions Engineer to coordinate a CSV export mapping your existing Aeropay users to their UUIDs. Aeropay will confirm the customer cohort and delivery details with you. This is the recommended bulk migration approach, rather than paging through your entire customer base using GET /searchCustomersForMerchant.
3. Import and reconcile the mappings. Match the export to your customer records and work with Aeropay to resolve missing mappings before cutting those users over. Continue storing UUIDs for new users while the export is being prepared.
   
   Sandbox development and testing can proceed while the historical backfill is coordinated.

Migration Steps

Step 1 — Code changes

These are the per-request changes you'll need to 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.
• Preauth capture id: in v1, capturing a preauthorized transaction created a new, separate transaction id. In v2, the id assigned at POST /v2/preauthTransaction persists through capture — POST /v2/capturePreauthTransaction returns that same id, and it's the id referenced in the transaction_completed webhook.

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.

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 (recommended)

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 supplied in your migration export—or returned as aeroPassUserUuid through v1—is the same value used as userId in v2. You do not need to recreate existing users.

FAQs

Can existing v1 users be reused in v2? Yes. Use their existing aeroPassUserUuid as userId in v2. You do not need to recreate users or relink their banks solely because you are migrating. Retrieve their active bank accounts through GET /v2/bankAccounts.

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? Keep each user’s active integration flow on one API version during cutover. You can migrate users in batches. Existing user identities and bank connections work across versions; this guidance concerns keeping request contracts, identifiers, SDK behavior, and webhook handling consistent within a user’s flow. Keep handling v1 webhooks for in-flight v1 transactions.

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.

How do I obtain UUIDs for a large existing customer base? First, begin storing UUIDs for new users. Then contact your Aeropay Solutions Engineer to coordinate a CSV export for your existing customer cohort. Import and reconcile those mappings before cutting existing users over.