Step 4 - Create a Preauthorized Transaction
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.
Create a Preauthorized Transaction Workflow
You will need to retrieve the user to check for their linked bank account. Refer to the previous step to learn more.
Step 4A - Create the Preauthorized Transaction
HTTP request
Sandbox - POST https://staging-api.aeropay.com/preauthTransaction
Production - POST https://api.aeropay.com/preauthTransaction
Request parameters
Parameter | Required? | Type | Description |
---|---|---|---|
bankAccountId | No | String | The bankAccountId from the user created in the previous step. You can also retrieve this Id by calling the GET /user endpoint. |
merchantId | Yes | String | Your merchant id. |
merchantLocationId | No | String | Your merchant location id. |
amount | Yes | String | Amount of money. Maximum limit: Default setting for configured in merchant portal or as defined in your Aeropay agreement. Minimum limit: $0.01 |
description | No | String | |
attributes | Yes | Object | See Attributes Object |
uuid | No | String | This unique uuid value will be associated with the transaction, and can be used to associate Aeropay transactions with your own system. Required for X-AP-Version: 2023-06-05. Please note, you must generate the UUID according to the standard methods (ISO/IEC 9834-8) |
Attributes Object
Parameter | Required? | Type | Description |
---|---|---|---|
key | Yes | String | See Key Object |
Key Object
Parameter | Required? | Type | Description |
---|---|---|---|
value | Yes | String | |
description | Yes | String |
Code Example - Request
curl --request POST \
--url https://staging-api.aeropay.com/preauthTransaction \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'authorizationToken: Bearer {{token}}' \
--data '
{
"attributes": {
"tip": {
"selection": {
"tipAmount": "1.00",
"label": "$1.00",
"totalAmount": "12.00"
}
}
},
"bankAccountId": "abc123",
"merchantId": "582",
"merchantLocationId": "4321",
"amount": "11.00",
"description": "Hello",
"uuid": "transaction-UUID-in-standard-v4-format"
}'
Code Example - Response
{
"success": true,
"error": null,
"transaction": {
"id": "19215",
"transactionId": "None",
"merchantId": "582",
"merchantAccountId": "511",
"merchantLocationId": "4321",
"userId": "12977",
"userAccountId": "16838",
"userName": "John Doe",
"userEmail": "[email protected]",
"amount": "1100",
"dollarAmount": "11.00",
"originalAmount": "1100",
"description": "Online Transaction",
"attributes": {
"tip": {
"selection": {
"tipAmount": "1.00",
"label": "$1.00",
"totalAmount": "12.00"
}
}
},
"createdDate": "1694105493",
"expiryDate": "1694364693",
"cancellationDate": null,
"creditPartnerId": null,
"status": "live"
},
"merchantName": "Aeropay"
}
This preauthorized transaction will expire after 3 days, or can be manually cancelled 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.
To create a webhook subscription, visit our API Reference
Updated 3 days ago