Initiate a Preauthorized Transaction from your User

Now that you have linked a bank account from your user, you will be able to initiate a a preauthorized transaction, which temporarily holds transaction details before initiating the movement of funds.

This step will go over how to create a preauthorized transaction, which will be captured at a future date.

Step 4A - Create the Preauthorized Transaction

HTTP request

Sandbox - POST https://api.sandbox-pay.aero.inc/v2/preauthTransaction
Production - POST https://api.aeropay.com/v2/preauthTransaction

Request parameters

Parameter	Required?	Type	Description
amount	Yes	Object	Dictionary with currency and amount in pennies. Only USD supported at this time Amount maximum limit: Default setting for configured in merchant portal or as defined in your Aeropay agreement. Amount minimum limit: $0.01.
merchantId	Yes	String	Your merchantId.
bankAccountId	no	String	BankAccountId of user. Defaults to user's selected bank
referenceId	no	String	This unique uuid value will be associated with the transaction, and can be used to associate Aeropay transactions with your own system. It is recommended to use a UUID value according to the standard methods (ISO/IEC 9834-8)
attributes	no	Object	Dictionary of value and description pairs. Accepted keys are "tip", "invoice", and "submerchant".

Code Example - Request

curl --location --globoff 'https://api.sandbox-pay.aero.inc/v2/preauthTransaction' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer {{userForMerchantScope token}}' \
--header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
--data '{
    "bankAccountId": {{bankAccountTransactionId}},
    "merchantId": {{mainMerchantId}},
    "amount": {
        "currency": "USD",
        "amount": 222
    },
    "description": "DESCRIPTION",
    "attributes": {
        "key": {
            "value": "KEY VALUE",
            "description": "KEY DESCRIPTION"
        }
    },
    "referenceId": "Testing V2"
}'

🔑
Idempotency-Key
Optional UUID value to ensure idempotent transaction.

Code Example - Response

{
    "transaction": {
        "id": "53024f75-f7d1-45b7-8e4d-4449fed355ab",
        "amount": {
            "currency": "USD",
            "amount": 222
        },
        "status": "live",
        "userId": "d5e17cbf-92ad-44e7-b483-19dba7adaaa4",
        "referenceId": "Testing V2",
        "description": "Online Transaction",
        "attributes": {
            "key": {
                "value": "KEY VALUE",
                "description": "KEY DESCRIPTION"
            }
        },
        "createdDate": "2026-01-02T12:00:56+00:00",
        "expiryDate": "2026-01-04T12:00:56+00:00",
        "userName": "Begos Andres",
        "userEmail": "[email protected]",
        "merchantId": 1057,
        "userAccountId": 1717,
        "locationId": 1147
    }
}

🚧
This preauthorized transaction will expire after 3 days, or can be manually canceled by calling DELETE /preauthTransaction with its respective id.
Time to expiration can be configured on a merchant by merchant basis.

HTTP status and error codes

HTTP Status	Error Code	Meaning	Resolution	Message
200	AP110: Missing user info	User is missing required info to transact	Verify user has valid first and last names, email and phone number	"Unable to complete transaction due to incomplete user profile."
200	AP109: User is disabled	The user either has an outstanding declined transaction or they were flagged during Aeropay’s identity screening. Refer to user.userStatus for more info	The user should email [email protected] if they’ve made payments. If they are a new user, they should contact [email protected]	"Sorry, your account is suspended. Please reach out to [email protected] to resolve the issue."
200	AP300: Bank Connection Error	The balance refresh of this user’s account failed. This is usually caused by the user resetting their banking password or security settings within online banking. Balances will also become stale within 6-12 months	This is called a UAR (User-Action Required) error where the user must reconnect their account or contact Aeropay where we will assess if we can override their balance check.	"We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue."
200	AP302: Insufficient Funds	The user’s current balance does not meet the transaction amount. Pending transactions in the user’s account may be attributing to the balance they think they have.	The user must deposit additional funds into their connected account. (This may take 1-2 business days to be reflected)	"Available balance does not meet requirement - contact [email protected] for more information."
200	AP305: User is disabled	Specific to /payoutTransaction: The user either has an outstanding declined transaction. Refer to user.userStatus for more info	The user should email [email protected] if they’ve made payments. If they are a new user, they should contact [email protected]	"Account disabled. Contact [email protected] to resolve the issue."
200	AP307: Transaction Not Approved	Aeropay’s machine learning model did not approve the transaction after assessing its likelihood to decline.	The user may contact the Aeropay Team for a possible override at [email protected]	"Your payment was not approved by our monitoring system. Please try a different amount, connecting a different bank account, or contact [email protected] for more information."
200	AP400: User missing bank account	User has no banks connected and cannot transact	Connect a bank account for user	"No bank account for provided user id."
200	AP401: Invalid bank account id	Bank account id does not belong to user attempting to transact	Provide valid bankAccountId or remove bankAccountId param and transaction will use user's default bank account	"Bank account does not belong to user."
200	AP412: Bank account removed	Bank account has been removed from users account	Provide valid bankAccountId or remove bankAccountId param and transaction will use user's default bank account	"Bank account has already been removed"

Step 4B - Handle Webhooks

If you have an active webhook subscription, you will receive the preauthorized_transaction_created webhook immediately after the resource has been created.