# Aeropay API Documentation
> Documentation for Aeropay API
Append .md to any documentation page URL to get its markdown version.
## Guides
- [Getting Started](https://dev.aero.inc/docs/getting-started.md)
- [Merchant Portal](https://dev.aero.inc/docs/merchant-portal.md)
- [API Quick Start](https://dev.aero.inc/docs/api-quick-start.md)
- [Overview](https://dev.aero.inc/docs/api-overview.md)
- [Token Scopes](https://dev.aero.inc/docs/token-scopes.md): This guide covers Aeropay's token types, what they are, and how each is used properly.
- [User Flows](https://dev.aero.inc/docs/user-flows.md)
- [New & Network Users](https://dev.aero.inc/docs/new-network-users.md)
- [Returning User](https://dev.aero.inc/docs/returning-user.md)
- [Standard Transaction](https://dev.aero.inc/docs/standard-transaction-overview.md)
- [Step 1 - Authentication](https://dev.aero.inc/docs/standard-transaction-step-1-authentication.md)
- [Step 2 - Create a User](https://dev.aero.inc/docs/standard-transaction-step-2-create-a-user.md)
- [Step 3 - Link a bank to the User](https://dev.aero.inc/docs/standard-transaction-step-3-link-a-bank-to-the-user.md)
- [Step 4 - Create a Transaction](https://dev.aero.inc/docs/standard-transaction-step-4-create-a-transaction.md)
- [Preauthorized Transaction](https://dev.aero.inc/docs/preauth-transaction-overview.md)
- [Step 1 - Authentication](https://dev.aero.inc/docs/preauth-transaction-step-1-authorization.md)
- [Step 2 - Create a User](https://dev.aero.inc/docs/preauth-transaction-step-2-create-a-user.md)
- [Step 3 - Link a bank to the User](https://dev.aero.inc/docs/preauth-transaction-step-3-link-a-bank-to-the-user.md)
- [Step 4 - Create a Preauthorized Transaction](https://dev.aero.inc/docs/preauth-transaction-step-4-create-a-payment.md)
- [Step 5 - Update a Preauth Transaction](https://dev.aero.inc/docs/preauth-transaction-step-5-update-a-preauth-transaction.md)
- [Step 6 - Capture a Preauth Transaction](https://dev.aero.inc/docs/preauth-transaction-step-6-capture-the-preauth-transaction.md)
- [Payout Transaction](https://dev.aero.inc/docs/payout-transaction-overview.md)
- [Step 1 - Authentication](https://dev.aero.inc/docs/payout-transaction-step-1-authentication.md)
- [Step 2 - Create a User](https://dev.aero.inc/docs/payout-transaction-step-2-create-a-user.md)
- [Step 3 - Link a bank to the User](https://dev.aero.inc/docs/payout-transaction-step-3-link-a-bank-to-the-user.md)
- [Step 4 - Create a Payout](https://dev.aero.inc/docs/payout-transaction-step-4-create-a-payout.md)
- [Request for Payment (RfP) Transaction](https://dev.aero.inc/docs/request-for-payment-transaction.md)
- [Manage Transactions, Users, or Banks](https://dev.aero.inc/docs/manage-transactions-users-or-banks.md)
- [Reporting & Reconciliation](https://dev.aero.inc/docs/reporting-reconciliation.md)
- [Error Glossary](https://dev.aero.inc/docs/error-handling.md)
- [Testing](https://dev.aero.inc/docs/testing.md): Testing scenarios designed for sandbox testing.
- [Aerosync Integration Guides](https://dev.aero.inc/docs/aerosync-implementation-guides.md)
- [Web NPM SDK (v2.0+)](https://dev.aero.inc/docs/npm-sdk.md): Aerosync SDK for use with network user identifier: aeroPassUserUuid.
- [Mobile WebView](https://dev.aero.inc/docs/mobile-webview.md): Integrating Aerosync Web SDK in Mobile Apps via WebView
- [Release Notes](https://dev.aero.inc/docs/release-notes.md)
- [React Native SDK (v4.0+)](https://dev.aero.inc/docs/react-native-sdk.md): Aerosync SDK for use with network user identifier: aeroPassUserUuid.
- [Release Notes](https://dev.aero.inc/docs/release-notes-1.md)
- [Android](https://dev.aero.inc/docs/android-sdk.md): Aerosync SDK for use with network user identifier: aeropassuuid.
- [iOS SDK](https://dev.aero.inc/docs/ios-sdk.md): Aerosync SDK for use with network user identifier: aeropassuuid.
- [Flutter ](https://dev.aero.inc/docs/flutter-sdk.md): Aerosync SDK for use with network user identifier: aeropassuuid.
- [Capacitor Example](https://dev.aero.inc/docs/capacitor-aeronetwork.md): Aerosync SDK for use with network user identifier: aeropassuuid.
- [CDN](https://dev.aero.inc/docs/cdn-v2.md)
- [Aerosync Test Banks (Aerobank)](https://dev.aero.inc/docs/aerosync-test-banks.md)
- [Aerosync Test Banks (Aerosync Bank)](https://dev.aero.inc/docs/aerosync-sandbox-environment.md)
- [OAuth Connections](https://dev.aero.inc/docs/oauth-connections.md)
- [Aerosync Customizations](https://dev.aero.inc/docs/aerosync-customizations.md)
- [SDK Integration Guide](https://dev.aero.inc/docs/integration-guide.md)
- [SDK Examples](https://dev.aero.inc/docs/examples.md)
- [Launch Checklist](https://dev.aero.inc/docs/launch-checklist.md)
- [API Integrations](https://dev.aero.inc/docs/launch-checklist-api-integrations.md)
- [SDK & Payment Links](https://dev.aero.inc/docs/launch-checklist-sdk-payment-links.md)
- [Webhooks](https://dev.aero.inc/docs/webhooks-1.md)
- [Webhook Security](https://dev.aero.inc/docs/webhook-security.md): Webhook security is optional
- [Python Example](https://dev.aero.inc/docs/python-example.md)
- [Node.js Example](https://dev.aero.inc/docs/nodejs-example.md)
- [Go Example](https://dev.aero.inc/docs/go-example.md)
- [UX Guidelines](https://dev.aero.inc/docs/ux-guidelines.md)
- [Assets](https://dev.aero.inc/docs/aeropay-assets.md)
- [SFTP Connections](https://dev.aero.inc/docs/sftp-connections.md)
- [Transaction Statuses & Return Codes](https://dev.aero.inc/docs/transaction-status.md)
- [User Reputation (Trusted User Program)](https://dev.aero.inc/docs/user-reputation-program.md)
- [Bank Account Migration](https://dev.aero.inc/docs/bank-account-migration.md)
- [Step 1 - Create Migration File](https://dev.aero.inc/docs/step-1-create-migration-file.md)
- [Step 2 - Retrieve List of Jobs](https://dev.aero.inc/docs/step-2-retrieve-list-of-jobs.md)
- [Step 3 - Retrieve Job Items](https://dev.aero.inc/docs/step-3-retrieve-job-items.md)
- [Subscriptions](https://dev.aero.inc/docs/subscriptions.md)
- [MCP](https://dev.aero.inc/docs/mcp.md)
## API Reference
- [token](https://dev.aero.inc/reference/post_v2-token.md): Authenticates API integrators for every Aeropay endpoint. Returns a transient JSON web token (JWT) to authorize access to the AeroPay API. Tokens last for 30 minutes and are required in the authorization header formatted as: `Bearer {{token}}`. **Scopes** The `scope` parameter determines who is acting on the system and which endpoints are available: * **`merchant`**: Used for merchant calls. To obtain a merchant scoped token, the `id` parameter is required. * **`userForMerchant`**: Used to act on behalf of users created by your merchant. To obtain a userForMerchant scoped token, an additional `userId` is required along with all merchant credentials (`api_key`, `api_secret`, `id`). Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP002` | 401 | Invalid API key or secret key | | `AP006` | 401 | Client not authorized for this scope | | `AP101` | 401 | No authenticated user | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [user](https://dev.aero.inc/reference/post_v2-user.md): Create a user associated with the authorized merchant. When creating a user, a `userId` is returned. This `userId` is required for referencing the user within the AeroPay system. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP006` | 401 | Client not authorized for this scope | | `AP101` | 401 | No authenticated user | | `AP102` | 200 | Unable to create user | | `AP105` | 200 | Phone number missing area code | | `AP106` | 200 | Improperly formatted phone number | | `AP115` | 200 | Unsupported phone type | | `AP118` | 200 | Name cannot contain numbers or special characters | | `AP119` | 200 | Unsupported country code - US numbers only | | `AP700` | 400 | Missing or invalid required parameter |
- [user](https://dev.aero.inc/reference/get_v2-user.md): Fetch a user associated with the merchant. The user fetched is based on the `userId` provided in the `/token` call. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user |
- [confirmUser](https://dev.aero.inc/reference/post_v2-confirmuser.md): Verifies a user account with the MFA code they receive. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP111` | 200 | Invalid verification code | | `AP112` | 200 | Max verification attempts exceeded | | `AP113` | 200 | User does not exist | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [aggregatorCredentials](https://dev.aero.inc/reference/get_v2-aggregatorcredentials.md): Request a new aggregator URL to launch an aggregator widget with a unique token. This will allow users to link their bank account. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP407` | 200 | Bank linking disabled on account | | `AP408` | 200 | Unknown aggregator | | `AP409` | 200 | Invalid redirectURI |
- [linkAccountFromAggregator](https://dev.aero.inc/reference/post_v2-linkaccountfromaggregator.md): Associates a user bank account with their AeroPay account. This call is to be made after a user goes through an aggregator bank connection flow leveraging the URL from `/v2/aggregatorCredentials` endpoint. You will receive the `connectionId` as response attributes from the aggregator widget. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP300` | 200 | Unable to connect to bank | | `AP403` | 200 | Bank not supported | | `AP404` | 200 | Invalid routing number | | `AP408` | 200 | Unknown aggregator | | `AP409` | 200 | Invalid redirectURI | | `AP410` | 200 | Error linking bank account | | `AP411` | 200 | Invalid account type - connect a checking account | | `AP414` | 200 | Maximum linked accounts reached | | `AP415` | 200 | Bank account already linked | | `AP700` | 400 | Missing or invalid required parameter |
- [userBankAccount](https://dev.aero.inc/reference/patch_v2-userbankaccount-bankaccountid.md): Selects a user's bank account. This sets the default bank account for transactions. If no bankAccountId is provided in the /transaction call, the selected account will be used. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP400` | 200 | No bank account linked | | `AP401` | 400 | Cannot validate bank account | | `AP412` | 200 | Bank account already removed | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [bankAccounts](https://dev.aero.inc/reference/get_v2-bankaccounts.md): Retrieve a list of bank accounts associated with the authenticated user. Error Glossary (click to expand)
| Code | HTTP Status | Message ||------|-------------|-------------|| `AP101` | 401 | No authenticated user | Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP103` | 200 | Unable to set user reputation level | | `AP109` | 200 | Delinquent activity on account | | `AP110` | 200 | User profile incomplete | | `AP114` | 200 | Account restricted by merchant | | `AP201` | 200 | No merchant found for merchant id | | `AP203` | 200 | Unable to get location for merchant | | `AP205` | 200 | Unable to get rewards and fees for merchant | | `AP206` | 200 | Unable to get merchant account | | `AP300` | 200 | Unable to connect to bank | | `AP302` | 200 | Insufficient funds | | `AP303` | 200 | Transaction missing location | | `AP304` | 200 | Transaction amount exceeds limit | | `AP306` | 200 | Insufficient balance | | `AP307` | 200 | Payment declined - try a lower amount | | `AP308` | 200 | Invalid amount | | `AP314` | 200 | Transaction already exists | | `AP315` | 200 | Payment rejected - threshold or suspended bank | | `AP400` | 200 | No bank account linked | | `AP401` | 400 | Cannot validate bank account | | `AP402` | 200 | No bank account for merchant | | `AP403` | 200 | Bank not supported | | `AP404` | 200 | Invalid routing number | | `AP411` | 200 | Invalid account type - connect a checking account | | `AP412` | 200 | Bank account already removed | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP1400` | 400 | Idempotency key reused with different payload | | `AP1401` | 400 | Request with same idempotency key still processing | | `AP1402` | 400 | Invalid idempotency key structure |
- [transactionRefunds](https://dev.aero.inc/reference/get_v2-transaction-transactionuuid-refunds.md): Retrieve the current refund state for a specific transaction. Returns two arrays: - **`refunds`** — processed or pending reversal transactions. Shape matches a standard transaction object. Always present; empty when no refunds have been processed. - **`queuedRefunds`** — individually tracked refunds that have been requested but not yet processed (e.g. the original transaction has not yet cleared). Each item has `id`, `referenceId`, `amount` (with `amount` and `currency`), and `status` (`queued` or `abandoned`). Always present; empty when nothing is queued. The `id` on a queued refund item is the uuid assigned at the time POST /v2/reverseTransaction was called (either supplied by the client or system-generated). That same uuid becomes the `id` of the resulting reversal transaction once processed. **Multiple reversals:** A transaction can have more than one independent reversal. Each POST /v2/reverseTransaction call produces its own record. Both `refunds` and `queuedRefunds` may contain multiple entries. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|---------| | `AP011` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [getTransactionByIdempotencyKey](https://dev.aero.inc/reference/get_v2-transaction-idempotency-idempotencykey.md): Fetches the original transaction response by the idempotency key used during the POST /v2/transaction request. **Security Behavior** To prevent information leakage, this endpoint returns an empty object `{}` in all negative cases — including when the idempotency key does not exist and when the key exists but belongs to a different merchant. Callers cannot distinguish between the two scenarios. **Loss of Reference Behavior** The idempotency key can reference the transaction only until the TTL expires. The current TTL is 1 day. After that, the transaction may exist but cannot be retrieved by the idempotency key.
- [transaction](https://dev.aero.inc/reference/get_v2-transaction-transactionid.md): Fetch a transaction for the specified transaction id. To search for multiple transactions or by other transaction attributes, use `POST /v2/transactionSearch`. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP011` | 401 | Unauthorized for this transaction | | `AP101` | 401 | No authenticated user | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [preauthTransaction](https://dev.aero.inc/reference/post_v2-preauthtransaction.md): Create a preauthorized transaction for the user specified by the authorization token. The response contains a transaction object. The `id` within this transaction object is used to identify this preauthorized transaction. Preauthorized transactions do not have a default expiration, but can be configurable by merchant. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP103` | 200 | Unable to set user reputation level | | `AP109` | 200 | Delinquent activity on account | | `AP110` | 200 | User profile incomplete | | `AP201` | 200 | No merchant found for merchant id | | `AP203` | 200 | Unable to get location for merchant | | `AP205` | 200 | Unable to get rewards and fees for merchant | | `AP300` | 200 | Unable to connect to bank | | `AP302` | 200 | Insufficient funds | | `AP303` | 200 | Transaction missing location | | `AP304` | 200 | Transaction amount exceeds limit | | `AP306` | 200 | Insufficient balance | | `AP307` | 200 | Payment declined - try a lower amount | | `AP308` | 200 | Invalid amount | | `AP310` | 200 | Credit transaction declined | | `AP314` | 200 | Transaction already exists | | `AP315` | 200 | Payment rejected - threshold or suspended bank | | `AP400` | 200 | No bank account linked | | `AP401` | 400 | Cannot validate bank account | | `AP402` | 200 | No bank account for merchant | | `AP403` | 200 | Bank not supported | | `AP411` | 200 | Invalid account type - connect a checking account | | `AP412` | 200 | Bank account already removed | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP1000` | 200 | Invalid API | | `AP1400` | 400 | Idempotency key reused with different payload | | `AP1401` | 400 | Request with same idempotency key still processing | | `AP1402` | 400 | Invalid idempotency key structure |
- [preauthTransaction](https://dev.aero.inc/reference/get_v2-preauthtransaction-preauthtransactionid.md): Retrieve the preauthorized transaction with the id provided by the path parameter ({{preAuthTransactionId}}). Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP313` | 200 | Preauth ineligible for capture | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [preauthTransaction](https://dev.aero.inc/reference/patch_v2-preauthtransaction-preauthtransactionid.md): Update the specified preauthorized transaction. Preauthorized transaction amounts can be increased or decreased. Attributes can also be added for tipping purposes. **Note:** The updated transaction amount may not exceed the original amount that was preauthorized. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP300` | 200 | Unable to connect to bank | | `AP302` | 200 | Insufficient funds | | `AP310` | 200 | Credit transaction declined | | `AP312` | 200 | Preauth already captured | | `AP313` | 200 | Preauth ineligible for capture | | `AP315` | 200 | Payment rejected - threshold or suspended bank | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP1000` | 200 | Invalid API |
- [preauthTransaction](https://dev.aero.inc/reference/delete_v2-preauthtransaction-preauthtransactionid.md): Delete the specified preauthorized transaction. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP312` | 200 | Preauth already captured | | `AP313` | 200 | Preauth ineligible for capture | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [preauthTransactions](https://dev.aero.inc/reference/get_v2-preauthtransactions.md): Fetch array of the preauthorized transactions for the authorized merchant. If the optional `id` query parameter is specified, fetches only that preauthorized transaction. If the optional `level` query parameter is specified, fetches the preauthorized transactions for that level. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP313` | 200 | Preauth ineligible for capture | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [capturePreauthTransaction](https://dev.aero.inc/reference/post_v2-capturepreauthtransaction.md): Execute the preauthorized transaction which is specified by provided 'id'. The AeroPay transaction is returned. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP300` | 200 | Unable to connect to bank | | `AP310` | 200 | Credit transaction declined | | `AP312` | 200 | Preauth already captured | | `AP313` | 200 | Preauth ineligible for capture | | `AP400` | 200 | No bank account linked | | `AP401` | 400 | Cannot validate bank account | | `AP412` | 200 | Bank account already removed | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP1000` | 200 | Invalid API |
- [reverseTransaction](https://dev.aero.inc/reference/post_v2-reversetransaction.md): Void or refund an Aeropay Transaction. If a transaction needs to be reversed (return money to the customer) this method will void the payment, or create a payment to the customer from the merchant. Transactions that are within the same business day can be voided on the spot, where no money is moved in either direction. If that window has closed and the transaction has begun to process, a transaction in the reverse direction will be created. An amount can be included to handle partial refunds if there was a change in the amount, otherwise the full amount will be refunded. Refunds will take 2-3 business days to process as usual. **Safe Retry for Refunds (Idempotency-Key):** When a merchant retries a refund request (e.g. after a timeout or network error), Aeropay returns the same outcome as the first attempt instead of creating a second refund. Send an idempotency key with the request (e.g. a UUID in the `Idempotency-Key` header). The first request with that key is processed and its response is stored; later requests with the same key receive the stored response and do not trigger a new refund. The same key cannot be used with a different request body; if it is, the API rejects the request so one key always maps to one logical refund. Idempotency is optional; if no idempotency key is sent, the API does not apply this behavior and does not guarantee protection against duplicate refunds on retries. **NOTE:** The `id` used is a `Aeropay Transaction.id` and is only for AeroTransactions. Use `/v2/preauthTransaction` DELETE to cancel a preauthorized transaction. **Multiple Independent Reversals:** Each call to this endpoint produces its own separate reversal record with its own uuid. Previously, concurrent partial refunds were silently merged into a single reversal record; that behavior has changed. A transaction can have multiple independent reversals, as long as their amounts do not collectively exceed the original transaction amount. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP011` | 401 | Unauthorized for this transaction | | `AP101` | 401 | No authenticated user | | `AP310` | 200 | Credit transaction declined | | `AP314` | 200 | Reversal uuid already exists — the supplied `uuid` collides with an existing reversal's uuid | | `AP400` | 200 | No bank account linked | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter — also raised when the optional `uuid` field is supplied but is not a valid UUID v4 | | `AP1001` | 200 | Error committing to database | | `AP1200` | 200 | Could not create merchant bill transaction | | `AP1300` | 200 | Total refunded amount across all queued and processed reversals on this transaction fully covers the original amount | | `AP1302` | 200 | Refund amount exceeds original transaction amount | | `AP1303` | 200 | Refund amount must be positive | | `AP1304` | 200 | Transaction type cannot be refunded | | `AP1305` | 200 | RTP transaction cannot be voided - schedule a refund |
- [payoutTransaction](https://dev.aero.inc/reference/post_v2-payouttransaction.md): Create a transaction that pays an amount from the logged in merchant to the specified user. The details of the transaction are returned upon success. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP101` | 401 | No authenticated user | | `AP103` | 200 | Unable to set user reputation level | | `AP109` | 200 | Delinquent activity on account | | `AP110` | 200 | User profile incomplete | | `AP201` | 200 | No merchant found for merchant id | | `AP203` | 200 | Unable to get location for merchant | | `AP205` | 200 | Unable to get rewards and fees for merchant | | `AP206` | 200 | Unable to get merchant account | | `AP300` | 200 | Unable to connect to bank | | `AP302` | 200 | Insufficient funds | | `AP303` | 200 | Transaction missing location | | `AP304` | 200 | Transaction amount exceeds limit | | `AP305` | 200 | Account blocked - delinquent activity | | `AP308` | 200 | Invalid amount | | `AP314` | 200 | Transaction already exists | | `AP315` | 200 | Payment rejected - threshold or suspended bank | | `AP400` | 200 | No bank account linked | | `AP401` | 400 | Cannot validate bank account | | `AP402` | 200 | No bank account for merchant | | `AP403` | 200 | Bank not supported | | `AP404` | 200 | Invalid routing number | | `AP411` | 200 | Invalid account type - connect a checking account | | `AP412` | 200 | Bank account already removed | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP900` | 200 | External API error | | `AP1400` | 400 | Idempotency key reused with different payload | | `AP1401` | 400 | Request with same idempotency key still processing | | `AP1402` | 400 | Invalid idempotency key structure |
- [transactionSearch](https://dev.aero.inc/reference/post_v2-transactionsearch.md): Search and retrieve a paginated list of transactions for the authorized merchant. Supports advanced filtering (e.g., `paymentType`), sorting (`sortBy`, `orderBy`), and pagination (`page`, `perPage`). The response includes a `paging` object with total counts and a `transactions` array containing the results. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP006` | 401 | Client not authorized for this scope | | `AP101` | 401 | No authenticated user | | `AP605` | 200 | Merchant is required | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter | | `AP1000` | 200 | Invalid API |
- [paymentLink](https://dev.aero.inc/reference/post_v2-paymentlink.md): Send a payment link via SMS or email for the given merchant. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP201` | 200 | No merchant found for merchant id | | `AP203` | 200 | Unable to get location for merchant | | `AP204` | 200 | Location does not belong to merchant | | `AP208` | 200 | Failed to fetch location for uuid | | `AP700` | 400 | Missing or invalid required parameter | | `AP701` | 400 | Improperly formatted parameter |
- [createWebhookSigningKey](https://dev.aero.inc/reference/post_v2-createwebhooksigningkey.md): Create a webhook. Specify a topic and a url. Use this call to either create or update a webhook for a topic. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP1000` | 200 | Invalid API | | `AP1107` | 400 | Merchant is required |
- [webhook](https://dev.aero.inc/reference/post_v2-webhook.md): Create a webhook. Specify a topic and a url. Use this call to either create or update a webhook for a topic. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP1000` | 200 | Invalid API | | `AP1102` | 400 | Topic required to create webhook | | `AP1103` | 400 | URL is invalid or missing | | `AP1104` | 400 | Unrecognized topic | | `AP1105` | 200 | Error creating webhook | | `AP1107` | 400 | Merchant is required |
- [webhook](https://dev.aero.inc/reference/get_v2-webhook.md): Fetch webhook for the specified topic. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP1000` | 200 | Invalid API | | `AP1101` | 200 | Error fetching webhook | | `AP1107` | 400 | Merchant is required |
- [webhook](https://dev.aero.inc/reference/delete_v2-webhook.md): Delete the webhook(s) matching the specified topic and/or webhook ID. Returns the details of every webhook that was successfully deleted. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|-------------| | `AP009` | 401 | Unauthorized | | `AP101` | 401 | No authenticated user | | `AP1000` | 200 | Invalid API | | `AP1100` | 400 | Topic or webhook ID required to delete webhook | | `AP1101` | 200 | Error fetching webhook | | `AP1106` | 200 | Error deleting webhook | | `AP1107` | 400 | Merchant is required |
- [Transactions CSV](https://dev.aero.inc/reference/get_v2-reports-transactions-csv.md): Fetch and return the transactions for a specified merchant, delivered in a CSV file.
- [Transactions Totals](https://dev.aero.inc/reference/get_v2-reports-transactions-totals.md): Fetch and return a summary of the transaction totals for the specified merchant.
- [Merchant Batch Balance](https://dev.aero.inc/reference/get_v2-reports-transactions-batches.md): Fetch the ACH batches and their associated transactions for the specified time range.
- [merchantReputation](https://dev.aero.inc/reference/get_v2-merchantreputation.md): Retrieve the current reputation status for a specific user associated with the merchant. The response includes the `userReputation` score and the `dateModified` timestamp indicating when the status was last updated.
- [merchantReputation](https://dev.aero.inc/reference/post_v2-merchantreputation.md): Create or update the reputation status for one or more users associated with the merchant. Accepts a list of `userReputations`, allowing for bulk updates by providing a `reputation` score for each `userId`.
- [tipConfiguration](https://dev.aero.inc/reference/get_v2-merchant-tipconfiguration.md): Retrieve the Aeropay tipping configuration for the authenticated merchant. Use this endpoint to render tip options in your own checkout flow instead of maintaining a duplicate copy of the merchant's tip settings. Tip settings are managed in the Aeropay Merchant Portal, and this response always reflects their current state. The merchant is derived from the merchant-scoped token, so this endpoint takes no request parameters. Tipping is configured at the merchant level and cannot be configured per merchant location. ### Check `enabled` first The response has two shapes. When tipping is off, `tipConfiguration` contains `enabled` and nothing else: ```json {"tipConfiguration": {"enabled": false}} ``` `options`, `defaultValue`, and `customTipEnabled` are omitted entirely rather than returned empty, because they describe how to render a tip prompt that will never be shown. A merchant that configured tip options and later turned tipping off returns this same response - leftover options are not surfaced. Read `enabled` before reading any other field. A merchant with no tipping configuration at all returns this same shape with `200`. It is not an error condition. ### Reading `options` When `enabled` is `true`, each entry in `options` is discriminated by `type`, and the shape of `value` changes accordingly: - `type: "percentage"` — `value` is the tip percentage as a number, for example `15` or `12.5`. It is a percentage of the transaction amount, not a decimal multiplier. - `type: "flat"` — `value` is a money object, `{"amount": , "currency": "USD"}`, matching the amount convention used elsewhere in the v2 API. An `amount` of `500` is $5.00. A custom (user-entered) tip is reported by the `customTipEnabled` boolean and is never returned as an entry in `options`. A merchant whose only configured tip is a custom one returns `enabled: true` with an empty `options` array and `customTipEnabled: true`. This endpoint is read-only and does not apply a tip. Once a tip is selected, send it as a tip attribute on `POST /v2/transaction` or `PATCH /v2/preauthTransaction/{preauthTransactionId}`. Error Glossary (click to expand)
| Code | HTTP Status | Message | |------|-------------|---------| | `AP101` | 401 | A merchant-scoped token is required |