Best Practices

Never expose your apiKey, apiSecret, or API tokens in client-side code, browser console, or public repositories. All token generation must be server-to-server.
Store aeroPassUserUuid and connectionId encrypted at rest. Treat them as PII-adjacent identifiers.
Generate a fresh widget token on every new widget session. Never reuse tokens across user sessions or page refreshes.
Whitelist your origin URLs with Aeropay before go-live. The Web NPM SDK enforces this in production.
Validate HMAC-SHA256 signatures on every inbound webhook payload. Reject any webhook without a valid signature.
Set and rotate your webhook secret_key on a schedule. Store it in a secrets manager — not an environment variable committed to source control.
Monitor connectionExpiry on all linked accounts and proactively surface the reconnection widget to users before expiry.

Always show a loading state while the widget token is being generated server-side. Never let the "Connect Bank" button be interactive until the token is ready.
Implement onClose gracefully. Users who close the widget without completing bank linking are a common dropout point. Surface a soft prompt to retry.
For balance and transaction jobs, show an async progress indicator. These jobs can take 5–15 seconds at real FIs.
Surface the MFA widget immediately when mfaTriggered is detected. Do not make users wait to be prompted for their security code.
Use the reconnection widget for expired or failed connections rather than asking users to re-link from scratch.
Use configurationId to match the widget to your app's branding. The default Aerosync branding can feel out of place in your product.
Test all three Aerosync Test Banks in sandbox: MFA, OAuth, and Security Question (MFA Trigger). Your production traffic will encounter all three.

Persist connectionId the moment it arrives in onSuccess — before any additional API calls. A lost connectionId requires the user to re-link their bank.
Check canFetchBalance: true from GET /accounts before triggering a balance refresh job. Skip the job and inform the user if it's false.
Do not fire concurrent jobs of the same type on the same connectionId. The API returns AC-112 (Conflict) and will reject the second request.
Set a maximum polling timeout (e.g., 90 seconds / 30 attempts) and surface a user-friendly error if the job does not complete in time.
Cache retrieved account/routing numbers server-side where your use case allows, to avoid triggering a full job flow on every page load.

Do not call POST /v2/token on every API request. Generate once, cache in memory, and refresh ~60 seconds before expiry.
If you receive AC-108 (MFA lockout — Too Many Requests), surface a clear message to the user. Do not retry automatically.
AC-110 (MFA session timeout) is a timed event. Build your MFA widget re-launch flow to complete within the FI's MFA session window — typically well under 5 minutes.