This checklist applies to direct API integrations using standard, preauthorized, and/or payout transactions. Make sure you've completed the universal production setup items before working through this page.

---

User Creation & Management

User Authentication

• Aeropay's SMS 2FA is required for all users.
  • Email 2FA alone is not an approved verification method for production integrations.
  • VOIP, landline, and prepaid phone numbers are not supported in production.

User management

• Only call POST /user only after a user has selected Aeropay (or "Pay by Bank") at checkout.
• Call GET /bankAccounts at least once per user session to ensure you are displaying a user's most current list of connected banks.
  • If a new user already has connected bank accounts through the Aeropay network, display the connected accounts with the option to link a new bank account.
• Check the userStatus field from GET /user (or subscribe to the user_suspended & user_active webhooks) to verify a user's status before allowing them to submit a payment.
  • Display an error message to suspended users prompting them to contact [email protected].

Testing

• Run a test of creating a new user.

---

Aerosync Bank Connections

Aerosync Customization Preferences

If applicable, provide the following so we can configure your Aerosync widget appearance:

• Light mode or dark mode preference
• Your logo in .svg format (horizontal orientation preferred)
• Preferred button color (hex code)

Aerosync SDK Configuration

• Ensure you are passing the correct configurationId value when launching the Aerosync SDK to render customizations (if applicable).
• Confirm that any requested Aerosync customizations (light/dark mode, logo, button color) are rendering correctly.
• If using the Web NPM Aerosync SDK, ensure your application's origin URLs are whitelisted. Refer to the SDK guide for details (if applicable).
• For mobile applications: Implement OAuth support and deep linking. OAuth flows work without additional setup on web, but mobile experiences require a deeplink to redirect users back from the OAuth login. See our OAuth Connections guide.

Bank Connection Tests

• Run a test of a new user linking their first bank account.
• Run a test of an OAuth bank connection to verify the redirect flow. Use the Aerosync (OAuth) test bank in the sandbox environment. This is especially critical for mobile applications.
• If a user wants to remove a bank account, direct them to [email protected]. This ensures the user is not attempting to circumvent pending payments or outstanding recovery.

---

Payments

Run the following tests for each transaction type your integration supports. Not all test cases will be applicable.

Standard Transactions

• Run a successful test of a standard transaction (pay-in): /transaction
• Run a test of a rejected payment. Ensure you handle this gracefully - how to test

Preauthorized Transactions

• Run a successful test of creating and capturing a preauth transaction: /preauthTransaction & /capturePreauthTransaction
• Ensure you are capturing payments before they expire. Preauthorized transactions expire 72 hours after creation.
• Ensure you have logic in place to update preauth transactions with PATCH /preauthTransaction.
• Ensure you have logic in place to cancel preauth transactions with DELETE /preauthTransaction.

Payout Transactions

• Run a successful test of a standard payout (same-day ACH): /payoutTransaction
  • If applicable, ensure you have logic to route payouts to RTP rails (real-time payment) via rtp param.
• If a payout is declined or voided, your system should re-credit the user's wallet or balance with the payout amount.

Refunds & Reversals

• Ensure you are able to void, partially refund, or fully refund a transaction using POST /reverseTransaction.

Tipping

• If you are accepting tips on your UI: run a successful transaction with the tip object populated in the /transaction call.

---

Checkout & Payment Page

• Do not display the last 4 digits of a user's bank account number when listing linked banks.

  • Instead, display the name and bankName returned from GET /bankAccounts (e.g., Bank of America, Adv. Checking).

  • Many large banks tokenize account numbers, so displaying tokenized digits can confuse end users.

• Display popular bank logos on your checkout page near the Aeropay or "Pay by Bank" option. Customers are more likely to select "Pay by Bank" when they see their bank's logo at checkout. More info: UX Guidelines.

• Use "Pay by Bank" language and Aeropay assets in your Aeropay payment option. This has been shown to outperform alternative wording.

---

Webhooks

General Webhook Requirements

• Webhook subscriptions are required for all API integrations.
• Ensure your system can receive webhooks from Aeropay's IP range (if applicable)
• Optional: implement webhook signature validation to verify the authenticity of incoming payloads.
• Webhooks in sandbox are a separate subscription from webhooks in prod. Subscribe to prod webhooks when you receive prod credentials.

Required

Strongly Recommended

You should subscribe to the following webhooks. If you choose not to, be prepared to explain your reasoning during integration review.

---

Error Handling

• Ensure your integration has graceful error-handling in place. See the full Error Glossary.

---

Fraud Prevention

• Name matching on user creation: When calling POST /user, compare the name your system provides in the request against the name returned in the response.

  • For network users, the name returned is the name on file with Aeropay and may differ from what your system passes. A name mismatch has historically been linked to fraud risk.
  • Performing this check is the merchant's KYC responsibility — if you choose not to implement name-matching logic, you are doing so at your own risk.

• User communication for voids: When a transaction is voided, surface the following message to the user:

  "We couldn't verify the full payment details for this transaction. Please try again with a different payment method, or contact [email protected]."

Stored Funds & Wallet Use Cases (If Applicable)

This section applies if your platform allows users to deposit funds into a wallet, player balance, or similar stored-value account.

• Ensure your system can freeze or deduct funds in the event of a major fraud event.
• Void handling best practices: A transaction_voided webhook can arrive hours after a transaction_completed webhook. A user may have already been credited and could attempt to withdraw funds before the void is processed. To mitigate this:
  • Implement a withdrawal waiting period for new users (min. 3 business days recommended).
  • Consider "play-through" requirements — require users to use deposited funds before allowing withdrawal.
  • Immediately suspend account activity when a user_suspended webhook is received. Re-activate on receiving user_active webhook.

---

Integration Approval

Once you've worked through the checklist above, submit the following to your Aeropay Solutions Engineer to complete your integration review.

Demo Videos

Share the following demos as screen-recorded videos or live on a video call. Each demo should cover the applicable transaction types in your integration (standard, preauth, payout).

• New user flow (new bank) — A new user on your platform goes through the MFA flow (/confirmUser) and completes a payment by linking a new bank.
• Network user flow (previously linked bank) — A new user on your platform goes through the MFA flow and completes a payment using a previously linked bank.
  • In this scenario, a new user to your platform bypasses the bank linking flow because they have bank account(s) already linked with another Aeropay merchant (network user).
  • Scenario setup: remove the test user from your platform database. Then you can go through the user onboarding flow where you call POST /user, then /bankAccounts to display the user's existing banks.
• Returning user flow — A returning user completes a payment with a previously linked bank account.
• For mobile applications (if applicable): Provide a mobile demo including a bank connection test using the Aerosync (OAuth) test bank to verify deep linking is working correctly. See our OAuth Connections guide.

Integration Questions

Provide answers or confirmation for each item:

• Does your integration call GET /v2/bankAccounts at least once per user session? (Yes/No)
• For returning users and network users, are their linked banks always displayed at checkout before payment completion? (Yes/No)
• What webhooks is your system subscribed to? What automations are in place when webhook payloads are received? (List webhooks + describe logic)
• Are you using your provided configurationId value when launching Aerosync? (Yes/No)
• If using the Web NPM Aerosync SDK, share your application's origin URL (base URL/domain) in both sandbox and production.
• Have you added Aeropay's Terms of Service excerpt to your Terms of Service? (Provide link — see Integration Agreement, Section 6)
  • Added hyperlink within excerpt: https://www.aeropay.com/legal/terms-of-service---end-user
• Have you added Aeropay's Privacy Policy excerpt and hyperlink to your Privacy Policy? (Provide link — see Integration Agreement, Section 6)
  • Added hyperlink within excerpt: https://www.aeropay.com/legal/privacy-policy