
Aeropay
Supports in this guide: Payouts
Provider website: aeropay.com
What you need to do for start processing transactions (brief summary)
- Choose account type
- Get your credentials (from Aeropay)
- Connect in Dashboard
- 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
-
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_voidedandtransaction_declinedtopics 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. -
Payout statuses: a newly created payout is
pendingat Aeropay and stays in processing until Aeropay marks itprocessed(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_idis 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!