Guides

Subscriptions

Managing Subscriptions with Aeropay

Merchants can use Aeropay's standard transaction API to power any recurring billing model they build on their end. This document explains how that works, what users should see, and how merchants should handle edge cases like failed payments.

How It Works

The initial payment follows the standard Aeropay checkout flow. The user links their bank account, authorizes the payment, and completes the transaction. Once that initial payment goes through, the merchant has everything they need to charge the user on a recurring basis — no further action is required from the user.

From that point forward, the merchant calls POST /v2/transaction on whatever schedule their subscription logic dictates — monthly, weekly, daily, etc. Think of it as a cron job on the merchant's side that triggers Aeropay to pull payment from the user's linked bank account. Because the user already authorized Aeropay during onboarding, this is a merchant-initiated transaction against the payment details captured in the initial flow.

Step-by-step

  1. User goes through the normal Aeropay signup and bank linking flow and makes their first payment.
  2. Merchant captures the user's bank account details and stores any relevant Aeropay identifiers on their end.
  3. At each billing interval, the merchant's system calls POST /v2/transaction to collect payment.
  4. The user doesn't need to take any action for renewals.

User-Facing Messaging (at sign-up)

Because the user won't be actively present during renewal charges, it's critical that you set expectations clearly at sign-up. At minimum, users should see language like:

"By continuing, you authorize [Merchant Name] to automatically debit your linked bank account ([e.g., Checking account at Chase]) for $X every [30 days / month / billing period]. This authorization remains in effect until you cancel your subscription."

If you plan to support a secondary payment method as a fallback, you should also mention it upfront:

"If your primary payment method fails, [Merchant Name] may attempt to charge your secondary payment method on file."

This transparency protects both the user and the merchant, and sets the right expectations before the first charge ever happens.

Pre-Renewal Notifications

As a best practice, merchants should notify users ahead of each billing cycle. A good pattern would be to surface something like:

"Your subscription renews in X days. We'll be charging your [bank name] [account type] ending in [last 4] on [date]. If you'd like to update your payment method, do so before your renewal date."

This gives users a heads-up, reduces disputes, and creates a natural checkpoint to catch stale or incorrect payment info before a charge fails.

Handling Failed Payments

Since the user is not actively present during a renewal transaction, the merchant needs to have a clear recovery strategy in place.

Rejected Payments

Aeropay's risk model evaluates each transaction in real time and, in some cases, will reject a payment outright if it has a high probability of resulting in an ACH return — for example, if the user doesn't have sufficient funds. In these cases, Aeropay returns an error on the transaction attempt directly. The merchant should surface that error to the user with clear next steps, such as prompting them to add funds or update their payment method before the next retry. It is on the merchant to attempt a retry.

Declined Payments

Aeropay may approve the transaction initially, but the payment later comes back as an ACH decline. When this happens, Aeropay emits a transaction_declined webhook and suspends the user. Merchants should listen for this webhook and use it to update the user's status in their system accordingly. While suspended, the user will not be able to transact with Aeropay — so it's important to surface a clear message letting them know their subscription is on hold and why. Aeropay automatically attempts smart retries to recover the payment, and once the user resolves their delinquency with Aeropay directly, they'll be reactivated.

Secondary Payment Method

If the merchant collected a backup payment method during sign-up (and disclosed this to the user upfront), they can attempt the charge against that method instead. This is the smoothest UX from the user's perspective since it's fully automated.

Fallback Messaging

If the charge can't be recovered automatically, surface a clear message to the user:

"We weren't able to process your payment for [subscription name]. Your subscription will end on [date] unless you update your payment method. Please update your bank account or contact support."

In any failed payment scenario, the subscription should not silently expire — the user should always know what happened and have a clear path to resolve it.

Key Reminders for Merchants

The merchant is fully responsible for managing subscription state. Aeropay does not track whether a user is subscribed, handle cancellations, or send renewal notices — all of that lives on the merchant's side. If a user wants to cancel, they contact the merchant, not Aeropay. Aeropay's role is simply to execute the payment when the merchant calls POST /v2/transaction.