Guides

Step 4 - Create a Preauthorized Transaction

Suggest Edits

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

ParameterRequired?TypeDescription
bankAccountId NoStringThe bankAccountId from the user created in the previous step.
You can also retrieve this Id by calling the GET /user endpoint.
merchantIdYesStringYour merchant id.
merchantLocationIdNoStringYour merchant location id.
amountYesStringAmount of money.
Maximum limit: Default setting for configured in merchant portal or as defined in your Aeropay agreement.
Minimum limit: $0.01
descriptionNoString
attributesYesObjectSee Attributes Object
uuidNoStringThis 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

ParameterRequired?TypeDescription
keyYesStringSee Key Object

Key Object

ParameterRequired?TypeDescription
valueYesString
descriptionYesString

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 StatusError CodeMeaningResolutionMessage
200AP110: Missing user infoUser is missing required info to transactVerify user has valid first and last names, email and phone number"Unable to complete transaction due to incomplete user profile."
200AP109: User is disabledThe user either has an outstanding declined transaction or they were flagged during Aeropay’s identity screening. Refer to user.userStatus for more infoThe 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."
200AP300: Bank Connection ErrorThe 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 monthsThis 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."
200AP302: Insufficient FundsThe 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."
200AP305: User is disabledSpecific to /payoutTransaction: The user either has an outstanding declined transaction. Refer to user.userStatus for more infoThe 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."
200AP307: Transaction Not ApprovedAeropay’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."
200AP400: User missing bank accountUser has no banks connected and cannot transactConnect a bank account for user"No bank account for provided user id."
200AP401: Invalid bank account idBank account id does not belong to user attempting to transactProvide valid bankAccountId or remove bankAccountId param and transaction will use user's default bank account"Bank account does not belong to user."
200AP412: Bank account removedBank account has been removed from users accountProvide 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

Refer to this page

Updated 4 months ago

What’s Next