Integration Process

Introduction

Aerosync is Aeropay's bank aggregation product. It gives your application a single, standardized way to:

Authenticate your end users with their financial institution (FI) via a secure, embeddable widget
Retrieve account numbers (tokenized and non-tokenized) and routing numbers for ACH payments
Pull real-time balances to verify funds availability before initiating a transaction
Fetch transaction history for underwriting, analytics, or KYC workflows
Retrieve account holder identity data (name, address, email) directly from the FI

Core Pillars

Every Aerosync integration is built on three sequential pillars. Understanding the relationship between them is essential before you begin.

Aeropass user

This is a persistent user identity in the Aeropay network via the Aeropass API. Key identifier: aeroPassUserUuid - a permanent identifier stored in your database and passed to every widget launch.

Bank linking widget

The Aerosync widget so the user authenticates with their bank via the secure iframe. Key identifier: connectionId — a per-bank-link identifier used for all subsequent data calls against that account

Bank data jobs

Trigger async jobs to pull live data (balance, transactions, identity) from the financial institution. Each job will return a structured data payload (balance, transactions, identity) fetched after polling confirms COMPLETED status. Key identifier: jobId - an identifier for the specific requested job.

Concept Glossary

Term	Definition	Relevant API
aeroPassUserUUID	Persistent UUID representing a user in the Aeropay network. Required for widget launch.	POST /user (Aeropass base URL)
connectionId	Unique identifier for a specific user-to-bank link. Used in every data API call.	onSuccess() callback from the widget
configurationId	UUID used for tracking and applies your custom branding (logo, colors, dark/light mode) to the widget.	Provided by your Aeropay Solutions Engineer
Widget token	Short-lived JWT used to initialize the widget for one session. TTL is 1,800 seconds (30 min).	POST /v2/token_widget (Aerosync base URL)
API token	Bearer token for server-side Aerosync API calls. 1,800 second TTL (30 min).	POST /v2/token (Aerosync base URL)
jobId	Unique ID for a single aggregation job run (e.g., REF-xxx for balance, TXN-xxx for transactions).	POST /accounts/connectionId/refresh (or /transactions or /identity)
Job status	Enum: Initiated \| IN_PROGRESS \| COMPLETED \| FAILED \| MFA_REQUIRED. Listen to webhooks or poll until terminal state.	GET /accounts/connectionId/job/jobId
MFA	Multi-factor auth challenge issued by the FI during a job. Must be surfaced to user via widget re-launch.	Detected via mfaTriggered: true in job status response
sandbox	Fully isolated test environment. Uses dedicated base URLs and Aerosync Test Banks — no real FI data.	api.sandbox.aerosync.com
production	Live environment. Requires IP/origin whitelisting, certified integration, and Aeropay SE approval	api.aerosync.com

Pre-integration checklist

Confirm all of the following with your Aeropay Solutions Engineer (SE) before writing any code:

Sandbox API key and secret for the Aerosync token endpoint received and stored securely
Sandbox API key, secret, and merchant ID for the Aeropass /user endpoint received separately
configurationId assigned (if using custom branding)
CORS origin URLs identified and shared with Aeropay for whitelisting (required before production go-live)
SDK method decided: Web NPM (v2.1.0+), React Native (v4.0+), iOS, Android, Flutter, or CDN
deeplink URL configured for mobile apps (required for OAuth bank flows)
Webhook endpoint URL registered with Aeropay and HMAC-SHA256 secret key generated
Reviewed the Aerosync Integration Agreement