Skip to content

Logo

Aeropay

Supports in this guide: Payouts

Provider website: aeropay.com


What you need to do for start processing transactions (brief summary)

  1. Choose account type
  2. Get your credentials (from Aeropay)
  3. Connect in Dashboard
  4. Send an API request

Choose account type

Aeropay can be connected in different ways (depending on your needs):

  • If you do payouts -> choose Provider account

If you're not sure which one to use, confirm with your Corefy account manager.


Prerequisites: get from Aeropay

Get the following values for your Aeropay project/account:

  • API key -> Corefy field api_key -> example: 35f9ba1c-4d2e-4a7b-9c3f-8e1d2a6b5d59 -> where to find: Aeropay backoffice / issued by Aeropay manager
  • API secret -> Corefy field api_secret -> example: 93381b7e-2f4a-4c1d-8b6e-5a9c0d3eb717 -> where to find: Aeropay backoffice / issued by Aeropay manager
  • Merchant ID -> Corefy field merchant_id -> example: 1234 (numeric) -> where to find: Aeropay backoffice / issued by Aeropay manager

Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open Aeropay in the provider directory and press Connect at Aeropay Provider Overview page in the New connection section. Choose Provider account.

Step 2 - Fill in fields (provider -> Corefy)

  • API key -> api_key
  • API secret -> api_secret
  • Merchant ID -> merchant_id (numeric Aeropay merchant identifier)
  • Webhook signing key -> webhook_signing_key (optional - leave empty: it is generated and filled in automatically when the account is connected, see Additional info)
  • Test mode -> (enable if you are using sandbox credentials)

Success

You have connected Aeropay Provider account!


First request to Corefy API

What it does: creates a payout-invoice.

Actual

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "5f2d9c4e-8a1b-4e7f-9d3c-2b6a1e0f7c84",
      "service": "ach_usd",
      "currency": "USD",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123",
        "metadata": {
          "aeropay_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      },
      "fields": {}
    }
  }
}

Aeropay pays out to an existing Aeropay user - a customer who has already registered with Aeropay and linked a bank account. Bank details are not sent in the request: fields stays empty, and the payout goes to the bank account currently selected in that user's Aeropay profile.

Important

customer.metadata.aeropay_user_id (the recipient's Aeropay user ID, a UUID) is required. Customer metadata is stored per customer.reference_id, so it is enough to send aeropay_user_id once for a customer (on a payout or through a customer update) - later payouts with the same customer.reference_id use the stored value automatically.

Before creating the payout, Corefy checks with Aeropay that the user exists, is Active, and has a selected linked bank account. If any check fails, the payout is declined at this stage and nothing is sent to Aeropay (so it can cascade to another provider if cascading is enabled in your routing).


Extended request (MAX)

Why add extra fields (typical reasons):

  • Provide additional customer details for compliance/reconciliation
  • Positively influence conversion rate
  • Include optional fields required by your specific flow

Options

Options are configured on the Corefy side and affect how Corefy builds provider requests or processes responses.

Currently available options (1):

  • rtp - selects whether payouts are sent as instant (RTP/FedNow) or Same-Day ACH transfers.
rtp

What it does: shown in Dashboard as Send payouts via RTP. When enabled, Aeropay attempts to send the payout instantly via RTP/FedNow and automatically falls back to Same-Day ACH if the recipient's bank does not support instant payments. When disabled, the payout is sent as Same-Day ACH.

When to use: enable it once instant payouts (RTP) are approved for your Aeropay account.

Default: disabled (false)

Allowed values: enabled / disabled

Note

If you are not sure which value to select, please contact our support team!


Refunds

Aeropay does not support refunds.


Additional info

  1. Callbacks are set up automatically. When you connect the Provider account in the Dashboard (and again whenever you update the connection), Corefy registers its webhook URL in your Aeropay account for the transaction_completed, transaction_voided and transaction_declined topics and, if Webhook signing key is empty, generates a signing key and saves it to the connection. No manual setup in the Aeropay backoffice is needed.

  2. Payout statuses: a newly created payout is pending at Aeropay and stays in processing until Aeropay marks it processed (typically about 3 business days), at which point it becomes successful. A voided or declined payout (including an ACH return) is marked as failed.


FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the API key, API secret and Merchant ID for the chosen environment (sandbox vs production) and the Test mode toggle
  • Payout declined as invalid recipient -> customer.metadata.aeropay_user_id is missing or is not a valid UUID; send the customer's Aeropay user ID
  • Payout declined because the user is not active or has no linked bank account -> the customer must complete Aeropay registration and link (and select) a bank account in Aeropay before receiving payouts
  • Payout stays in processing for several days -> expected for ACH: the payout is finalized once Aeropay marks it processed
  • Not sure which account type to use? -> ask your Corefy account manager

Question

Still looking for help connecting your Aeropay account? Please contact our support team!