openapi: 3.0.0
info:
  title: Aeropay v2 API
  version: 1.0.0
  description: '# Introduction


    Welcome to the Aeropay developer API documentation. Aeropay facilitates smart bank transfers that are quick and secure.
    Please use the following documentation to learn more about how you can integrate Aeropay into your platform.


    **NOTE:** For quickest integration - please review our javascript SDK.


    # Onboarding


    Before you begin, you must first request a test account in the Aeropay sandbox environment. Please email [support@aeropay.com](https://mailto:support@aeropay.com)
    - once approved, we’ll send you sandbox credentials.


    # Environments


    Aeropay has two environments; staging and production. The staging environment is used for integration and testing. Ready
    to go live? Access to the production environment will be granted for processing live transactions.


    **NOTE:** Be sure to use the appropriate API key for the environment you wish to use. Tokens have a 30 minute TTL.


    **API URLs**


    (staging) [https://staging-api.aeropay.com](https://staging-api.aeropay.com)


    (production) [https://api.aeropay.com](https://api.aeropay.com)


    # Users & Merchants


    There are two primary parties utilizing the Aeropay platform - users and merchants. Users initiate transactions with payment
    to the merchant while merchants typically receive payments from users.


    Please see the User Management section to learn more about how to create and manage users on the AeroPay platform.'
servers:
- url: https://api.sandbox-pay.aero.inc
  variables: {}
paths:
  /v2/token:
    post:
      summary: token
      description: '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`).


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Authentication
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: Merchant Scope
                type: object
                properties:
                  apiKey:
                    type: string
                  apiSecret:
                    type: string
                  scope:
                    type: string
                    description: Type of token requested
                    enum:
                    - merchant
                  id:
                    type: integer
                    description: Merchant Id. Required for merchant or userForMerchant token.
                required:
                - apiKey
                - apiSecret
                - scope
                - id
              - title: User For Merchant Scope
                type: object
                properties:
                  apiKey:
                    type: string
                  apiSecret:
                    type: string
                  scope:
                    type: string
                    description: Type of token requested
                    enum:
                    - userForMerchant
                  id:
                    type: integer
                    description: Merchant Id. Required for merchant or userForMerchant token.
                  userId:
                    type: string
                    description: UUID id of user. Required for userForMerchant token.
                required:
                - apiKey
                - apiSecret
                - scope
                - id
                - userId
            examples:
              MerchantToken:
                summary: Merchant Scope Request
                value:
                  apiKey: '{{api_key}}'
                  apiSecret: '{{api_secret}}'
                  scope: merchant
                  id: '{{mainMerchantId}}'
              UserForMerchantToken:
                summary: User For Merchant Request
                value:
                  apiKey: '{{api_key}}'
                  apiSecret: '{{api_secret}}'
                  scope: userForMerchant
                  id: '{{mainMerchantId}}'
                  userId: '{{userId}}'
      responses:
        '200':
          description: Success - Token generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  TTL:
                    type: integer
                  token:
                    type: string
              example:
                TTL: 1800
                token: eyJ0eXAiOiJKV1Qi...
        '400':
          description: Bad Request - Validation Errors. See examples for common vs. scope-specific errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Common_InvalidScope:
                  summary: 'Common: Invalid scope'
                  value:
                    error:
                      code: AP700
                      message: Invalid scope
                Common_MissingScope:
                  summary: 'Common: Missing scope'
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''scope'''
                Common_MissingSecret:
                  summary: 'Common: Missing apiSecret'
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''apiSecret'''
                Common_MissingKey:
                  summary: 'Common: Missing apiKey'
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''apiKey'''
                Common_InvalidId:
                  summary: 'Common: Invalid id format'
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''id: invalid UUID format'']'
                UserScope_MissingUserId:
                  summary: 'UserForMerchant ONLY: Missing userId'
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''userId'''
                UserScope_InvalidUsername:
                  summary: 'UserForMerchant ONLY: Invalid username format'
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''userId: invalid username format'']'
        '401':
          description: Unauthorized - Authentication Failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: AP002
                  message: invalid API key or secret key
  /v2/user:
    parameters: []
    post:
      summary: user
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - User Management
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        description: Payload to create a new consumer user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userRequest'
            example:
              firstName: John
              lastName: Doe
              email: test@test.com
              phoneNumber: '13125826818'
        required: true
      responses:
        '200':
          description: Success or Validation Failure (Unified 200)
          headers:
            Date:
              schema:
                type: string
              example: Tue, 24 Jun 2025 20:24:21 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/userObject'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_User_Response_MFA:
                  summary: 'Success: User Response with MFA'
                  value:
                    user:
                      id: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      firstName: JohnNew
                      lastName: DoeNew
                      type: consumer
                      email: test-1754932665@aeropay.com
                      phoneNumber: '+11754932665'
                      createdDate: '2025-02-27T12:59:32+00:00'
                    mfaType: null
                Error_MissingEmail:
                  summary: 'Error: Missing Email'
                  value:
                    error:
                      help: Contact support@aeropay.com for help.
                      code: AP700
                      message: 'Missing required Parameter: ''email'''
                Error_MissingPhone:
                  summary: 'Error: Missing Phone Number'
                  value:
                    error:
                      help: Contact support@aeropay.com for help.
                      code: AP700
                      message: 'Missing required Parameter: ''phoneNumber'''
                Error_InvalidPhoneFormat:
                  summary: 'Error: Invalid Phone Format'
                  value:
                    error:
                      help: Contact support@aeropay.com for help.
                      code: AP115
                      message: We're sorry, but the type of phone you entered is not supported or invalid.
                Error_InvalidNameFormat:
                  summary: 'Error: Invalid Name Format'
                  value:
                    error:
                      help: Contact support@aeropay.com for help.
                      code: AP118
                      message: User cannot be created with numbers or special characters
                Error_ImproperlyFormatted:
                  summary: 'Error: Improperly Formatted Parameter'
                  value:
                    error:
                      help: Contact support@aeropay.com for help.
                      code: AP700
                      message: 'Improperly formatted parameter: [''firstName'']'
        '401':
          description: Unauthorized - Invalid or missing Merchant Token
          content:
            application/json:
              example:
                error:
                  code: AP002
                  message: invalid API key or secret key
    get:
      summary: user
      description: 'Fetch a user associated with the merchant.


        The user fetched is based on the `userId` provided in the `/token` call.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|-------------|

        | `AP101` | 401 | No authenticated user |


        </details>'
      tags:
      - User Management
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            Date:
              schema:
                type: string
              example: Tue, 29 Jul 2025 11:07:36 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/userGetResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_UserDetails:
                  summary: 'Success: Get User Details'
                  value:
                    user:
                      id: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      firstName: JohnNew
                      lastName: DoeNew
                      type: consumer
                      email: test-1754932665@aeropay.com
                      phoneNumber: '+11754932665'
                      createdDate: '2025-02-27T12:59:32+00:00'
                      userStatus: Active
        '401':
          description: Unauthorized - Invalid or missing User Token
          content:
            application/json:
              example:
                error:
                  code: AP002
                  message: invalid API key or secret key
  /v2/confirmUser:
    parameters: []
    post:
      summary: confirmUser
      description: 'Verifies a user account with the MFA code they receive.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - User Management
      parameters:
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: confirmUserObject
              type: object
              required:
              - userId
              - code
              - merchantId
              properties:
                userId:
                  type: string
                  description: Id of the user to be confirmed
                code:
                  type: string
                  description: Verification code
                merchantId:
                  type: integer
                  description: Merchant identifier
            example:
              userId: '14831'
              code: '223324'
              merchantId: '1234'
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Tue, 29 Jul 2025 18:21:59 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success - User Confirmed
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/confirmUserObject'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2:
                  summary: Success V2 - User Confirmed
                  value:
                    user:
                      id: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      firstName: JohnNew
                      lastName: DoeNew
                      type: consumer
                      email: test-1754932665@aeropay.com
                      phoneNumber: '+11754932665'
                      createdDate: '2025-02-27T12:59:32+00:00'
                      userStatus: Active
                Error_UserNotExist:
                  summary: Fail - User does not exist
                  value:
                    error:
                      help: contact support@aeropay.com for help
                      code: AP113
                      message: User does not exist
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Error_ImproperUserId:
                  summary: Fail - Improper userId
                  value:
                    error:
                      help: contact support@aeropay.com for help
                      code: AP701
                      message: 'Improperly formatted parameter: [''userId'']'
  /v2/aggregatorCredentials:
    parameters: []
    get:
      summary: aggregatorCredentials
      description: 'Request a new aggregator URL to launch an aggregator widget with a unique token.


        This will allow users to link their bank account.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|-------------|

        | `AP101` | 401 | No authenticated user |

        | `AP407` | 200 | Bank linking disabled on account |

        | `AP408` | 200 | Unknown aggregator |

        | `AP409` | 200 | Invalid redirectURI |


        </details>'
      tags:
      - Bank Connection
      parameters:
      - name: aggregator
        in: query
        required: true
        description: The aggregator you are using to launch a bank linking widget. Only accepted value is aerosync
        example: aerosync
        schema:
          type: string
          enum:
          - aerosync
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Tue, 29 Jul 2025 18:05:13 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/aggregatorCredentialsResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_CorrectToken:
                  summary: Success - Correct Token
                  value:
                    fastlinkURL: https://sandbox.aerosync.com/
                    token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
                    username: 16d96afbeaf0........
                Error_InvalidAggregator:
                  summary: Fail - Invalid Aggregator
                  value:
                    error:
                      code: AP408
                      message: Unknown Aggregator aerosyncj
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                Error_InvalidURI:
                  summary: Fail - Invalid URI format
                  value:
                    code: INVALID_FORMAT
                    message: The redirectURI is not a valid URL structure.
                Error_MissingAggregator:
                  summary: Fail - Missing aggregator
                  value:
                    code: MISSING_PARAMETER
                    message: The aggregator parameter is required.
  /v2/linkAccountFromAggregator:
    parameters: []
    post:
      summary: linkAccountFromAggregator
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Bank Connection
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: linkAccountFromAggregatorRequest
              description: Body of linkAccountFromAggregator call
              type: object
              required:
              - connectionId
              - aggregator
              properties:
                connectionId:
                  type: string
                  description: ConnectionId returned from Aerosync SDK
                aggregator:
                  type: string
                  description: aerosync
                  enum:
                  - aerosync
            example:
              connectionId: '{{connectionId}}'
              aggregator: aerosync
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 12:19:17 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Connection Failure
          content:
            application/json:
              schema:
                oneOf:
                - title: Post aggregatorCredentials Response
                  type: object
                  properties:
                    userBankInfo:
                      type: object
                      properties:
                        bankAccountId:
                          type: integer
                        bankName:
                          type: string
                        accountLast4:
                          type: string
                        name:
                          type: string
                        externalBankAccountId:
                          type: string
                        isSelected:
                          type: boolean
                        accountType:
                          type: string
                        status:
                          type: string
                        createdDate:
                          type: string
                        accountHolderInfo:
                          type: array
                          items:
                            type: object
                        canFetchBalance:
                          type: boolean
                        balance:
                          type: integer
                - title: Failure Response
                  type: object
                  properties:
                    success:
                      type: boolean
                    code:
                      type: string
                    error:
                      type: string
              examples:
                Success:
                  summary: Success
                  value:
                    userBankInfo:
                      bankAccountId: 0
                      bankName: Aerosync Bank (oAuth)
                      accountLast4: '1329'
                      name: Aerosync Checking
                      externalBankAccountId: None
                      isSelected: true
                      accountType: checking
                      status: verified
                      createdDate: '2025-12-11T21:50:22+00:00'
                      accountHolderInfo:
                      - name:
                          fullName: Dwight Schrute
                      canFetchBalance: true
                      balance: 312425
                Fail_IncorrectBody:
                  summary: Fail - Incorrect body
                  value:
                    success: false
                    code: AP300
                    error: We are having issues connecting to your bank. Try reconnecting your bank or reach out to support@aeropay.com
                      to resolve the issue.
  /v2/userBankAccount/{bankAccountId}:
    parameters:
    - name: bankAccountId
      in: path
      required: true
      description: The unique identifier of the bank account to update.
      example: '{{bankAccountId}}'
      schema:
        type: string
    patch:
      summary: userBankAccount
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Bank Connection
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Thu, 07 Aug 2025 14:09:05 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success - Bank Account Updated
          content:
            application/json:
              schema:
                oneOf:
                - title: Patch use response
                  type: object
                  properties:
                    bankAccount:
                      type: object
                      properties:
                        bankAccountId:
                          type: integer
                        bankName:
                          type: string
                        accountLast4:
                          type: string
                        name:
                          type: string
                        isSelected:
                          type: boolean
                        accountType:
                          type: string
                        status:
                          type: string
                        createdDate:
                          type: string
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Activated:
                  summary: Success - activated bank account
                  value:
                    bankAccount:
                      bankAccountId: 0
                      bankName: Aerosync Bank (MFA)
                      accountLast4: '0000'
                      name: Aerosync Checking
                      isSelected: true
                      accountType: checking
                      status: verified
                      createdDate: '2025-12-01T18:52:37+00:00'
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Fail_InvalidAccount:
                  summary: Fail - invalid bank account
                  value:
                    error:
                      code: AP401
                      message: We cannot validate the account you're attempting to connect. Please connect a valid account.
  /v2/bankAccounts:
    get:
      summary: bankAccounts
      description: 'Retrieve a list of bank accounts associated with the authenticated user.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|-------------|

        | `AP101` | 401 | No authenticated user |


        </details>'
      tags:
      - Bank Connection
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            Date:
              schema:
                type: string
              example: Tue, 02 Dec 2025 20:26:27 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                type: object
                properties:
                  bankAccounts:
                    type: array
                    items:
                      type: object
                      properties:
                        bankAccountId:
                          type: integer
                        bankName:
                          type: string
                        accountLast4:
                          type: string
                        name:
                          type: string
                        isSelected:
                          type: boolean
                        accountType:
                          type: string
                        status:
                          type: string
                        createdDate:
                          type: string
                        connectionId:
                          type: string
                          format: uuid
                          description: Optional connection identifier for this bank account. Present only when the Bank Aggregator
                            is AeroSync.
              examples:
                Success:
                  summary: Success - Multiple Accounts
                  value:
                    bankAccounts:
                    - bankAccountId: 1139036
                      bankName: Aerosync Bank (MFA)
                      accountLast4: '3535'
                      name: Aerosync Checking
                      isSelected: true
                      accountType: checking
                      status: verified
                      createdDate: '2025-12-01T18:52:37+00:00'
                      connectionId: bd9d48bd-8b51-4e6e-9f4b-5f5e8f4b0a10
                    - bankAccountId: 1139682
                      bankName: Aerosync Bank (oAuth)
                      accountLast4: '1329'
                      name: Aerosync Checking
                      isSelected: false
                      accountType: checking
                      status: verified
                      createdDate: '2025-12-11T21:50:22+00:00'
                      connectionId: 2e6f7a9b-0df6-4d6c-9b4e-3c9f1c4c7e21
                Success_One:
                  summary: Success - One Account
                  value:
                    bankAccounts:
                    - bankAccountId: 957022
                      bankName: undefined
                      accountLast4: '5432'
                      name: Test EA Account
                      isSelected: true
                      accountType: checking
                      status: None
                      createdDate: '2025-08-13T16:47:00+00:00'
                Success_Empty:
                  summary: Success - No Accounts
                  value:
                    bankAccounts: []
        '401':
          description: Unauthorized - Invalid or missing Token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              example:
                error:
                  code: AP002
                  message: invalid API key or secret key
  /v2/transaction:
    parameters: []
    post:
      summary: transaction
      description: 'Create an Aeropay Transaction Object where funds will move from a user to a merchant.


        The `userForMerchant` token specifies the paying user. The merchant being paid is specified by the `merchantId` in
        the request body. The user''s default bank account will be selected if no `bankAccountId` is specified.


        **Attributes** are AeroPay formatted data that you may wish to include with your transaction. For example, an invoice
        number or the tracking of a tip amount.


        **NOTE:** Tip amounts will be added to the ''amount'' value.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional UUID value to ensure idempotent transaction.
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
          format: uuid
      requestBody:
        description: Body of transaction call
        content:
          application/json:
            schema:
              title: transactionRequest
              type: object
              required:
              - merchantId
              - amount
              properties:
                bankAccountId:
                  type: integer
                  description: default bank account for the user will be used if not specified
                merchantId:
                  type: integer
                  description: MerchantId
                amount:
                  type: object
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                referenceId:
                  type: string
                  description: Merchant reference id of transaction
                attributes:
                  type: object
                  description: Dictionary with attributes. Tip and invoice are standard formats. Custom attributes must follow
                    value/description dictionary formatting.
                  properties:
                    CUSTOM ATTRIBUTE:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of custom attribute
                        description:
                          type: string
                          description: Description of custom attribute
                    invoice:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of invoice
                          example: Value
                        description:
                          type: string
                          description: Description of invoice
                          example: Description
                    tip:
                      type: object
                      properties:
                        tipAmount:
                          type: string
                          description: Required. Amount of tip, in format XX.XX
                        label:
                          type: string
                          description: Required. String representation of tip, including $
                        totalAmount:
                          type: string
                          description: Required. Amount + tip, in format XX.XX. This can be used for reconciliation and to
                            guarantee accurate amount value
                      example:
                        tipAmount: '1.00'
                        label: $1.00
                        totalAmount: '2.00'
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 13:07:17 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_With_Reference:
                  summary: Success - with referenceId
                  value:
                    transaction:
                      id: f79c19d4-11fd-408e-940f-c341667563b9
                      amount:
                        amount: 400
                        currency: USD
                      status: pending
                      paymentType: payment
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      referenceId: merchant-ref-id
                      attributes:
                        ATTRIBUTE NAME:
                          value: ATTRIBUTE VALUE
                          description: ATTRIBUTE DESCRIPTION
                        tip:
                          selection:
                            tipAmount: 1
                            label: $0.01
                            totalAmount: '4.00'
                      isRtp: false
                      merchantId: 582
                      title: Online Transaction
                      locationId: 541
                      userAccountId: 1139036
                Success_Minimal:
                  summary: Success - no referenceId or tip
                  value:
                    transaction:
                      id: f79c19d4-11fd-408e-940f-c341667563b9
                      amount:
                        amount: 400
                        currency: USD
                      status: pending
                      paymentType: payment
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      isRtp: false
                      merchantId: 582
                      title: Online Transaction
                      locationId: 541
                      userAccountId: 1139036
                Success_ValidTip_NoReferenceID:
                  summary: Success - valid tip
                  value:
                    transaction:
                      id: f79c19d4-11fd-408e-940f-c341667563b9
                      amount:
                        amount: 400
                        currency: USD
                      status: pending
                      paymentType: payment
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      attributes:
                        ATTRIBUTE NAME:
                          value: ATTRIBUTE VALUE
                          description: ATTRIBUTE DESCRIPTION
                        tip:
                          selection:
                            tipAmount: 1
                            label: $0.01
                            totalAmount: '4.00'
                      isRtp: false
                      merchantId: 582
                      title: Online Transaction
                      locationId: 541
                      userAccountId: 1139036
                Error_InvalidTipCalculation:
                  summary: Fail - Invalid total tip amount
                  value:
                    error:
                      code: ApError
                      message: 'Invalid total amount calculation: 13.34 not 1.03'
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Error_InvalidAmountFormat:
                  summary: Fail - Invalid amount format
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''amount: money amount must be a dictionary'']'
                Error_InvalidReference:
                  summary: Fail - invalid referenceId (>64)
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''referenceId: exceeded maximum length of 64'']'
                Error_MissingCurrency:
                  summary: Fail - Missing amount/currency
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Currency is required
  /v2/transaction/{transactionUUID}/refunds:
    parameters:
    - name: transactionUUID
      in: path
      required: true
      description: Transaction UUID (id returned from POST /v2/transaction)
      schema:
        type: string
        format: uuid
    get:
      summary: transactionRefunds
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|---------|

        | `AP011` | 401 | Unauthorized |

        | `AP101` | 401 | No authenticated user |

        | `AP700` | 400 | Missing or invalid required parameter |

        | `AP701` | 400 | Improperly formatted parameter |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: false
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Mon, 22 Jan 2026 10:30:00 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success - Transaction refunds retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactionRefundsResponse'
              examples:
                hasRefunds:
                  summary: Transaction has processed/pending refunds
                  value:
                    refunds:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      amount:
                        amount: 5000
                        currency: USD
                      status: processed
                      paymentType: reversal
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      title: Refund for Online Transaction
                      referenceId: 0123456789
                      attributes: []
                      createdDate: '2026-01-22T10:30:00+00:00'
                      modifiedDate: '2026-01-22T10:30:00+00:00'
                      apFee: '0.00'
                      isRtp: false
                      merchantId: 582
                      locationId: 541
                      userAccountId: 1139036
                    - id: b2c3c3d4-e5f6-7890-abcd-ef1234567890
                      amount:
                        amount: 1000
                        currency: USD
                      status: pending
                      paymentType: reversal
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      title: Refund for Online Transaction
                      referenceId: 0123456789
                      attributes: []
                      createdDate: '2026-01-24T10:30:00+00:00'
                      modifiedDate: '2026-01-24T10:30:00+00:00'
                      apFee: '0.00'
                      isRtp: false
                      merchantId: 582
                      locationId: 541
                      userAccountId: 1139036
                    queuedRefunds: []
                hasQueuedRefunds:
                  summary: Transaction has queued refunds pending processing
                  value:
                    refunds: []
                    queuedRefunds:
                    - id: a3f1c2d4-e5b6-7890-abcd-ef1234567890
                      referenceId: b4e2d3f5-f6c7-8901-bcde-fa2345678901
                      amount:
                        amount: 1500
                        currency: USD
                      status: queued
                    - id: c5d3e4f6-a7b8-9012-cdef-ab3456789012
                      referenceId: null
                      amount:
                        amount: 500
                        currency: USD
                      status: queued
                noRefunds:
                  summary: Transaction has no refunds
                  value:
                    refunds: []
                    queuedRefunds: []
  /v2/transaction/idempotency/{idempotencyKey}:
    parameters:
    - name: idempotencyKey
      in: path
      required: true
      description: Idempotency key UUID sent as the Idempotency-Key header on the original POST /v2/transaction request
      schema:
        type: string
        format: uuid
    get:
      summary: getTransactionByIdempotencyKey
      description: '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.'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: false
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: false
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Tue, 24 Jun 2025 20:24:21 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Returns the transaction response originally stored for this idempotency key, or an empty object if
            no record is found or the key belongs to a different merchant.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transactionGetResponse'
                - $ref: '#/components/schemas/emptyResponse'
              examples:
                found:
                  summary: Idempotency key found — returns original transaction response
                  value:
                    transaction:
                      id: f79c19d4-11fd-408e-940f-c341667563b9
                      amount:
                        amount: 400
                        currency: USD
                      status: pending
                      paymentType: payment+
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      title: Online Transaction
                      referenceId: 0123456789
                      attributes:
                      - value: '1'
                        name: tip
                        description: flat
                      - value: ATTRIBUTE VALUE
                        name: ATTRIBUTE NAME
                        description: ATTRIBUTE DESCRIPTION
                      createdDate: '2026-01-21T02:14:45+00:00'
                      modifiedDate: '2026-01-21T02:14:45+00:00'
                      apFee: '0.03'
                      isRtp: false
                      merchantId: 582
                      locationId: 541
                      userAccountId: 1139036
                notFound:
                  summary: Idempotency key not found or belongs to a different merchant
                  value: {}
        '400':
          description: Missing or invalid idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200failure'
              example:
                error:
                  help: contact support@aeropay.com for help
                  code: AP700
                  message: 'Missing required Parameter: ''idempotencyKey'''
  /v2/transaction/{transactionId}:
    parameters:
    - name: transactionId
      in: path
      required: true
      description: Transaction Id of transaction. In UUID format.
      example: 47e1eab8-5b71-42e7-a0fd-bf30f73af6fb
      schema:
        type: string
    get:
      summary: transaction
      description: 'Fetch a transaction for the specified transaction id.


        To search for multiple transactions or by other transaction attributes, use `POST /v2/transactionSearch`.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Thu, 07 Aug 2025 14:22:24 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Transaction Not Found
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transactionGetResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2_Reference:
                  summary: Success - V2 referenceId
                  value:
                    transaction:
                      id: f79c19d4-11fd-408e-940f-c341667563b9
                      amount:
                        amount: 400
                        currency: USD
                      status: pending
                      paymentType: payment
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      referenceId: merchant-ref-id
                      attributes:
                        ATTRIBUTE NAME:
                          value: ATTRIBUTE VALUE
                          description: ATTRIBUTE DESCRIPTION
                        tip:
                          selection:
                            tipAmount: 1
                            label: $0.01
                            totalAmount: '4.00'
                      isRtp: false
                      createdDate: '2026-01-02T11:45:32+00:00'
                      modifiedDate: '2026-01-02T11:45:32+00:00'
                      apFee: '0.03'
                      merchantId: 582
                      title: Online Transaction
                      locationId: 541
                      userAccountId: 1139036
                Success_V2_NoReference:
                  summary: Success - V2 no referenceId
                  value:
                    transaction:
                      id: 5c10f370-387a-4aa0-8f94-56fecc4b0d84
                      amount:
                        amount: 3
                        currency: USD
                      status: pending
                      paymentType: payment
                      userId: '2181'
                      title: Online Transaction
                      attributes:
                      - value: ATTRIBUTE VALUE
                        name: ATTRIBUTE NAME
                        description: ATTRIBUTE DESCRIPTION
                      createdDate: '2025-12-24T01:52:42+00:00'
                      modifiedDate: '2025-12-24T01:52:42+00:00'
                      apFee: '0.00'
                      isRtp: false
                      merchantId: 1057
                      locationId: 1147
                      userAccountId: 4542
                Error_NotFound:
                  summary: Fail - Invalid transaction UUID
                  value:
                    error:
                      code: ApError
                      message: Transaction 47e1eab8-5b71-42e7-a0fd-bf30f73af6fa not found
  /v2/preauthTransaction:
    parameters: []
    post:
      summary: preauthTransaction
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A userForMerchant scoped token.
        example: Bearer {{userForMerchantScopedToken}}
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional UUID value to ensure idempotent transaction.
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
          format: uuid
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: preauthtransactionRequest
              description: Body of preauthtransaction call
              type: object
              required:
              - bankAccountId
              - merchantId
              - amount
              properties:
                bankAccountId:
                  type: integer
                  description: bankAccountId of selected bank
                merchantId:
                  type: integer
                  description: MerchantId
                amount:
                  type: object
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                attributes:
                  type: object
                  description: Dictionary with attributes. Tip and invoice are standard formats. Custom attributes must follow
                    value/description dictionary formatting.
                  properties:
                    CUSTOM ATTRIBUTE:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of custom attribute
                        description:
                          type: string
                          description: Description of custom attribute
                    invoice:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of invoice
                          example: Value
                        description:
                          type: string
                          description: Description of invoice
                          example: Description
                    tip:
                      type: object
                      properties:
                        tipAmount:
                          type: string
                          description: Required. Amount of tip, in format XX.XX
                        label:
                          type: string
                          description: Required. String representation of tip, including $
                        totalAmount:
                          type: string
                          description: Required. Amount + tip, in format XX.XX. This can be used for reconciliation and to
                            guarantee accurate amount value
                      example:
                        tipAmount: '1.00'
                        label: $1.00
                        totalAmount: '2.00'
                referenceId:
                  type: string
                  description: Merchant reference id of transaction
              example:
                bankAccountId: '0'
                merchantId: '1748'
                amount:
                  amount: 1234
                  currency: USD
                referenceId: 123-123-1234
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 16:28:20 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/preauthTransactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2_NoReference:
                  summary: Success - V2 no referenceId
                  value:
                    transaction:
                      id: bec5a7b7-edd8-4580-aff5-b1ee52e73686
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-02T11:59:44+00:00'
                      expiryDate: '2026-01-04T11:59:44+00:00'
                      userName: Begos Andres
                      userEmail: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Success_V2_ValidReference:
                  summary: Success - V2 valid referenceId
                  value:
                    transaction:
                      id: 53024f75-f7d1-45b7-8e4d-4449fed355ab
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      referenceId: check-new-ref-id
                      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: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Error_RefTooLong:
                  summary: Fail - V2 invalid referenceId (>64)
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''referenceId: exceeded maximum length of 64'']'
                Error_InvalidAmount:
                  summary: Fail - Invalid amount format
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''amount: money amount must be a dictionary'']'
  /v2/preauthTransaction/{preauthTransactionId}:
    parameters:
    - name: preauthTransactionId
      description: Id of preauthorized transaction to query by
      in: path
      required: true
      example: 4da64b86-eb2c-44e7-803b-fe0446505fd9
      schema:
        type: string
    get:
      summary: preauthTransaction
      description: 'Retrieve the preauthorized transaction with the id provided by the path parameter ({{preAuthTransactionId}}).


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 16:33:02 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/preauthTransactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2_NoReference:
                  summary: Success - V2 no referenceId
                  value:
                    transaction:
                      id: bec5a7b7-edd8-4580-aff5-b1ee52e73686
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-02T11:59:44+00:00'
                      expiryDate: '2026-01-04T11:59:44+00:00'
                      userName: Begos Andres
                      userEmail: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Success_V2_Reference:
                  summary: Success - V2 referenceId
                  value:
                    transaction:
                      id: 53024f75-f7d1-45b7-8e4d-4449fed355ab
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      referenceId: check-new-ref-id
                      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: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Error_Ineligible:
                  summary: Fail - V2 invalid preauth uuid
                  value:
                    error:
                      code: AP313
                      message: Preauth ineligible for capture
                Error_InvalidPreauthUuid:
                  summary: Fail - V2 invalid format preauth uuid
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''id: invalid UUID format'']'
    patch:
      summary: preauthTransaction
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              title: preathtransactionPatchRequest
              description: Body of preauthtransaction patch call
              type: object
              properties:
                amount:
                  type: object
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                attributes:
                  type: object
                  description: Dictionary with attributes. Tip and invoice are standard formats. Custom attributes must follow
                    value/description dictionary formatting.
                  properties:
                    CUSTOM ATTRIBUTE:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of custom attribute
                        description:
                          type: string
                          description: Description of custom attribute
                    invoice:
                      type: object
                      properties:
                        value:
                          type: string
                          description: Value identifier of invoice
                          example: Value
                        description:
                          type: string
                          description: Description of invoice
                          example: Description
                    tip:
                      type: object
                      properties:
                        tipAmount:
                          type: string
                          description: Required. Amount of tip, in format XX.XX
                        label:
                          type: string
                          description: Required. String representation of tip, including $
                        totalAmount:
                          type: string
                          description: Required. Amount + tip, in format XX.XX. This can be used for reconciliation and to
                            guarantee accurate amount value
                      example:
                        tipAmount: '1.00'
                        label: $1.00
                        totalAmount: '2.00'
            example:
              amount:
                amount: 101
                currency: USD
              attributes:
                invoice:
                  value: '12345'
                  description: BUSINESS NAME
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Thu, 07 Aug 2025 14:27:56 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/preauthTransactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Update:
                  summary: Success - Update Amount
                  value:
                    transaction:
                      id: 53024f75-f7d1-45b7-8e4d-4449fed355ab
                      amount:
                        currency: USD
                        amount: 101
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      description: Online Transaction
                      attributes:
                        invoice:
                          value: '12345'
                          description: BUSINESS NAME
                      createdDate: '2026-01-02T12:00:56+00:00'
                      expiryDate: '2026-01-04T12:00:56+00:00'
                      userName: Begos Andres
                      userEmail: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Error_AlreadyCaptured:
                  summary: Fail - preauth already captured
                  value:
                    error:
                      code: AP312
                      message: 'Preauth has already been captured by Transaction #0b6c0d66-2752-4800-bbf4-aa1118b8a646.'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Error_InvalidFormat:
                  summary: Fail - Invalid ID Format
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''id: invalid UUID format'']'
                Error_MissingId:
                  summary: Fail - missing transaction id
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''transactionId'''
    delete:
      summary: preauthTransaction
      description: 'Delete the specified preauthorized transaction.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Thu, 07 Aug 2025 15:05:36 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  preauthTransactionGetResponse:
                    title: Get preauthTransaction Response
                    type: object
                    properties:
                      transaction:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                            description: Unique identifier for the transaction (UUID).
                          amount:
                            type: object
                            properties:
                              currency:
                                type: string
                                example: USD
                                description: Three-letter ISO currency code.
                              amount:
                                type: integer
                                example: 101
                                description: Amount in pennies or smallest currency unit.
                          status:
                            type: string
                            enum:
                            - pending
                            - live
                            - canceled
                            - completed
                            description: Current status of the transaction.
                          userId:
                            type: string
                            format: uuid
                            description: Internal identifier of the user.
                          userName:
                            type: string
                            description: Full name of the user.
                          userEmail:
                            type: string
                            format: email
                            description: Email address of the user associated with the transaction.
                          createdDate:
                            type: string
                            format: date-time
                            description: The date and time when the transaction was created.
                          expiryDate:
                            type: string
                            format: date-time
                            description: The date and time when the transaction expires.
                          merchantId:
                            type: integer
                            description: Identifier of the merchant.
                          userAccountId:
                            type: integer
                            description: Identifier of the user's bank account.
                          locationId:
                            type: integer
                            description: Identifier of the specific business location.
                    example:
                      transaction:
                        id: 53024f75-f7d1-45b7-8e4d-4449fed355ab
                        amount:
                          currency: USD
                          amount: 101
                        status: canceled
                        userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                        userName: Begos Andres
                        userEmail: begona.andresm@aeropay.com
                        createdDate: '2026-01-02T12:00:56+00:00'
                        expiryDate: '2026-01-04T12:00:56+00:00'
                        merchantId: 1057
                        userAccountId: 1717
                        locationId: 1147
              examples:
                Success_Cancel:
                  summary: Success - preauth canceled
                  value:
                    transaction:
                      id: 53024f75-f7d1-45b7-8e4d-4449fed355ab
                      amount:
                        currency: USD
                        amount: 101
                      status: canceled
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      userName: Begos Andres
                      userEmail: begona.andresm@aeropay.com
                      createdDate: '2026-01-02T12:00:56+00:00'
                      expiryDate: '2026-01-04T12:00:56+00:00'
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Error_AlreadyDeleted:
                  summary: Fail - Already deleted preauth transaction
                  value:
                    error:
                      code: AP313
                      message: Preauthorized Transaction with status of canceled is not eligible for capture
                Error_NotExist:
                  summary: Fail - preauth does not exists
                  value:
                    error:
                      code: AP313
                      message: Preauth ineligible for capture
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  code: AP701
                  message: 'Improperly formatted parameter: [''id: invalid UUID format'']'
  /v2/preauthTransactions:
    parameters: []
    get:
      summary: preauthTransactions
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: uuid
        in: query
        required: false
        description: UUID of preauthorized transaction to query by
        example: 7626c8c6-d6df-4c21-bcf4-09569294eaec
        schema:
          type: string
      - name: level
        in: query
        required: false
        description: Status of preauthorized transaction to query by
        example: live
        schema:
          type: string
      - name: dateStart
        in: query
        required: false
        description: Start date to filter preauthorized transactions on (MM-DD-YYYY HH:mm:ss)
        example: 11-12-2025 00:00:00
        schema:
          type: string
      - name: dateEnd
        in: query
        required: false
        description: End date to filter preauthorized transactions on (MM-DD-YYYY HH:mm:ss)
        example: 11-13-2025 00:00:00
        schema:
          type: string
      - name: timezone
        in: query
        required: false
        description: Timezone of dates
        example: ECT
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        example: 1
        schema:
          type: integer
      - name: perPage
        in: query
        required: false
        description: Number of transactions per page
        example: 10
        schema:
          type: integer
      - name: sortBy
        in: query
        required: false
        description: Field to sort by
        example: id
        schema:
          type: string
      - name: orderBy
        in: query
        required: false
        description: Order by
        example: desc
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 16:33:02 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success
          content:
            application/json:
              schema:
                type: object
                title: Get preauthTransaction response
                properties:
                  paging:
                    type: object
                    properties:
                      totalPages:
                        type: integer
                      totalItems:
                        type: integer
                      currentPage:
                        type: integer
                      itemsPerPage:
                        type: integer
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/preauthTransactionResponse'
              examples:
                Success_V2_Params:
                  summary: Success - V2 params
                  value:
                    paging:
                      totalPages: 1
                      totalItems: 1
                      currentPage: 1
                      itemsPerPage: 1
                    transactions:
                    - id: 962af059-bf7b-4fd5-8d1f-83e9deb0a02a
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      referenceId: merchant-ref-id
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-21T02:56:27+00:00'
                      expiryDate: '2026-01-24T02:56:27+00:00'
                      userName: Cristiano Lopes
                      userEmail: cristiano.lopes@ext.blaze.me
                      merchantId: 582
                      userAccountId: 1139036
                      locationId: 541
                Success_NoQueryParams:
                  summary: Success - No Query Parameters
                  value:
                    paging:
                      totalPages: 1
                      totalItems: 2
                      currentPage: 1
                      itemsPerPage: 50
                    transactions:
                    - id: 962af059-bf7b-4fd5-8d1f-83e9de77acb
                      amount:
                        currency: USD
                        amount: 333
                      status: live
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      referenceId: merchant-ref-id
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-21T02:56:27+00:00'
                      expiryDate: '2026-01-24T02:56:27+00:00'
                      userName: Cristiano Lopes
                      userEmail: cristiano.lopes@ext.blaze.me
                      merchantId: 582
                      userAccountId: 1139036
                      locationId: 541
                    - id: 962af059-bf7b-4fd5-8d1f-83e9deb0a02a
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
                      referenceId: merchant-ref-id
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-21T02:56:27+00:00'
                      expiryDate: '2026-01-24T02:56:27+00:00'
                      userName: Cristiano Lopes
                      userEmail: cristiano.lopes@ext.blaze.me
                      merchantId: 582
                      userAccountId: 1139036
                      locationId: 541
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  code: AP008
                  message: Invalid token.
  /v2/capturePreauthTransaction:
    parameters: []
    post:
      summary: capturePreauthTransaction
      description: 'Execute the preauthorized transaction which is specified by provided ''id''.


        The AeroPay transaction is returned.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        description: Body of preauthtransaction capture call
        content:
          application/json:
            schema:
              title: preathtransactionCaptureRequest
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: preauthtransactionId of transaction to capture. In UUID format.
            example:
              id: 7626c8c6-d6df-4c21-bcf4-09569294eaec
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Wed, 30 Jul 2025 16:50:39 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/capturePreauthTransactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Valid_Id:
                  summary: Success - valid preauth id
                  value:
                    transaction:
                      id: bec5a7b7-edd8-4580-aff5-b1ee52e73686
                      amount:
                        currency: USD
                        amount: 222
                      status: live
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      description: Online Transaction
                      attributes:
                        key:
                          value: KEY VALUE
                          description: KEY DESCRIPTION
                      createdDate: '2026-01-02T11:59:44+00:00'
                      expiryDate: '2026-01-04T11:59:44+00:00'
                      userName: Begos Andres
                      userEmail: begona.andresm@aeropay.com
                      merchantId: 1057
                      userAccountId: 1717
                      locationId: 1147
                Error_AlreadyCancelled:
                  summary: Fail - Transaction already cancelled
                  value:
                    error:
                      code: AP313
                      message: Preauthorized Transaction with status of canceled is not eligible for capture
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Error_Invalid_Format:
                  summary: Fail - invalid id format
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''id'']'
                      help: Contact support@aeropay.com for help.
  /v2/reverseTransaction:
    parameters: []
    post:
      summary: reverseTransaction
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional idempotency key (e.g. a UUID) to ensure that reverseTransaction is idempotent.
        schema:
          type: string
          format: uuid
      requestBody:
        description: Payload to reverse (void or refund) a transaction.
        content:
          application/json:
            schema:
              title: reverseTransactionRequest
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: id of transaction to refund or void. In UUID format.
                amount:
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  type: object
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                uuid:
                  type: string
                  format: uuid
                  description: Optional client-supplied UUID v4 identifier for the resulting reversal. If omitted, the system
                    generates one.
                referenceId:
                  type: string
                  description: Optional merchant-provided reference for correlating this reversal with external records.
            example:
              id: 9b5781ff-5674-4ce0-9a38-597903bbee2d
              amount:
                currency: USD
                amount: 1111
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Fri, 01 Aug 2025 23:04:11 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  title: POST reverseTransaction Response
                  properties:
                    refundTransaction:
                      type: object
                      properties:
                        id:
                          type: string
                        amount:
                          type: object
                        status:
                          type: string
                        paymentType:
                          type: string
                        userId:
                          type: string
                        title:
                          type: string
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
                        apFee:
                          type: string
                        isRtp:
                          type: boolean
                        merchantId:
                          type: integer
                        locationId:
                          type: integer
                        userAccountId:
                          type: integer
                    message:
                      type: string
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_TransactionVoided:
                  summary: Success - Original transaction has been voided
                  value:
                    refundTransaction:
                      id: f73d1fb8-f668-47a2-84b6-2ccc17ec4353
                      amount:
                        amount: 400
                        currency: USD
                      status: void
                      paymentType: payment+
                      userId: dcecf824-e81f-49a1-a2ea-ca6fa5b2fb30
                      title: Online Transaction
                      attributes:
                      - value: '1'
                        name: tip
                        description: flat
                      - value: ATTRIBUTE VALUE
                        name: ATTRIBUTE NAME
                        description: ATTRIBUTE DESCRIPTION
                      - value: 0123456789
                        name: referenceId
                        description: External Reference Id
                      createdDate: '2026-03-16T15:33:56+00:00'
                      modifiedDate: '2026-03-16T15:35:46+00:00'
                      apFee: '0.33'
                      isRtp: false
                      merchantId: 1522
                      locationId: 2887
                      userAccountId: 1338559
                    message: Transaction has been voided
                Success_QueuedForAmount:
                  summary: Success - Refund for specified amount has been queued
                  value:
                    refundTransaction:
                      userId: dcecf824-e81f-49a1-a2ea-ca6fa5b2fb30
                      merchantId: 1522
                      userAccountId: 1338559
                      amount:
                        currency: USD
                        amount: 300
                    message: Transaction queued for refund. Refund will process after transaction clears
                Success_RefundCreatedForAmount:
                  summary: Success - Refund transaction created with specified refund amount
                  value:
                    refundTransaction:
                      id: d7311d89-9c2f-46b0-a4d9-a77f9ea904ce
                      amount:
                        currency: USD
                        amount: 300
                      status: pending
                      paymentType: reversal
                      userId: dcecf824-e81f-49a1-a2ea-ca6fa5b2fb30
                      title: '2744390'
                      createdDate: '2026-03-16T15:38:10+00:00'
                      modifiedDate: '2026-03-16T15:38:10+00:00'
                      apFee: '0.25'
                      isRtp: false
                      merchantId: 1522
                      locationId: 2887
                      userAccountId: 1338559
                    message: Refund transaction d7311d89-9c2f-46b0-a4d9-a77f9ea904ce created for transaction 9b5781ff-5674-4ce0-9a38-597903bbee2d
                Error_AmountExceeded:
                  summary: Fail - Amount greater than original
                  value:
                    error:
                      code: AP1302
                      message: Refund amount must be equal to or less than the original transaction amount
                Error_UUIDCollision:
                  summary: Fail - Supplied uuid collides with an existing reversal's uuid (AP314)
                  value:
                    error:
                      code: AP314
                      message: Transaction with uuid of d7311d89-9c2f-46b0-a4d9-a77f9ea904ce already exists
                Error_CannotReverseVoidTransaction:
                  summary: Fail - Cannot reverse voided transaction
                  value:
                    error:
                      code: AP1306
                      message: Cannot reverse transaction with status of void
                Error_TransactionNotFound:
                  summary: Fail - Transaction not found
                  value:
                    error:
                      code: AP316
                      message: Transaction ea89bec0-0edb-4f86-9a92-66ce29a488f3 not found
        '400':
          description: Bad Request - Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Error_MissingId:
                  summary: Fail - Missing ID
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''id'''
                Error_InvalidUUIDField:
                  summary: Fail - Optional uuid field is not a valid UUID v4
                  value:
                    error:
                      code: AP314
                      message: 'Improperly formatted parameters: uuid'
  /v2/payoutTransaction:
    parameters: []
    post:
      summary: payoutTransaction
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional UUID value to ensure idempotent transaction.
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              title: payoutTransactionRequest
              type: object
              required:
              - userId
              - amount
              - merchantId
              properties:
                userId:
                  type: string
                  description: UserId of Aeropay user to pay to. In UUID format.
                amount:
                  type: object
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                attributes:
                  type: object
                  description: Dictionary with attributes. Tip and invoice are standard formats. Custom attributes must follow
                    value/description dictionary formatting.
                  properties:
                    tip:
                      type: object
                      properties:
                        tipAmount:
                          type: string
                          description: Required. Amount of tip, in format XX.XX
                        label:
                          type: string
                          description: Required. String representation of tip, including $
                        totalAmount:
                          type: string
                          description: Required. Amount + tip, in format XX.XX. This can be used for reconciliation and to
                            guarantee accurate amount value
                merchantId:
                  type: integer
                  description: merchantId
                bankAccountId:
                  type: integer
                  description: bankAccountId of selected bank
                referenceId:
                  type: string
                  description: Merchant reference id of transaction
                rtp:
                  type: boolean
                  description: If RTP is not specified, it will default to an ACH transaction.
            example:
              userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
              bankAccountId: 0
              amount:
                amount: 10
                currency: USD
              attributes:
                ATTRIBUTE NAME:
                  value: ATTRIBUTE VALUE
                  description: ATTRIBUTE DESCRIPTION
                tip:
                  selection:
                    tipAmount: 1
                    label: $0.01
                    totalAmount: '1.10'
              merchantId: 1057
              referenceId: newReferenceID-TestingEA
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Fri, 01 Aug 2025 23:26:04 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success or Business Logic Error (AP411)
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/payoutTransactionResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_With_Reference:
                  summary: Success - V2 with reference id
                  value:
                    transaction:
                      id: a8f0f917-0087-45ca-acdf-1b34ad33f1ea
                      amount:
                        currency: USD
                        amount: 10
                      attributes:
                        ATTRIBUTE NAME:
                          value: ATTRIBUTE VALUE
                          description: ATTRIBUTE DESCRIPTION
                        tip:
                          selection:
                            tipAmount: 1
                            label: $0.01
                            totalAmount: '1.10'
                      status: pending
                      paymentType: payout
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      referenceId: newReferenceID-TestingEA
                      isRtp: false
                      merchantId: 1057
                      title: Online Transaction
                      locationId: 1147
                      userAccountId: 1717
                Success_Without_Reference:
                  summary: Success - V2 without reference id
                  value:
                    transaction:
                      id: aefc50a7-000b-41de-a937-78aeecd50298
                      amount:
                        currency: USD
                        amount: 10
                      attributes:
                        ATTRIBUTE NAME:
                          value: ATTRIBUTE VALUE
                          description: ATTRIBUTE DESCRIPTION
                        tip:
                          selection:
                            tipAmount: 1
                            label: $0.01
                            totalAmount: '1.10'
                      status: pending
                      paymentType: payout
                      userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                      isRtp: false
                      merchantId: 1057
                      title: Online Transaction
                      locationId: 1147
                      userAccountId: 1717
                Error_Invalid_Account_Type:
                  summary: Fail - Invalid Account for processing payments
                  value:
                    error:
                      code: AP411
                      message: Invalid account connected for processing payments. Please connect a checking account.
                Error_Missing_User_ID:
                  summary: Fail - Missing User ID
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''userId'''
                Error_Invalid_Amount:
                  summary: Fail - Invalid Amount
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''amount: money amount must be a dictionary'']'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Error_Cannot_Validate:
                  summary: Fail - Invalid Account
                  value:
                    error:
                      code: AP401
                      message: We cannot validate the account you're attempting to connect. Please connect a valid account.
  /v2/transactionSearch:
    parameters: []
    post:
      summary: transactionSearch
      description: '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.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: authorization
        in: header
        required: true
        description: Merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      requestBody:
        description: Payload to search for transactions using filters like timezone, page, dates, and search types.
        content:
          application/json:
            schema:
              title: transactionSearchRequest
              type: object
              properties:
                timezone:
                  description: Timezone of dates transactions are filtered on
                  type: string
                  example: America/Chicago
                page:
                  type: string
                  example: '1'
                perPage:
                  type: string
                  example: '50'
                sortBy:
                  type: string
                  example: id
                orderBy:
                  type: string
                  example: asc
                startDate:
                  type: string
                  description: 'Format: MM-DD-YYYY HH:mm:ss'
                endDate:
                  type: string
                  description: 'Format: MM-DD-YYYY HH:mm:ss'
                searchType:
                  type: string
                  description: Type of transaction attribute searched for (transactionId, userId, etc...)
                  enum:
                  - transactionId
                  - uuid
                  - userId
                  - name
                  - phone
                  - email
                  - locationId
                  - merchantId
                  - default
                filters:
                  type: object
                  properties:
                    paymentType:
                      type: string
                      example: payment
                    referenceId:
                      type: string
                      description: Merchant reference id of transaction
            example:
              timezone: America/Chicago
              page: '1'
              perPage: '50'
              sortBy: id
              orderBy: asc
              filters:
                paymentType: payment
        required: false
      responses:
        '200':
          description: Success - List of matching transactions
          headers:
            Date:
              schema:
                type: string
              example: Wed, 27 Aug 2025 12:56:50 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        amount:
                          type: object
                        status:
                          type: string
                        paymentType:
                          type: string
                        attributes:
                          type: array
                        userId:
                          type: string
                        title:
                          type: string
                        createdDate:
                          type: string
                        modifiedDate:
                          type: string
                        apFee:
                          type: string
                        isRtp:
                          type: boolean
                        merchantId:
                          type: integer
                        locationId:
                          type: integer
                        userAccountId:
                          type: integer
                        customerName:
                          type: string
                        locationName:
                          type: string
                        merchantName:
                          type: string
                  paging:
                    type: object
                    properties:
                      totalPages:
                        type: integer
                      totalItems:
                        type: integer
                      currentPage:
                        type: integer
                      itemsPerPage:
                        type: integer
              examples:
                Success_V2:
                  summary: Success - V2 format response
                  value:
                    paging:
                      totalPages: 1
                      totalItems: 1
                      currentPage: 1
                      itemsPerPage: 50
                    transactions:
                    - id: 019bec33-7f67-7b71-a499-60d75.........
                      amount:
                        amount: 717
                        currency: USD
                      status: processed
                      paymentType: payment
                      userId: us-east-1:359b6261-2067-4b33-aa5f-97a8d92551e4
                      title: AP Test Transaction
                      createdDate: '2017-10-15T00:43:19+00:00'
                      modifiedDate: '2026-01-23T00:43:19+00:00'
                      apFee: '0.00'
                      isRtp: false
                      merchantId: 300
                      locationId: 300
                      userAccountId: 3
                      customerName: Carlos Campbell
                      locationName: Walgreens
                      merchantName: Walgreens
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
              examples:
                Error_Missing_UUID:
                  summary: Fail - V2 Missing required Parameter
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''uuid'''
  /v2/paymentLink:
    parameters: []
    post:
      summary: paymentLink
      description: 'Send a payment link via SMS or email for the given merchant.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Create & Manage Transactions
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - merchantId
              properties:
                merchantId:
                  type: string
                  description: The unique identifier for the merchant.
                phone:
                  type: string
                  description: The user's phone number to send the payment link to. One of phone or email is required; if
                    both are supplied, phone delivery is used.
                email:
                  type: string
                  description: The user's email address to send the payment link to. One of phone or email is required; if
                    both are supplied, phone delivery is used.
                merchantLocationId:
                  oneOf:
                  - type: integer
                  - type: string
                    format: uuid
                  description: The merchant location id or uuid to associate with the payment link. Must belong to the merchant
                    in merchantId. Defaults to the merchant's default location if omitted.
                referenceId:
                  type: string
                  description: Merchant reference id of the payment link. Max length 64.
                amount:
                  type: object
                  description: Dictionary with currency and amount in pennies. Only USD supported at this time
                  properties:
                    amount:
                      type: integer
                      description: Payment amount in pennies
                    currency:
                      type: string
                      description: Currency. Currently only supports USD
                userId:
                  type: string
                  description: The unique identifier for the user the link is for.
                paymentType:
                  type: string
                  description: Type of payment link to generate, e.g. preauth/preauthorized. subscription is not supported.
            example:
              merchantId: '{{mainMerchantId}}'
              phone: '{{userPhoneNumber}}'
              merchantLocationId: 65400d5b-d0aa-4e3a-9c9a-3f9e2f1a1234
              referenceId: merchant-reference-123
              amount:
                amount: 1000
                currency: USD
              userId: '{{userId}}'
        required: true
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
              example: Fri, 02 Jan 2026 15:02:42 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          description: Success - Payment Link Sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  referenceId:
                    type: string
              examples:
                Success:
                  summary: Success
                  value:
                    message: Payment Link send request successful
                Success_WithReferenceId:
                  summary: Success - with referenceId echoed back
                  value:
                    message: Payment Link send request successful
                    referenceId: merchant-reference-123
                Fail_LocationIdNotFoundOrOwned:
                  summary: Fail - AP203 - merchantLocationId (int) not found or not owned by merchant
                  value:
                    error:
                      code: AP203
                      message: Unable to get location for merchant id.
                Fail_LocationNotForMerchant:
                  summary: Fail - AP204 - resolved location does not belong to merchantId
                  value:
                    error:
                      code: AP204
                      message: Location 42 not for merchant.
                Fail_NoMerchantFound:
                  summary: Fail - AP201 - no merchant found
                  value:
                    error:
                      code: AP201
                      message: No merchant exists for merchant id.
                Fail_LocationUuidNotFound:
                  summary: Fail - AP208 - merchantLocationId (uuid) not found
                  value:
                    error:
                      code: AP208
                      message: Failed to fetch location for uuid
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Fail_MissingDeliveryDestination:
                  summary: Fail - AP700 - phone and email both missing
                  value:
                    error:
                      code: AP700
                      message: 'Missing required Parameter: ''phone/email'''
                Fail_RejectedField:
                  summary: Fail - AP701 - legacy field not supported (uuid, transaction_uuid, locationId, subscriptionId)
                  value:
                    error:
                      code: AP701
                      message: 'Field(s) not supported: ''uuid'''
                Fail_InvalidFormat:
                  summary: Fail - AP701 - improperly formatted parameter (e.g. referenceId too long, malformed amount, unsupported
                    paymentType)
                  value:
                    error:
                      code: AP701
                      message: 'Improperly formatted parameter: [''referenceId: exceeded maximum length of 64'']'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Fail_Unauthorized:
                  summary: Fail - AP009 - Unauthorized
                  value:
                    error:
                      code: AP009
                      message: Unauthorized
                Fail_NoAuthenticatedUser:
                  summary: Fail - AP101 - No authenticated user
                  value:
                    error:
                      code: AP101
                      message: No Authenticated User
  /v2/createWebhookSigningKey:
    parameters: []
    post:
      summary: createWebhookSigningKey
      description: 'Create a webhook.


        Specify a topic and a url. Use this call to either create or update a webhook for a topic.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|-------------|

        | `AP009` | 401 | Unauthorized |

        | `AP101` | 401 | No authenticated user |

        | `AP1000` | 200 | Invalid API |

        | `AP1107` | 400 | Merchant is required |


        </details>'
      tags:
      - Webhooks
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        description: Payload to create a signing key for webhook validation. Optionally includes the topic and URL for the
          webhook subscription.
        content:
          application/json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                  description: The event topic to subscribe to.
                  example: transaction_completed
                url:
                  type: string
                  description: The destination URL where webhooks will be sent.
                  example: https://webhook.site/9374cfe2-8535-44ec-86d6-20e949fd7919
            example:
              topic: transaction_completed
              url: https://webhook.site/9374cfe2-8535-44ec-86d6-20e949fd7919
        required: false
      responses:
        '200':
          description: Successful Response - Signing Key Created
          headers:
            Date:
              schema:
                type: string
              example: Wed, 27 Aug 2025 13:10:45 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  signingKey:
                    type: string
              examples:
                Success_V2:
                  summary: Success - V2 Response
                  value:
                    message: This is your signingKey used to validate any Webhooks you are subscribed to. Please store this
                      key for future use, as it will not be displayed at any point afterwards.
                    signingKey: cb5e9c4c4d7bd733a16a41da9f34a9ebdc47bee4dc1ab19e....
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Fail_Unauthorized:
                  summary: Fail - Unauthorized
                  value:
                    error:
                      code: AP008
                      message: Invalid token.
  /v2/webhook:
    parameters: []
    post:
      summary: webhook
      description: 'Create a webhook.


        Specify a topic and a url. Use this call to either create or update a webhook for a topic.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Webhooks
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - topic
              - url
              properties:
                topic:
                  type: string
                  description: Webhook topic to subscribe to
                  enum:
                  - transaction_completed
                  - transaction_refunded
                  - transaction_voided
                  - preauthorized_transaction_created
                  - transaction_declined
                  - transaction_resolved
                  - user_active
                  - user_suspended
                  - merchant_reputation_updated
                url:
                  type: string
                  description: Callback URL where webhook payloads will be sent.
            example:
              topic: transaction_completed
              url: https://www.test.com/webhook/test_for_v2
        required: true
      responses:
        '200':
          description: Success - Webhook Subscribed
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/webhookPostResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2:
                  summary: Success - V2 Response
                  value:
                    webhooks:
                      id: 12975
                      payloadVersion: '2.0'
                      topic: transaction_completed
                      url: https://www.test.com/webhook/test_for_v2
        '400':
          description: Bad Request - Validation Errors
          content:
            application/json:
              examples:
                Error_Missing_Url:
                  summary: Fail - Missing url
                  value:
                    error:
                      code: AP1103
                      message: Url is invalid or missing
                Error_Invalid_Topic:
                  summary: Fail - Unrecognized topic
                  value:
                    error:
                      code: AP1104
                      message: Unrecognized topic
    get:
      summary: webhook
      description: 'Fetch webhook for the specified topic.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Webhooks
      parameters:
      - name: topic
        in: query
        required: false
        description: Filter webhooks by topic.
        example: transaction_completed
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: A merchant scoped token.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      responses:
        '200':
          description: Success - List of webhooks
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/webhookGetResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2_List:
                  summary: Success - V2 Response
                  value:
                    webhooks:
                    - id: 2318
                      payloadVersion: '2.0'
                      topic: transaction_completed
                      url: https://example.com/webhook
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  code: AP008
                  message: Invalid token.
    delete:
      summary: webhook
      description: 'Delete the webhook(s) matching the specified topic and/or webhook ID.


        Returns the details of every webhook that was successfully deleted.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | 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 |


        </details>'
      tags:
      - Webhooks
      parameters:
      - name: topic
        in: query
        required: false
        description: The name of the topic being deleted.
        example: transaction_completed
        schema:
          type: string
      - name: webhookId
        in: query
        required: false
        description: ID of the specific webhook to be deleted.
        example: '247'
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      responses:
        '200':
          description: Success - Webhook Deleted
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/webhookDeleteResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Delete:
                  summary: Success - V2 Response
                  value:
                    webhooks:
                    - id: '247'
                      payloadVersion: '2.0'
                      topic: transaction_completed
                      url: https://webhook.site/...
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  code: AP1100
                  message: Topic or webhook Id required to delete webhook
  /v2/reports/transactions/CSV:
    parameters: []
    get:
      summary: Transactions CSV
      description: Fetch and return the transactions for a specified merchant, delivered in a CSV file.
      tags:
      - Reports
      parameters:
      - name: merchantId
        in: query
        required: false
        description: Unique identifier for the merchant.
        example: '{{mainMerchantId}}'
        schema:
          type: string
      - name: timezone
        in: query
        required: false
        description: Timezone for the report data.
        example: America/Chicago
        schema:
          type: string
      - name: gmtOffset
        in: query
        required: false
        description: GMT Offset for the report data.
        example: -5
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number for pagination.
        example: '1'
        schema:
          type: integer
      - name: size
        in: query
        required: false
        description: Number of records per page.
        example: '100'
        schema:
          type: integer
      - name: refunds
        in: query
        required: false
        description: Include refunded transactions in the report.
        example: 'true'
        schema:
          type: boolean
      - name: voids
        in: query
        required: false
        description: Include voided transactions in the report.
        example: 'true'
        schema:
          type: boolean
      - name: version
        in: query
        required: false
        description: Report version.
        example: '1.0'
        schema:
          type: string
      - name: email
        in: query
        required: false
        description: Email address to receive the CSV file.
        example: test.test@gmail.com
        schema:
          type: string
      - name: dateBegin
        in: query
        required: false
        description: Start date for the report filter (MM-DD-YYYY).
        example: 6-25-2020
        schema:
          type: string
      - name: dateEnd
        in: query
        required: false
        description: End date for the report filter (MM-DD-YYYY).
        example: 12-14-2019
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: Merchant scoped token (V2).
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        example: application/json
        schema:
          type: string
      responses:
        '200':
          description: Success - CSV Request Queued
          headers:
            Date:
              schema:
                type: string
              example: Fri, 02 Jan 2026 15:10:45 GMT
            Content-Type:
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                title: Transaction Total CSV Response
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    description: CSV creation process started successfully.
              examples:
                Success_V2:
                  summary: Success Call - V2
                  value:
                    success: true
                    message: CSV creation request successful
  /v2/reports/transactions/totals:
    parameters: []
    get:
      summary: Transactions Totals
      description: Fetch and return a summary of the transaction totals for the specified merchant.
      tags:
      - Reports
      parameters:
      - name: merchantId
        in: query
        required: false
        description: Unique identifier for the merchant.
        example: '{{mainMerchantId}}'
        schema:
          type: string
      - name: dateBegin
        in: query
        required: false
        description: Start date for filtering totals (MM-DD-YYYY).
        example: 02-02-2021
        schema:
          type: string
      - name: dateEnd
        in: query
        required: false
        description: End date for filtering totals (MM-DD-YYYY).
        example: 11-23-2026
        schema:
          type: string
      - name: timezone
        in: query
        required: false
        description: Timezone for the date filters.
        example: America/Chicago
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: Merchant scoped token (V2).
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      - name: Accept
        in: header
        required: false
        example: application/json
        schema:
          type: string
      responses:
        '200':
          description: Success - Totals Generated or Business Error
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transactionTotals'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2:
                  summary: Success Call - V2
                  value:
                    chargeTotal: 2,924,567.05
                    tipTotal: 1,735.70
                    feeTotal: 29,559.03
                    rewardsTotal: '617.35'
                    payoutsTotal: 47,315.92
                    refundsTotal: 532,444.82
                    netTotal: 2,314,629.93
                    returns:
                      payoutReturnsTotal: '189.00'
                Success_Zero:
                  summary: Success - Zero transactions
                  value:
                    chargeTotal: '0.00'
                    tipTotal: '0.00'
                    feeTotal: '0'
                    rewardsTotal: '0.00'
                    payoutsTotal: '0.00'
                    refundsTotal: '0.00'
                    netTotal: '0.00'
                    returns:
                      payoutReturnsTotal: '0.00'
                Fail_Internal:
                  summary: Fail - Error generating totals
                  value:
                    error: Error generating totals
  /v2/reports/transactions/batches:
    parameters: []
    get:
      summary: Merchant Batch Balance
      description: Fetch the ACH batches and their associated transactions for the specified time range.
      tags:
      - Reports
      parameters:
      - name: merchantId
        in: query
        required: false
        description: Unique merchant ID to filter batches.
        example: '{{mainMerchantId}}'
        schema:
          type: string
      - name: dateBegin
        in: query
        required: false
        description: Start date for the report filter (MM-DD-YYYY).
        example: 02-02-2021
        schema:
          type: string
      - name: dateEnd
        in: query
        required: false
        description: End date for the report filter (MM-DD-YYYY).
        example: 11-23-2026
        schema:
          type: string
      - name: timezone
        in: query
        required: false
        description: Time zone for date filters.
        example: America/Chicago
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number for paginated results.
        example: 1
        schema:
          type: integer
      - name: size
        in: query
        required: false
        description: Page size.
        example: 100
        schema:
          type: integer
      - name: Accept
        in: header
        required: false
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: Merchant token with Bearer prefix.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          description: Successful response - Batch list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        batchId:
                          type: integer
                        batchDate:
                          type: string
                          format: date-time
                        transactions:
                          type: array
                          items:
                            type: object
                  paging:
                    type: object
                    properties:
                      totalItems:
                        type: integer
                      totalPages:
                        type: integer
                      currentPage:
                        type: integer
                      itemsPerPage:
                        type: integer
              examples:
                Success_V2:
                  summary: Success Call - V2
                  value:
                    data:
                    - batchId: 13374
                      batchDate: '2025-12-11T02:00:49-06:00'
                      transactions:
                      - uuid: 836bbf98-9fa8-11f0-80bc-12d4b68c7db9
                        amount:
                          amount: 3446598
                          currency: USD
                        direction: credit
                      - uuid: 8370be5d-9fa8-11f0-80bc-12d4b68c7db9
                        amount:
                          amount: 9032
                          currency: USD
                        direction: debit
                    - batchId: 13319
                      batchDate: '2025-12-09T02:00:49-06:00'
                      transactions: []
                    paging:
                      totalItems: 452
                      totalPages: 23
                      currentPage: 1
                      itemsPerPage: 2
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  code: AP008
                  message: Invalid token.
  /v2/merchantReputation:
    parameters: []
    get:
      summary: merchantReputation
      description: '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.'
      tags:
      - Merchant Management
      parameters:
      - name: userId
        in: query
        required: false
        description: User ID to query their reputation.
        example: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: Merchant token with Bearer prefix.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          description: Success - Reputation retrieved
          content:
            application/json:
              schema:
                oneOf:
                - title: Get merchantReputation Response
                  type: object
                  properties:
                    merchantId:
                      type: string
                      description: MerchantId
                    dateModified:
                      type: string
                      description: Last date reputation was modified.
                    paging:
                      type: object
                      nullable: true
                      description: Pagination
                    userId:
                      type: string
                      description: User Id. No longer primary user identifier.
                    userReputation:
                      type: integer
                      description: Reputation status, as integer. 0, 1, or 2
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_V2:
                  summary: Success Call - V2
                  value:
                    merchantId: '1057'
                    dateModified: '2025-12-26 16:49:51'
                    paging: null
                    userId: d5e17cbf-92ad-44e7-b483-19dba7adaaa4
                    userReputation: 0
        '400':
          description: Validation error
          content:
            application/json:
              example:
                error:
                  code: AP700
                  message: 'Missing required Parameter: ''user_id'''
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  code: AP101
                  message: No Authenticated User
    post:
      summary: merchantReputation
      description: '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`.'
      tags:
      - Merchant Management
      parameters:
      - name: Content-Type
        in: header
        required: true
        example: application/json
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        description: Merchant token with Bearer prefix.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - merchantId
              - userReputations
              properties:
                merchantId:
                  type: integer
                userReputations:
                  type: array
                  items:
                    type: object
                    properties:
                      userId:
                        type: string
                      reputation:
                        type: integer
            example:
              merchantId: 1057
              userReputations:
              - userId: 42f73292-9a78-433b-9d60-09561536a033
                reputation: 2
        required: true
      responses:
        '200':
          description: Success - Reputation updated
          content:
            application/json:
              schema:
                oneOf:
                - title: Post merchantReputationStatus Response
                  type: object
                  properties:
                    userReputations:
                      type: array
                      items:
                        type: object
                        properties:
                          userId:
                            type: string
                            description: UserId of the user whose reputation was updated.
                          reputation:
                            type: integer
                            description: New reputation of the user
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Update:
                  summary: Success V2 update
                  value:
                    userReputations:
                    - userId: 42f73292-9a78-433b-9d60-09561536a033
                      reputation: 2
        '400':
          description: Reputation validation error
          content:
            application/json:
              example:
                error:
                  code: AP700
                  message: 'Missing required Parameter: ''Invalid userReputations value: reputation value 5 does not exist'''
  /v2/merchant/tipConfiguration:
    get:
      summary: tipConfiguration
      description: '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": <integer cents>, "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}`.


        <details>

        <summary><strong>Error Glossary</strong> (click to expand)</summary>


        | Code | HTTP Status | Message |

        |------|-------------|---------|

        | `AP101` | 401 | A merchant-scoped token is required |


        </details>'
      tags:
      - Merchant Management
      parameters:
      - name: authorization
        in: header
        required: true
        description: Merchant token with Bearer prefix.
        example: Bearer {{merchantScopedToken}}
        schema:
          type: string
      responses:
        '200':
          description: Success - Tip configuration retrieved
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/tipConfigurationResponse'
                - $ref: '#/components/schemas/200failure'
              examples:
                Success_Percentages:
                  summary: Success - percentage options with custom tip
                  value:
                    tipConfiguration:
                      enabled: true
                      options:
                      - type: percentage
                        value: 15
                      - type: percentage
                        value: 20
                      - type: percentage
                        value: 25
                      defaultValue: null
                      customTipEnabled: true
                Success_MixedOptions:
                  summary: Success - flat and percentage options
                  value:
                    tipConfiguration:
                      enabled: true
                      options:
                      - type: flat
                        value:
                          amount: 500
                          currency: USD
                      - type: percentage
                        value: 12.5
                      defaultValue: null
                      customTipEnabled: false
                Success_TippingDisabled:
                  summary: Success - tipping disabled or not configured
                  value:
                    tipConfiguration:
                      enabled: false
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  code: AP101
                  message: A merchant-scoped token is required.
components:
  schemas:
    200failure:
      title: Failure Response
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            help:
              type: string
              description: Support contact information
      example:
        error:
          help: Contact support@aeropay.com for help.
          code: AP700
          message: 'Missing required Parameter: ''email'''
    emptyResponse:
      title: Empty Response
      type: object
      properties: {}
      example: {}
    userRequest:
      title: Post user Request
      required:
      - firstName
      - lastName
      - phoneNumber
      - email
      type: object
      properties:
        firstName:
          type: string
          description: First name of user being created
        lastName:
          type: string
          description: Last name of user being created
        phoneNumber:
          type: string
          description: Phone number of user in international format (+11234567890). Landlines, VOIPs, or prepaid numbers are
            invalid.
        email:
          type: string
          description: Email of user being created
      example:
        firstName: Stephanie
        lastName: Jones
        phoneNumber: '+11234567890'
        email: stephjones@aeropay.com
    confirmUserObject:
      title: Confirm user - MFA Validation
      type: object
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              description: The id of the user, in uuid format
            firstName:
              type: string
              description: The user's first name
            lastName:
              type: string
              description: The user's last name
            type:
              type: string
              description: Type of user. (consumer, business)
            email:
              type: string
              format: email
              description: The user's email
            phoneNumber:
              type: string
              description: The user's phone number
            createdDate:
              type: string
              format: date-time
              description: Date user was created
            userStatus:
              type: string
              format: date-time
              description: Date user was created
      example:
        user:
          id: 2ac82269-9315-4bb6-8a19-f37e20d50238
          firstName: JohnNew
          lastName: DoeNew
          type: consumer
          email: test-1754932665@aeropay.com
          phoneNumber: '+11754932665'
          createdDate: '2025-02-27T12:59:32+00:00'
          userStatus: Active
    userObject:
      title: Post user - New User and Network User Response
      type: object
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              description: The id of the user, in uuid format
            firstName:
              type: string
              description: The user's first name
            lastName:
              type: string
              description: The user's last name
            type:
              type: string
              description: Type of user. (consumer, business)
            email:
              type: string
              format: email
              description: The user's email
            phoneNumber:
              type: string
              description: The user's phone number
            createdDate:
              type: string
              format: date-time
              description: Date user was created
        mfaType:
          type: string
          description: The Multi-Factor Authentication type determined by the merchant's configuration.
          enum:
          - sms
          - email
          example: sms
      example:
        user:
          id: 2ac82269-9315-4bb6-8a19-f37e20d50238
          firstName: JohnNew
          lastName: DoeNew
          type: consumer
          email: test-1754932665@aeropay.com
          phoneNumber: '+11754932665'
          createdDate: '2025-02-27T12:59:32+00:00'
          userStatus: Active
        mfaType: sms
    userGetResponse:
      title: Get user Response
      type: object
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              description: The id of the user, in uuid format
            firstName:
              type: string
              description: The user's first name
            lastName:
              type: string
              description: The user's last name
            type:
              type: string
              description: Type of user. (consumer, business)
            email:
              type: string
              format: email
              description: The user's email
            phoneNumber:
              type: string
              description: The user's phone number
            createdDate:
              type: string
              format: date-time
              description: Date user was created
            userStatus:
              type: string
              description: The user's status
      example:
        user:
          id: 2ac82269-9315-4bb6-8a19-f37e20d50238
          firstName: JohnNew
          lastName: DoeNew
          type: consumer
          email: test-1754932665@aeropay.com
          phoneNumber: '+11754932665'
          createdDate: '2025-02-27T12:59:32+00:00'
          userStatus: Active
    aggregatorCredentialsResponse:
      title: Post aggregatorCredentials Response
      type: object
      properties:
        fastlinkURL:
          type: string
        token:
          type: string
        username:
          type: string
    linkAccountFromAggregatorResponse:
      title: Post linkAccountFromAggregator Response
      type: object
      properties:
        userBankInfo:
          type: object
          properties:
            bankAccountId:
              type: integer
            bankName:
              type: string
            accountLast4:
              type: string
            name:
              type: string
            externalBankAccountId:
              type: string
            isSelected:
              type: boolean
            accountType:
              type: string
            status:
              type: string
            createdDate:
              type: string
            accountHolderInfo:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: object
                    properties:
                      fullName:
                        type: string
            canFetchBalance:
              type: boolean
            balance:
              type: integer
    transactionResponse:
      title: Post transaction Response
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                amount:
                  type: integer
                currency:
                  type: string
            status:
              type: string
            paymentType:
              type: string
            userId:
              type: string
            title:
              type: string
            referenceId:
              type: string
            attributes:
              type: array
              items:
                type: object
            isRtp:
              type: boolean
            merchantId:
              type: integer
            locationId:
              type: integer
            userAccountId:
              type: integer
    transactionGetResponse:
      title: Get transaction Response
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                amount:
                  type: integer
                currency:
                  type: string
            status:
              type: string
            paymentType:
              type: string
            userId:
              type: string
            title:
              type: string
            referenceId:
              type: string
            attributes:
              type: array
              items:
                type: object
            createdDate:
              type: string
              format: date-time
            modifiedDate:
              type: string
              format: date-time
            apFee:
              type: string
            isRtp:
              type: boolean
            merchantId:
              type: integer
            locationId:
              type: integer
            userAccountId:
              type: integer
    transactionRefundsResponse:
      title: Get transaction refunds Response
      type: object
      properties:
        refunds:
          type: array
          description: List of processed or pending refunds for the transaction. Empty array when only queued refunds exist.
          items:
            $ref: '#/components/schemas/transactionGetResponse'
          nullable: false
        queuedRefunds:
          type: array
          description: List of individually tracked refunds that have been requested but not yet processed. Each item carries
            its own id, referenceId, amount, and status. Empty array when no queued refunds exist.
          items:
            $ref: '#/components/schemas/queuedRefundItem'
          nullable: false
      example:
        refunds:
        - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          amount:
            amount: 5000
            currency: USD
          status: processed
          paymentType: reversal
          userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
          title: Refund for Online Transaction
          referenceId: 0123456789
          attributes: []
          createdDate: '2026-01-22T10:30:00+00:00'
          modifiedDate: '2026-01-22T10:30:00+00:00'
          apFee: '0.00'
          isRtp: false
          merchantId: 582
          locationId: 541
          userAccountId: 1139036
        queuedRefunds: []
    refundItem:
      title: Refund item
      allOf:
      - $ref: '#/components/schemas/transactionGetResponse'
      example:
        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        amount:
          amount: 5000
          currency: USD
        status: processed
        paymentType: reversal
        userId: 2ac82269-9315-4bb6-8a19-f37e20d50238
        title: Refund for Online Transaction
        referenceId: 0123456789
        attributes: []
        createdDate: '2026-01-22T10:30:00+00:00'
        modifiedDate: '2026-01-22T10:30:00+00:00'
        apFee: '0.00'
        isRtp: false
        merchantId: 582
        locationId: 541
        userAccountId: 1139036
    queuedRefundItem:
      title: Queued refund item
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID4 assigned to this queued refund at creation. Will become the aeroTransaction.id when the queued
            refund is processed.
        referenceId:
          type: string
          nullable: true
          description: Merchant-provided reference supplied at the time POST /v2/reverseTransaction was called. null if none
            was provided. Stored as a transaction attribute when processed.
        amount:
          type: object
          properties:
            amount:
              type: integer
              description: Queued refund amount in cents
            currency:
              type: string
              description: Currency code (e.g., USD)
        status:
          type: string
          description: Current state of this queued refund entry. 'queued' means it is pending processing. 'abandoned' means
            it was superseded or cancelled before processing.
          enum:
          - queued
          - abandoned
      example:
        id: a3f1c2d4-e5b6-7890-abcd-ef1234567890
        referenceId: b4e2d3f5-f6c7-8901-bcde-fa2345678901
        amount:
          amount: 1500
          currency: USD
        status: queued
    preauthTransactionResponse:
      title: Post preauthTransaction Response
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                currency:
                  type: string
                amount:
                  type: integer
            status:
              type: string
            userId:
              type: string
            description:
              type: string
            attributes:
              type: object
            createdDate:
              type: string
              format: date-time
            expiryDate:
              type: string
              format: date-time
            userName:
              type: string
            userEmail:
              type: string
              format: email
            merchantId:
              type: integer
            userAccountId:
              type: integer
            locationId:
              type: integer
            referenceId:
              type: string
    preauthTransactionGetResponse:
      title: Get preauthTransaction Response
      type: object
      properties:
        paging:
          type: object
          properties:
            totalPages:
              type: integer
            totalItems:
              type: integer
            currentPage:
              type: integer
            itemsPerPage:
              type: integer
        transactions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              transactionId:
                type: string
                nullable: true
              merchantId:
                type: integer
              merchantAccountId:
                type: integer
              merchantLocationId:
                type: integer
              locationId:
                type: integer
              userId:
                type: string
              userAccountId:
                type: integer
              userName:
                type: string
              userEmail:
                type: string
                format: email
              amount:
                type: object
                properties:
                  currency:
                    type: string
                  amount:
                    type: integer
              description:
                type: string
              attributes:
                type: object
              createdDate:
                type: string
                format: date-time
              expiryDate:
                type: string
                format: date-time
              status:
                type: string
              referenceId:
                type: string
    capturePreauthTransactionResponse:
      title: POST capturePreauthTransaction Response
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                currency:
                  type: string
                amount:
                  type: integer
            status:
              type: string
            userId:
              type: string
            description:
              type: string
            attributes:
              type: object
            createdDate:
              type: string
              format: date-time
            expiryDate:
              type: string
              format: date-time
            userName:
              type: string
            userEmail:
              type: string
              format: email
            merchantId:
              type: integer
            userAccountId:
              type: integer
            locationId:
              type: integer
    reverseTransactionResponse:
      title: POST reverseTransaction Response
      type: object
      properties:
        refundTransaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                currency:
                  type: string
                amount:
                  type: integer
            status:
              type: string
            paymentType:
              type: string
            userId:
              type: string
            title:
              type: string
            createdDate:
              type: string
            modifiedDate:
              type: string
            apFee:
              type: string
            isRtp:
              type: boolean
            merchantId:
              type: integer
            locationId:
              type: integer
            userAccountId:
              type: integer
        message:
          type: string
    payoutTransactionResponse:
      title: Post payoutTransaction Response
      type: object
      properties:
        transaction:
          type: object
          properties:
            id:
              type: string
            amount:
              type: object
              properties:
                amount:
                  type: integer
                currency:
                  type: string
            status:
              type: string
            paymentType:
              type: string
            userId:
              type: string
            referenceId:
              type: string
            isRtp:
              type: boolean
            merchantId:
              type: integer
            title:
              type: string
            locationId:
              type: integer
            userAccountId:
              type: integer
    transactionSearchResponse:
      title: POST transactionSearch Response
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              status:
                type: string
              userId:
                type: string
              merchantId:
                type: integer
              locationId:
                type: integer
              title:
                type: string
              userAccountId:
                type: integer
              amount:
                type: object
                properties:
                  amount:
                    type: integer
                  currency:
                    type: string
              apFee:
                type: string
              paymentType:
                type: string
              createdDate:
                type: string
              modifiedDate:
                type: string
              isRtp:
                type: boolean
              customerName:
                type: string
              locationName:
                type: string
              merchantName:
                type: string
        paging:
          type: object
          properties:
            totalPages:
              type: integer
            totalItems:
              type: integer
            currentPage:
              type: integer
            itemsPerPage:
              type: integer
    webhookPostResponse:
      title: Post webhook Response
      type: object
      properties:
        webhooks:
          type: object
          description: Object of webhook subscribed to
          properties:
            id:
              type: integer
              description: Id of webhook subscription.
            topic:
              type: string
            url:
              type: string
              format: uri
            payloadVersion:
              type: string
              description: Payload format version for this subscription (e.g.2.0). Determines the shape of delivered webhook
                payloads.
              example: '2.0'
    webhookGetResponse:
      title: Get webhook Response
      type: object
      properties:
        webhooks:
          type: array
          description: Array of subscribed webhook objects
          items:
            type: object
            properties:
              id:
                type: integer
                description: Id of webhook subscription.
              topic:
                type: string
              url:
                type: string
                format: uri
              payloadVersion:
                type: string
                description: Payload format version for this subscription (e.g.2.0). Determines the shape of delivered webhook
                  payloads.
                example: '2.0'
    webhookDeleteResponse:
      title: Delete webhook Response
      type: object
      properties:
        webhooks:
          type: array
          description: Array of deleted webhook objects
          items:
            type: object
            properties:
              id:
                type: string
                description: Id of webhook subscription.
              topic:
                type: string
              url:
                type: string
                format: uri
              payloadVersion:
                type: string
                description: Payload format version for this subscription (e.g.2.0). Determines the shape of delivered webhook
                  payloads.
                example: '2.0'
    transactionTotals:
      title: transactionTotals Response
      type: object
      properties:
        chargeTotal:
          type: string
          description: Payment total
        tipTotal:
          type: string
          description: Tips total
        feeTotal:
          type: string
          description: Fee total
        rewardsTotal:
          type: string
          description: Rewards total
        payoutsTotal:
          type: string
          description: Payout payment total
        refundsTotal:
          type: string
          description: Refund total
        netTotal:
          type: string
          description: Net total of above fields
        returns:
          type: object
          description: ACH returns object
          properties:
            payoutReturnsTotal:
              type: string
              description: Payout returns total
    merchantReputationStatusPostResponse:
      title: Post merchantReputationStatus Response
      type: object
      properties:
        userReputations:
          type: array
          description: Array of users reputations updated.
          items:
            type: object
            properties:
              userId:
                type: string
                description: UserId of the user whose reputation was updated.
              reputation:
                type: integer
                description: New reputation of the user
    tipConfigurationResponse:
      title: Get tipConfiguration Response
      type: object
      properties:
        tipConfiguration:
          description: The merchant's current tipping configuration. Returned in one of two shapes depending on `enabled`.
          oneOf:
          - title: Tipping enabled
            type: object
            description: Returned when the merchant has tipping switched on.
            required:
            - enabled
            - options
            - defaultValue
            - customTipEnabled
            properties:
              enabled:
                type: boolean
                enum:
                - true
                description: Always `true` in this variant. The remaining fields are present only in this shape.
              options:
                type: array
                description: The tip options configured by the merchant, in configured order. A custom tip is never included
                  here - see `customTipEnabled`. May be empty when the merchant's only configured tip is a custom one.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - percentage
                      - flat
                      description: Determines how `value` is interpreted. `percentage` is a percentage of the transaction
                        amount; `flat` is a fixed currency amount.
                    value:
                      description: The tip value. A number when `type` is `percentage`, a money object when `type` is `flat`.
                      oneOf:
                      - title: Percentage value
                        type: number
                        description: Returned when `type` is `percentage`. The tip percentage of the transaction amount, for
                          example `15` or `12.5` - not a decimal multiplier.
                        example: 15
                      - title: Flat value
                        type: object
                        description: Returned when `type` is `flat`.
                        properties:
                          amount:
                            type: integer
                            description: The flat tip amount in cents. `500` is $5.00.
                            example: 500
                          currency:
                            type: string
                            description: ISO 4217 currency code. Always `USD`.
                            example: USD
              defaultValue:
                description: Reserved for a pre-selected default tip option. Always `null` today - a default selection is
                  not yet configurable in the Aeropay Merchant Portal. The key is always present in this variant so the shape
                  remains stable, and will begin returning a value once default selection is supported. Treat `null` as no
                  option pre-selected. No type is declared because the eventual shape will follow the selected option.
                example: null
              customTipEnabled:
                type: boolean
                description: Whether the merchant has configured a custom, user-entered tip. When `true`, present a custom
                  tip input alongside `options`. A custom tip is reported here rather than as an entry in `options`.
          - title: Tipping disabled
            type: object
            description: Returned when the merchant has tipping switched off, or has no tipping configuration at all. `enabled`
              is the only key present - `options`, `defaultValue`, and `customTipEnabled` are omitted rather than returned
              empty.
            required:
            - enabled
            additionalProperties: false
            properties:
              enabled:
                type: boolean
                enum:
                - false
                description: Always `false` in this variant. Do not present tipping at checkout.