openapi: 3.0.3
info:
  title: Flute - API Reference Guide
  version: V2 Beta
  description: >
    Build date: 8.13.2026 10:19 AM


    <div style="color: #d32f2f; border-left: 4px solid #d32f2f; padding-left:
    1rem;">

    <strong style="font-size: 1.5em;">⚠️ Beta Release</strong>


    The v2 API is currently in active development. 


    Functionality, request and response formats, field names, and behavior may
    change before the stable release. 

    Review the release notes regularly for updates.


    Contact [Developer
    Support](mailto:developer@flute.com?subject=About%20Flute%20API) for further
    details.

    </div>
servers:
  - url: https://sandbox.api.flute.com
    description: Sandbox environment
  - url: https://api.flute.com
    description: Production environment
security:
  - Bearer: []
x-tagGroups:
  - name: Flute API Overview
    tags:
      - Getting Started
      - API Suite Fundamentals
  - name: Flute API Reference
    tags:
      - API Token Authorization
      - Customers
      - Merchant API Keys
      - Payment Methods
      - Payment Sessions
      - Ping
      - POS Transactions
      - Settings
      - Settlements
      - Terminals
      - Transactions
      - Webhooks
tags:
  - name: Getting Started
    description: >
      The following is an overview for using the Flute API suite and making
      endpoint calls.

      Getting started has the following steps:

      * Creating a Flute Account

      * Developing in the Sandbox Environment

      * Going Live


      # Creating a Flute Account
        <h1 style="margin-top: -12px; margin-bottom: 4px;"></h1>

      Before using Flute payment capabilities or the Flute API suite, you must
      create a Flute sandbox account.


      All development and testing occurs first in a sandbox account.

      The sandbox account is a fully isolated account that mirrors production
      behavior.

      All transactions, sales, and Flute API endpoints may be made in the
      sandbox.

      However, it does not process real transactions.

      It is used to validate your integration, applications, and workflows
      before going live.


      The account is free, does not require approval, and is self managed.

      Use the following procedure to create the Flute sandbox account and a
      merchant API key.

      The merchant API key is required to generate an API token, used to make
      each call.<br>

      See <a
      href="/docs/getting-started/api-authentication#creating-a-flute-sandbox-account"
      target="_blank" rel="noopener noreferrer">Creating a Flute Account</a>



      # Developing in the Sandbox Environment

      The sandbox account is a fully isolated account that mirrors production
      behavior.

      It does not process real transactions.

      Use the sandbox for all testing and app development.

      The Flute support team is available with assistance for developing
      workflows and tools.

      Even after going live, it may still be used to develop and test apps.


      # Going Live

      When your product is ready to be deployed live, the Flute support team
      will work with you to ensure compliance.

      This compliance follows the production readiness checklist.

      It ensures the best and optimal developer, client, and customer
      experience.<br>

      For more information and details about the production readiness checklist,
      <a href="/docs/launch/go-live" target="_blank" rel="noopener
      noreferrer">Production Go-Live Guide</a>.
  - name: API Suite Fundamentals
    description: >-
      The following sections are general information required for using the
      Flute API suite.


      # baseURL Environments

      Flute provides different environments to run endpoints.

      <a id="urlbases"></a>


      **Sandbox**<br>

      The sandbox environment is for development and testing.

      No payments, charges, or invoices will be enforced.

      It is a fully isolated account that mirrors production behavior.


      It is used to validate your integration before going live.

      You will work with your Flute support team developing workflows and tools.


      baseURL: `https://sandbox.api.flute.com`


      **Production**<br>

      The production environment is for deploying the payment system live to
      clients.

      All payments, charges, or invoices are live and will be enforced.


      When your product is ready to be deployed live, the Flute support team
      will work with you to ensure compliance.

      This compliance follows the production readiness checklist.

      It ensures the best and optimal developer, client, and customer
      experience.<br>

      For more information and details about the production readiness checklist,
      see <a href="/docs/launch/go-live" target="_blank" rel="noopener
      noreferrer">Production Go-Live Guide</a>.


      baseURL: `https://api.flute.com`


      **Using the baseURL**<br>

      Use the baseURL instead of the placeholder noted in each endpoint.

      For example, an endpoint may be described in the endpoint documentation
      as:<br>

      `GET {{baseURL}}/v2/customers`


      To make this call in the sandbox environment, use:<br>

      `POST https://sandbox.api.flute.com/v2/customers`


      To make this call in the production environment, use:<br>

      `POST https://api.flute.com/v2/customers`


      # Payment Flow
        <h1 style="margin-top: -12px; margin-bottom: 4px;"></h1>
        The following is a generalized workflow.

      ## Approving a Purchase Request

      1) The customer completes their shopping experience on the merchant's
      website by selecting the products or services.
         They navigate to the checkout page on the merchant's website.
      1) They enter their personal and payment information. This could include
      card details, or net banking information.

      1) The merchant's website captures these details, formatting the details
      as needed to conform to Flute payment gateway requirements.

      1) This sensitive data is transmitted by a secure connection (HTTPS) to
      the Flute payment gateway.
         The Flute payment gateway is a service that makes authorization and sale by cards or ACH (automated clearing house, an electronic network used by financial institutions to process direct deposits).
      1) Upon receiving this information, the Flute payment gateway further
      routes this payment data to the processing center, such as TSYS.

      1) This entity communicates with the customer's bank to get authorization
      or denial for the payment.
         The processing center determines if the payment is approved, that is, if there are sufficient funds or credit available in the customer's account.

      ## Acknowledging a Purchase Request

      1) After the transaction is processed, the processing center sends back a
      response to the Flute payment gateway.
         This response includes details of the transaction, such as whether it was approved or declined.
      1) The Flute payment gateway relays this information back to the
      merchant's website.

      1) The merchant's website receives this information and displays a message
      or signal for the customer.
         Depending on whether the transaction was approved or declined, the appropriate message is displayed to the customer.
         For instance:
         * If transaction was successful, a confirmation message is shown, usually with a transaction ID and other details.<br>
         * If it was declined, the customer is informed and typically asked to try another payment method.

      ## Supported Card Types
        <h1 style="margin-top: -12px; margin-bottom: 4px;"></h1>
        The following credit cards and formats are supported.

      - Diners Club: Card numbers are typically 14 or 16 digits long.

      - Discover: Card numbers are typically 16 digits long.

      - JCB: Card numbers are typically 16 digits long.

      - MasterCard: Card numbers are typically 16 digits long.

      - VISA: Card numbers are typically 13 or 16 digits long.


      # Flute-Defined Enums
        <h1 style="margin-top: -12px; margin-bottom: 4px;"></h1>
        The following are Flute-defined enumerations and indices used in endpoint fields.

        <details>
      <summary>Account Holder Types</summary>


      | id | name     |

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

      | 1  | Business |

      | 2  | Personal |

      </details>


      <details>

      <summary>Account Types</summary>


      | id | name     |

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

      | 1  | Checking |

      | 2  | Savings  |

      </details>


      <details>

      <summary>Business Categories</summary>


      | id | name                         |

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

      | 1  | WebDeveloper                 |

      | 2  | IndependentSoftwareVendor    |

      | 3  | IndependentSalesOrganization |

      </details>


      <details>

      <summary>Credit Card Types</summary>

      <a id="card-types"></a>


      | id | name            |

      |:--:|-----------------|

      | 1  | Visa            |

      | 2  | MasterCard      |

      | 3  | AmericanExpress |

      | 4  | DinersClub      |

      | 5  | Discover        |

      | 6  | JCB             |

      </details>


      <details>

      <summary>Transaction Creator Types</summary>

      <a id="flute-transaction-creator-type"></a>


      | id | name         |

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

      | 1  | Portal       |

      | 2  | ApiToken     |

      | 3  | Terminal     |

      | 4  | Invoice      |

      | 5  | QuickPayment |

      | 6  | WebComponent |

      | 7  | Subscription |

      | 8  | MobileApp    |

      | 9  | TapToPay     |

      </details>


      <details>

      <summary>Partner Statuses</summary>


      | id | name      |

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

      | 1  | Active    |

      | 2  | Suspended |

      </details>


      <details>

      <summary>Partner Business Model Types</summary>


      | id | name                 |

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

      | 1  | SingleAffiliateModel |

      | 2  | SubAffiliateModel    |

      </details>


      <details>

      <summary>Payment Method Types</summary>


      | id | name            |

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

      | 1  | Card            |

      | 2  | ElectronicCheck |

      </details>


      <details>

      <summary>Payment Processor Statuses</summary>


      | id | name     |

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

      | 1  | Active   |

      | 2  | Inactive |

      </details>


      <details>

      <summary>Payment Processor Types</summary>


      | id | name |

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

      | 1  | TSYS |

      | 2  | EFT  |

      </details>


      <details>

      <summary>Payment Session Statuses</summary>


      | id   | name      |

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

      | 1    | Created   |

      | 2    | Cancelled |

      | 3    | Completed |

      | 4    | Failed    |

      </details>


      <details>

      <summary>Transaction Statuses</summary>

      <a id="flute-transaction-statuses"></a>


      | Status Code | Status               |
      Description                                                                                                                                                                                                                                                                                   
      | Available actions |

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

      | 1           | Authorized           | Transaction status after an
      approved `pre-authorization`
      request                                                                                                                                                                                                                              
      | Capture, Void     |

      | 2           | Captured             | Transaction status after approved
      `sale` or `capture`
      request                                                                                                                                                                                                                                 
      | Void              |

      | 3           | Voided               | Transaction status after merchant
      voids an `authorized` request or refunds a `captured` (not settled)
      request                                                                                                                                                                                 
      | N/A               |

      | 4           | Refunded             | Transaction status after merchant
      refunds a `settled`
      request                                                                                                                                                                                                                                 
      | N/A               |

      | 5           | Verified             |
      NA                                                                                                                                                                                                                                                                                            
      | N/A               |

      | 6           | Settled              | Transaction status after successful
      settlement request. All `captured` transactions should have status changed
      to
      `settled`                                                                                                                                                                   
      | Refund            |

      | 7           | Partially Authorized | Transaction status after an
      approved `pre-authorization` request with the approved amount less than
      initially requested. Indicates that the issuer bank has approved only a
      portion of the requested payment amount. The exact authorized amount
      should be checked in the corresponding field. | Capture, Void     |

      | 8           | Informational        |
      NA                                                                                                                                                                                                                                                                                            
      | N/A               |

      | 21          | Scheduled            |
      NA                                                                                                                                                                                                                                                                                            
      | N/A               |

      | 24          | Pending              | Transaction status while changing
      status. This is a temporary
      status                                                                                                                                                                                                                          
      | N/A               |

      | 91          | Declined             | Transaction status after a denied
      `pre-authorization`, `sale` or `capture`
      request                                                                                                                                                                                                            
      | N/A               |

      | 92          | Failed               | Transaction status after a failure
      at any type of
      request                                                                                                                                                                                                                                     
      | N/A               |

      | 92          | Expired              | Transaction status after 7 days in
      `authorized` status (merchant has not captured within this
      time)                                                                                                                                                                                           
      | N/A               |

      </details>


      <details>

      <summary>Transaction Types</summary>

      <a id="flute-transaction-types"></a>


      | id | name               |

      |:--:|--------------------|

      | 1  | Authorization      |    

      | 2  | Sale               |      

      | 3  | Capture            |      

      | 4  | Void               |      

      | 5  | Refund             |      

      | 6  | CardAuthentication |

      | 7  | RefundWORef        |  

      | 8  | TipAdjustment      |  

      | 11 | AchDebit           |   

      | 12 | AchRefund          |     

      | 13 | AchHold            |     

      | 14 | AchUnHold          |      

      | 15 | AchCancel          |      

      | 16 | AchCredit          |       

      </details>
  - name: Payment Methods
    description: >-
      <a id="payment-methods-overview"></a>




      A payment method is a stored, tokenized payment record that can be used to
      process transactions. 


      A stored record is created once and may be used for all future
      transactions.

      This includes submitting the raw card and account details only once, when
      it is first created.


      Tokenization means the sensitive payment data, such as the raw card number
      or bank account number, is submitted to Flute once.

      After that, Flute assigns a non-sensitive value to `paymentMethodId`.

      The `paymentMethodId` is then used as the payment reference for later
      transactions.


      Payment methods can be set to one of the following types: linked to a
      customer or an orphan.


      **Linked to a customer**<br>

      A customer is a defined business entity.

      Information includes the company name, the owner's name, billing and
      shipping addresses, and different kinds of payment methods.

      Rather than re-entering the information, it can be saved and used later as
      needed.

      A payment method linked to a customer can be used by referencing the
      customer using the `customerId` value.


      **An orphan**<br>

      An orphan payment method is a stored payment method (card or ACH account)
      that belongs to the merchant directly.

      If the customerId is omitted from the payment method, the payment method
      is created as an orphan.

      It exists in the merchant's vault but has no customer record associated
      with it.

      A practical use case would be for a one-time transaction that uses a
      tokenize card but without creating a full customer profile.


      There are two types of payment method: Cards and ACH.


      **Cards**<br>

      Credit or debit cards are stored as a token.

      The raw card number is never fully displayed.

      It always uses a masked card number, such as `************1111`.

      A card payment type includes a card type (such as Visa or MasterCard),
      credit or debit card type, expiration date, and an optional payment name,
      a name recognizable to the merchant.


      **ACH accounts**<br>

      ACH accounts are electronic bank accounts transfers.

      They are stored with routing number, account number, account type
      (Checking/Savings), and account holder type (Personal/Business)

      Business ACH accounts also carry a payment name, a name recognizable to
      the merchant.


      Either can be marked as the default payment method for a customer but only
      one payment method may set as the default at a time.
  - name: Settings
    description: >+
      <a id="settings"></a>


      This endpoint group lists the preset and default settings for payments,
      discounts, and premium charges.


      **Levels 2 and 3**<br>


      Some settings list information about levels, specifically Levels 2 and 3.


      Levels refer to data standards for credit card transactions.

      They provide increasingly detailed standards.

      Higher data standards qualify for lower interchange rates from Visa and
      Mastercard.

      That means, merchants save on processing fees.

      Advanced level are often required by many government and large enterprise
      buyers.

      This also accommodates buyers needing detailed transaction data for
      accounting and reconciliation.


      **Level 1**<br>

      Level 1 is the most basic data standards for credit card transactions.

      In general industry terms, Level 1 is simply a standard transaction with
      basic data.

      This includes the amount, date, merchant name, card number.

      It's the default when no enhanced data is provided. 


      **Level 2**<br>

      This is an enhanced data standard.

      It is typically the standard for business to business transactions, such
      as corporate, and purchasing cards.


      Level 2 adds:

      * Customer code and purchase order number

      * The tax amount

      * A tax indicator.

      This is a flag indicting if tax is included in the transaction amount, and
      if so, what kind.


      **Level 3**<br>

      This is the most advanced data standard.

      It offers the most detail and accountability.

      It is typically the standard for large business to business transactions,
      government transactions, and government purchase cards.

      Level 3 can reduce interchange fees by 0.5% to 1.5% compared to Level 1.

      This discount become significant at high transaction volumes.


      Level 3 adds:

      * Line-item details, such as product codes, descriptions, quantities, unit
      prices

      * Ship-to and ship-from postal codes

      * Freight amount

      * Discount amount


  - name: Settlements
    description: >+
      <a id="settlements"></a>


      Settlement is the process of actually transferring funds between parties
      to finalize a transaction

      This is different from authorization, which just reserves or confirms
      funds are available.

      That means funds are not instantly available for each transaction.

      Merchants may see a delay between a sale and the funds deposited in their
      account.


      The typical lifecycle that includes settlement:


      * **Authorization**. An authorized transaction is one that has been
      approved and funds are held or reserved. 

      No money has moved yet.<br><br>

      For example, the following call starts a transaction with the
      `captureMethod` of `Auto`.

      This automatically adds the transaction in an open settlement batch when
      the transaction is completed.

      The call returns `transactionId`, which may be used to reference this
      transaction.

          <details>
          <summary>Sample Authorization Call</summary>
          <a id="sample-authorization-call"></a>
          
          ```csharp
            POST /v2/transactions
            Authorization: Bearer {{apiKey}}                                                                                          
            Content-Type: application/json
            {                                                                                                                         
            "baseAmount": 150.00,                                                                                                 
            "currencyCode": "USD",
            "customerInitiatedTransaction": true,
                "transactionDetails": 
                {
                    "cardData":
                    {
                        "captureMethod": "Auto",
                        "paymentMethodDetails":
                        {
                          "cardNumber": "4111111111111111",
                          "securityCode": "737",
                          "expirationMonth": 9,
                          "expirationYear": 2027
                          }
                      }
                  }
              }
          ```
          
          </details>

      * **Capture or batch**. Approved transactions are grouped together, or
      batched, for later processing.

        If `captureMethod` is `Auto`, no additional processing is required at this step.
        The transaction has been added to the settlement batch automatically.

        If `captureMethod` is `Manual`, the transaction must be explicitly added to the settlement batch.
        In this case use `POST /v2/transactions/{{transactionId}}/capture` to capture it to the settlement batch.
        
        Care must be taken when using `Manual` because if the transaction is never captured, the authorization simply expires and no funds move.

        <details>
        <summary>Sample Capture Call</summary>
        <a id="sample-capture-call"></a>

        Omit the body (or send {}) for a full capture. Once captured, it enters the open settlement batch.

        ```csharp
        POST /v2/transactions/{{transactionId}}/capture
        Authorization: Bearer {{apiKey}}
        Content-Type: application/json

        {
          "amount": 150.00
        }
        ```

        </details>

      * **Settlement**. Settlement is the step where an authorized transaction
      becomes a real transfer of money.


      The batch is submitted to the card networks or banks.

      This processing includes moving the money from the cardholder's bank,
      through the network, to the acquiring bank.

      It eventually ends at merchant's account, minus fees.

      Use `POST /v2/settlements/settle` to initiate the settlement batch.


      This batch processing usually happens on a schedule, such as daily batch
      settlement at the end of business.

  - name: Terminals
    description: >+
      <a id="terminals"></a>


      A terminal represents a physical payment device deployed to a merchant to
      accept card and other electronic payments.

      Each terminal is tracked from the point it's ordered through its active
      use in the field, including hardware details, connectivity, and security
      provisioning.


      The combination of all the details and attributes portrays and monitors a
      terminal's readiness, connectivity, and security posture throughout its
      deployment.

  - name: POS Transactions
    description: >+
      <a id="payment-pos-transactions-overview"></a>


      POS (point of sales) transactions represent payment transactions that are
      initiated and driven directly on a physical terminal device.

      This is in contrast to transactions created purely through an API, such as
      a card-not-present charge.


      A POS transaction is the record of a payment flow that runs through a
      physical terminal.

      The point of service, such as a diner's table, creates it and enters at
      the terminal what to charge.

      The transaction can then be polled or listed to see the resulting status
      and the core transaction.

      The typical lifecycle that includes a POS transaction:


      **Creating one**<br>

      Use `POST /v2/pos/transactions`.<br>

      This initiates a transaction on a specific terminal device with predefined
      details.

      These include the amount, transaction type, such as sale or authorization,
      currency, customer, pricing type, and whether to wait for the terminal to
      accept it. 

      The terminal handles the actual card read (readingMethod) and cardholder
      interaction.


      **Tracking status**<br>

      A POS transaction has its own lifecycle status (posTransactionStatus).

      This is such as TransactionProcessing or Completed and is separate from
      the underlying core transactionId it eventually links to once processed.


      **Listing them**<br>

      Use `GET /v2/pos/transactions`.<br>

      This returns a paginated list of POS transactions, filterable by
      terminalId, showing fields like processedAmount, transactionType, and the
      linked transactionId.





  - name: Transactions
    description: >+
      <a id="payment-transactions-overview"></a>


      At the center of Flute's payments model is the *transaction*.

      A transaction is a record created every time money moves through a
      merchant's account.


      A transaction is created with a single call: \

      `POST /v2/transactions`


      Every transaction carries the same core shape regardless of payment type:

      * `paymentProcessorId` specifies the processor handling the transaction.

      * `baseAmount` and `currencyCode` specify the transaction amount.

      * `referenceId` specifies a value the merchant chooses for their own
      bookkeeping.

      * `transactionDetails` specifies an object holding either the `cardData`
      or `achData` depending on how the customer is paying.


      Each transaction goes through the same endpoint.

      It comes back with the same response envelope, just populated with
      different `processorResponse` details.

      This includes whether someone is charging a saved card, running a
      brand-new card number inline, or debiting a bank account through ACH.


      Card transactions carry an extra decision point that ACH doesn't:
      `captureMethod`.

      This is set to either `Auto` or `Manual`.

      * `Auto` capture means the authorization and the capture happen in one
      step, and the transaction lands in an Approved state immediately, ready to
      settle.

      * `Manual` capture splits it into two steps: the initial call only
      authorizes the funds and returns a Pending transaction, and a separate
      call to `POST /v2/transactions/{transactionId}/capture` later finalizes
      it.


      This distinction matters most for merchants who need to confirm inventory
      or finalize an order total.

      For example, a restaurant might close a tab with tips added before
      actually pulling the money.

      It's why the API treats "money authorized" and "money captured" as two
      different states rather than collapsing them into one.


      Once a transaction is captured or approved, several other endpoints act on
      it rather than creating a new one.

      * `POST /v2/transactions/{transactionId}/reversal` reverses a transaction
      outright.

      * `POST /v2/transactions/{transactionId}/tip-adjustment` lets a merchant
      amend the tip on an existing charge, common in card-present environments
      where the tip is added after the initial swipe.

      * `POST /v2/transactions/reversal` for pulling money back after
      settlement.

      * `POST /v2/transactions/credit` for issuing money without tying it to a
      prior reference.

      * `POST /v2/transactions/{transactionId}/ach-hold` for placing a hold on a
      pending ACH transaction.


      Every transaction also comes back with a rich `amountDetails` and
      `processorResponse` breakdown rather than just a status code.

      * `amountDetails` separates `baseAmount` from `tipAmount`, `tipRate`,
      `surchargeAmount`, and `discountAmount`.

      A merchant can see exactly how a `processedAmount` was assembled instead
      of just the final total.

      * `processorResponse` reports which underlying processor ran the
      transaction, TSYS, for instance, on the card examples in the spec, or a
      plain ACH label for bank debits, along with a response code and a
      human-readable message.

      For card transactions there's also an
      `addressVerificationServiceResponse`, showing whether the billing address
      and the postal or ZIP code the customer supplied matched what the card
      issuer has on file.

      This is one of the signals merchants use to judge fraud risk on a given
      charge.


      The following is an example of a basic transaction.

      A merchant charges $100 on a saved card with auto-capture, and the
      customer adds a $15 tip at checkout.


      Request \

      `POST /v2/transactions`

      ```json

      {
          "paymentProcessorId": "a2f2c2e7-0b23-4682-8f99-ab7707205461",
          "baseAmount": 100.00,
          "currencyCode": "USD",
          "referenceId": "REF-CARD-SALE-001",
          "isCustomerInitiatedTransaction": true,
          "pricingType": "Card",
          "transactionDetails": {
              "cardData": {
                  "captureMethod": "Auto",
                  "paymentMethodId": "e397e367-bc4a-4b69-bd78-32e3e12327c2"
              }
          }
      }

      ```


      Because the `captureMethod` is `Auto`, Flute authorizes and captures the
      charge in the same call.

      The response comes back already settled from the API's perspective:


      Response

      ```json

      {
          "transactionId": "5f6f782f-37af-44e1-bb18-2bc35e411899",
          "transactionStatus": "Approved",
          "processedAmount": 115.5,
          "currencyCode": "USD",
          "amountDetails":
          {
              "baseAmount": 100.00,
              "tipAmount": 15,
              "surchargeAmount": 3,
              "discountAmount": 2.5
          },
          "processorResponse":
          {
              "processorName": "TSYS",
              "responseCode": "00",
              "responseMessage": "Approved",
              "responseDefinition": "Approved and completed"
          },
          "addressVerificationServiceResponse":
          {
              "action": "Allow",
              "responseCode": "Y",
              "description": "Address and ZIP match"
          }
      }

      ```

      The `processedAmount` ($115.50) reflects the base charge plus the tip and
      a surcharge, minus a discount.

      This is exactly as itemized in `amountDetails`.


      The transaction is done.

      There is no separate capture call needed.

      This merchant chose the auto-capture path rather than the
      authorize-then-capture flow used for something like a restaurant tab.


  - name: API Token Authorization
    description: >-
      <a id="generating-an-api-token"></a>

      An API token is required for each endpoint use.

      An API token can only be created after an account is created, registered,
      and at least one API key has been created.


      The API token is an authorization token needed for each for endpoint.

      It is an encrypted string that combines the client Id and client secret
      from an API key (created earlier).

      It contains authentication and authorization coding.

      This includes any privileges the user or account affords.

      Being encrypted means the API token is safe to expose in frontend code.

      The API token is time-sensitive and expires after an amount of time.


      It may be created as needed.

      We recommend generating a new API token before each endpoint use.

      This ensures the API token will be valid for each call.


      <a id="baseOAuthURL"></a>

      The API token is an OAuth 2.0 Client Credentials authorization flow.

      The Client Credentials Flow is an OAuth 2.0 authorization Bearer grant.

      This means a server-side application obtains an access token using its
      client credentials (client ID and client secret) to protect resources.


      <h3 style="margin-top: 24px; margin-bottom: 4px;">Base authorization
      URLs</h3>

      An API token is created for the environment it will be used in.

      There are two available Flute environments: Sandbox and Production.


      **Sandbox**<br>

      Use the sandbox environment for development and testing.

      No payments, charges, or invoices will be enforced.<br>

      Endpoint: `POST https://sandbox.oauth.api.flute.com`


      **Production**<br>

      Use the production environment for deploying the payment system live to
      clients.

      All payments, charges, or invoices will be enforced.<br>

      Endpoint: `POST https://oauth.api.flute.com`


      The sandbox and production environments API tokens use the same API key
      and differentiated only by the environment endpoint.

      The two API tokens types are not interchangeable and cannot be used in an
      environment different than they were created for.


      The API key that was created in the initial account registration is needed
      to create an API token.

      The **client ID** and **client secret** are used together to create an API
      token.


      The following is an example of obtaining an API token for the sandbox
      environment:

      ```shell

      curl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \

      -u '594838709594...38697242c:9eb2c6859daa4...d8ae5da9' \

      -H 'Content-Type: application/x-www-form-urlencoded' \

      -d 'grant_type=client_credentials&scope=offline_access'

      ```


      The following is an example of refreshing an API token for the sandbox
      environment:

      ```shell

      curl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \

      -u '594838709594...38697242c:9eb2c6859daa4...d8ae5da9' \

      -H 'Content-Type: application/x-www-form-urlencoded' \

      -d 'grant_type=refresh_token&refresh_token=def50200newrefresh123456789'

      ```


      Regardless of either obtaining or refreshing an API token, the following
      example is passed back in the response body:

      ```json

      {

      "access_token": "u7BYwJx26U1lT...TZpKvndLCC4",

      "refresh_token": "def50200newrefresh123456789",

      "token_type": "Bearer",

      "expires_in": 900

      }

      ```


      <h3 style="margin-top: 24px; margin-bottom: 4px;">Using the API Token</h3>


      The token endpoint returns both an `access_token` and a `refresh_token`.

      The lifespan of the `access_token` is indicated by the `expires_in` value.

      The lifespan of the `refresh_token` is set by OAuth standards.


      Clients are encouraged to use either token as needed.

      For example, it may be easier to call for a new `access_token` before each
      user-initiated action.

      The `access_token` may also be left to expire, and then use
      `refresh_token` procedures to continue.

      For example, mobile phones apps may need to use the `refresh_token` to
      avoid consistently signing back in.


      In the endpoint header, use the following `access_token` format:

      ```json

      "Authorization": "Bearer u7BYwJx26U1lT...TZpKvndLCC4"

      ```


      The following example creates a new access token:

      ```shell

      curl 'https://sandbox.api.flute.com/v2/transactions' \

      -H 'Authorization: Bearer u7BYwJx26U1lT...TZpKvndLCC44' \

      -H 'Accept: application/json'

      ```

      As a reminder, always secure your client ID and especially your client
      secret.

      Never expose the client secret in client-side code or public repositories.

      It should be kept private and secure.

      If it is suspected that the client secret has been compromised, the owning
      API key must be deleted.

      A new API key can then be created.


      <h3 style="margin-top: 24px; margin-bottom: 4px;">Error Responses</h3>


      If authentication fails, the token endpoint returns an error.

      The following are commonly encountered errors.


      | HTTP Status      | Common
      Cause                                                              |

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

      | 400 Bad Request  | Missing or invalid grant_type, or malformed request
      body.                 |

      | 401 Unauthorized | The API token has likely expired. Create a new one
      and retry the request. |
  - name: Payment Sessions
    description: >-
      <a id="payment-sessions-overview"></a>

      A payment session is an in-progress payment transaction.

      It is a temporary, time-limited context created when a client initiates a
      payment flow.


      It becomes a secure, stateful environment for completing a payment
      transaction. 

      Instead of passing sensitive payment data on every request, the payment
      session persists transaction details. 

      This includes the amount, currency, payment method, and status.

      It exposes only the payment session identifier to the client. 

      This reduces the risk of data exposure.


      The use of a payment session is applicable only to Flute Elements and
      Flute Checkout.

      Some fields may include a note about their use, and specifically for
      Elements and Checkout.


      The following is a common workflow for using a payment session.


      * Create the payment session.

      * Connect through Flute Elements or Flute Checkout.

      This may include selecting a payment method, applying discounts or
      promotions,

      authorizing the payment, and capturing the funds.

      Many of these individual steps will be transparent to the client when
      using Flute Elements or Flute Checkout.


      At each step, the payment session holds the transaction state.

      This means each step can update the session without resubmitting the full
      transaction data. 

      If the client navigates away but later returns or does not complete the
      transaction immediately, the session can be retrieved by its identifier.

      The flow resumed from where it left off.


      The payment session can end in one of the following ways:

      * The transaction is completed.

      Check the status of the transaction for its success.

      See `POST /v2/payment-sessions/{{paymentSessionId}}`, the field `status`.

      * The transaction is canceled.

      The client chooses to not complete the transaction.

      If the client cannot later resume the transaction.

      A new payment session must be started.

      * The payment session expires or times out.

      When creating a payment session, an expiration date and time can be
      assigned.

      If the transaction is neither completed nor explicitly canceled, the
      payment session cancels itself.

      Like the cancel operation, the state of the transaction is saved.

      The client may retrieve the payment session later and continue the
      transaction.
  - name: Merchant API Keys
    description: >-
      API keys may be managed programmatically.

      This includes creating and deleting API keys.

      This is the same capability as through the partner and merchant
      dashboards.


      How the API keys are managed depends on the source of the API token used
      for the endpoints.

      There are two sources: Partner and merchant.

      * A partner API key used to create the API token affects only merchants
      associated with the partner.

      The partner can manage the API keys for their individual merchants.

      A partner API key can be created only in the partner dashboard.

      * A merchant API key used to create an API token that affects only that
      one merchant.

      This includes both a merchant associated with a partner and standalone
      merchants (those not associated with any partner).


      Each merchant API Key endpoint explains the details of using either API
      token source.


      The API keys are specific to a single merchant.

      They are not interchangeable from among different merchants, even if they
      are each associated with the same partner.

      That is, merchants cannot use API keys from any other merchant.

      Standalone merchants (those not associated with any partner) manage their
      API keys through the merchant Flute dashboard.


      Merchant API keys are required only if the merchant application or account
      needs to integrate with the API suite.

      A merchant API key is required to create API tokens (also called access
      tokens), needed to make endpoint calls.

      Except for the Merchant API Key endpoints, only merchant API tokens (API
      tokens created from a merchant API key) can be used with any other
      endpoint.

      Partner API keys cannot be used to create API tokens otherwise.

      To generate an API token from an API key, see <a href="#get-oauth-token"
      style="text-decoration: underline;">GET /oauth-token</a>.


      The number of API keys is determined by the partner or standalone
      merchants.

      They may have as many or as few as required.

      For more information about API keys, see <a
      href="/docs/getting-started/api-authentication" target="_blank">Creating
      an API Key</a>.


      This Merchant API Key group consists of the following endpoints:

      * To list available keys, see `GET /v2/api-keys`

      * To create an API key, see `POST /v2/api-keys`

      * To revoke an API key, see `DELETE /v2/api-keys/{{clientId}}`
  - name: Customers
    description: >-
      Customers are entities used to organize and manage saved payment methods.

      These include billing details, transaction history, and recurring
      payments.

      A customer record may contain their name, email address, phone number,
      billing, and shipping addresses.

      Having a customer association is not required to pay for transactions.


      **Creating a customer**<br>

      Customers may be created in the following ways:


      * Explicitly with `POST /pay-api/v1/customers`.

      This includes full customer details and optional payment methods.

      * The Merchant Portal. Merchants and their partner can create customers
      through this portal.

      * Implicitly with `POST /pay-int-api/payment-sessions`.

      When this endpoint's `mode` is either `SaveMethod` or `PaymentAndSave`, if
      `customerId` is not provided, one will be created.

      * Implicitly with `POST /pay-int-api/invoices/publish`.

      If `customerId` is not provided, one will be created.


      New `customerId` values can be reviewed with `GET /v2/customers`.


      **Pay transactions**<br>

      Customers may pay transactions in one of three ways:

      * Vaulted payments

      * Standalone tokenization, also known as orphan vaulted payment

      * Account supported


      **Vaulted payments**<br>

      Customers can be associated with one or more vaulted payment methods.

      A vaulted payment method is a securely stored payment credential.

      This applies to credit card or bank account payments.

      A vaulted payment method is a securely stored payment credential.

      This is considered a more secure method rather than storing the card
      number directly.

      That information has previously been tokenized and saved for future use.

      Vaulted information can be safely accessed through a payment identifier.

      This is typically used for recurring billing, subscriptions, saved
      checkout experiences, and card-on-file transactions.


      In the transaction payment, the field `customerId` is provided.

      The customer's vaulted payment methods are available for selection.


      **Standalone tokenization**<br>

      Clients may use standalone tokenization, also known as an orphan vaulted
      payment.

      This allows a payment method to be vaulted even when the payer has not
      been recognized as a customer entity.

      The transaction proceeds using a previously established payment method
      identifier.


      Standalone tokenization is useful when a payment method must be vaulted
      before a customer profile exists.

      This includes guest checkouts, delayed onboarding, account setup, or
      card-on-file collection before registration is complete.


      In the transaction payment, the field `customerId` is omitted but
      `paymentMethodId` is provided.

      This indicates the merchant's orphan vaulted payment method is used.


      **Accounts Supported**<br>

      Clients may use accounts supporting orphan payments.

      This is a form of a payment method that temporarily exists without a
      customer association.


      In the transaction payment, both fields `customerId` and `paymentMethodId`
      are omitted.

      The transaction uses the credit or debit card, or bank account data
      supplied in the request.
  - name: Webhooks
    description: >
      Webhooks are notifications that are automatically sent when specific
      predefined events occur.


      Webhooks are commonly used, for instance, when payment processors need to
      notify a client that a charge succeeded or failed, when a subscription
      renews, or an incoming SMS message is available.


      They replace polling.

      This polling might have been:

      * Software polling for a status change either through a loop, or timed
      queries.

      * Manually by a user explicitly polling expecting a response or pending
      status to be returned.


      A merchant can only affect their own webhooks.

      They cannot view or modify other merchant's webhooks.

      Likewise, a partner can only affect merchants associated to them.

      They cannot affect merchants of other partners.


      **Required API Permissions**<br>

      Required API Permission: Webhooks


      **Webhook Workflows**<br>

      To create and manage Flute webhooks, use the following procedures and
      workflows.


      **Creating Webhooks**<br>

      1\) Optionally, review all the valid event types.

      Webhooks can accept one or more event types.

      Each event type is evaluated independently.

      Selected events are not required to be related and may relate to different
      transaction types or workflows.

      For organizational reasons, multiple webhooks can be created.

      Each webhook can then have its own set of event types.


      To list all available events, see `GET /v2/webhooks/event-types`


      2\) Create the webhook<br>

      To create the webhook, see `POST /v2/webhooks/endpoints`


      3\) Test the webhook<br>

      Verify the endpoint is reachable (sends a test ping).<br>

      To test the webhook, see `POST /v2/webhooks/endpoints/{webhookId}/ping`


      **Managing Webhooks**<br>

      The following set of endpoints manage webhooks.


      * This endpoint provides a list of all available webhook for the
      merchant.<br>

      To list all the available webhooks, see `GET /v2/webhooks/endpoints`


      * This endpoint retrieves webhook details specified by its webhookId.<br>

      To retrieve a specific webhook, see `GET
      /v2/webhooks/endpoints/{webhookId}`


      * This endpoint provides an ability to update or change a webhook.

      For example, the set of event types may be changed without having to
      create a new webhook.<br>

      To modify or update a specific webhook, see `PATCH
      /v2/webhooks/endpoints/{webhookId}`


      * This endpoint deletes the specific webhook.

      This action can neither be undone nor can the webhook be retrieved.

      This does not erase entries in the log file.<br>

      To delete a specific webhook, see `DELETE
      /v2/webhooks/endpoints/{webhookId}`


      **Monitoring Webhooks**<br>

      The following set of endpoints monitor webhooks.

      These may be used to verify success of an attempt or assist in determining
      the cause of a problem.


      * This endpoint lists success level of delivery attempts.<br>

      To view webhooks delivery attempts log file, see `GET
      /v2/webhooks/delivery-logs`


      * This endpoint lists success level of delivery attempts for a specified
      webhook.<br> 

      To view a specified webhook delivery attempts log file, see `GET
      /v2/webhooks/delivery-logs/{webhookId}`

      Get full request/response detail for a single attempt


      * This endpoint exports the delivery logs file.

      It may be specified as either a CSV or JSON format.<br>

      To export webhooks delivery attempts log file, see `GET
      /v2/webhooks/delivery-logs/export`


      * This endpoint retries a failed delivery.<br>

      To retry a failed delivery, see `POST
      /v2/webhooks/delivery-logs/{id}/retry`


      **Client Handling of Messages**<br>

      The webhook sends a message to the URL specified by the client.

      This is `endpointUrl` of `POST {{baseURL}}/v2/webhooks/endpoints`.

      The message is considered successfully sent after a send confirmation is
      received.

      If that send confirmation was not successfully confirmed, the message will
      be sent, or retried, a number of times before failing.


      After being successfully sent to the receiving endpoint or URL, 

      it is the client's responsibility to handle it after that.

      As a best practice, we recommend that the message is first verified to be
      from Flute.

      For example, use HMAC verification.

      This step greatly increases security and reduces system vulnerabilities
      such as spoofing, tampering, or data injection.

      The IP address could be blocked to prevent future intrusions.


      Once the sender is verified, the client can process the message as they
      need.

      For example, code or an application on the receiving server may create an
      email or SMS message to send to the client.
  - name: Ping
    description: >-
      Ping is a health check endpoint.

      It verifies the service is currently reachable.

      This also checks that an API token is still valid.


      This is a simple endpoint call. 

      It takes no parameters and returns no response body.

      A successful call returns only a 200 OK.

      That minimalism is intentional.

      It is typically hit frequently and automatically rather than as part of
      real business logic.


      This endpoint is useful as:

      * an application startup check when an integration boots.

      * a periodic keep-alive in a monitoring dashboard, 

      * a quick manual test after rotating an API key.


      It shares the same error-handling shape as every other endpoint, such as
      response codes for 400, 401, 403, 429, or 500.

      These error response codes are diagnostically useful, too.

      For example, a response code of 401 indicates the API token is bad or
      expired.


      <span class="api-seealso">See Also:</span><br>

      To ping a webhook endpoint, see `POST
      /v2/webhooks/endpoints/{{webhookId}}/ping`
paths:
  /oauth2/token:
    post:
      tags:
        - API Token Authorization
      summary: Obtains or refreshes an API token
      operationId: get-oauth-token
      description: >
        <a id="get-oauth-token"></a>

        <span class="api-endpoint">POST {{<a
        href="#baseOAuthURL">baseOAuthURL</a>}}/oauth2/token</span>


        This endpoint obtains or refreshes an API token.


        Each Flute endpoint (with the exception of this authentication endpoint)
        requires an API token, also called an access token).

        It is an encrypted string generated from a Flute-owned authentication
        server.

        The API token is a combination of an authentication of the user and an
        authorization of the user's permissions.


        Each API token has a limited lifespan.

        This is often 900 seconds, or 15 minutes although the actual value is
        returned by the authentication call. 

        After the API token expires, it can no longer be used to make calls.

        The API token must then be obtained anew or refreshed.


        ### Obtaining API Tokens

        There are two ways to get a valid API token: **Obtaining a new token**
        or **Refreshing an existing token**.


        The endpoint for obtaining a new API token or to refresh an existing one
        is the same.

        Only the request body fields are different.

        Selecting the appropriate option displays the relevant fields and
        information.


        **Obtaining a new token**<br>

        A new token must be obtained because:

        * No token exists.

        This may be from the user just logging in or the previous API token
        expired.

        * The stored `refresh_token` expired, has been revoked, or gets rejected
        by the server (such as a refresh attempt failed).

        * A different API key is being used.


        To obtain a new API token, see the call below, selecting **Obtain a new
        token**.

        This displays the fields and details needed to make the call.


        **Refreshing an existing token**<br>

        An existing API token may be refreshed to create a new, valid API token.

        That existing API token may be currently valid or has expired recently.

        The goal is to provide continuous operation.

        This allows users to remain authenticated without repeating full
        credential authentication on every renewal.


        An API token may be refreshed because:

        * The current `access_token` is about to or has already expired.

        * A valid `refresh_token` is currently available and valid from the most
        recent API token.


        To refresh an API token, see the call below, selecting **Refresh an
        existing token**.

        This displays the fields and details needed to make the call.


        ### API Token Types

        API token types depend on the type of API keys used to create them.

        The resulting API token type will be one of following:

        * Merchant token if it is created from a merchant API key.

        * Partner token if it is created from a partner API key.


        The two API keys types are not interchangeable.

        Most Flute endpoints require a merchant token.

        The endpoint description specifies the required API key type.

        Endpoints requiring a partner token will be explicitly marked.

        Otherwise, a merchant token is required.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  title: Obtain a new token
                  description: >-
                    Use `grant_type=client_credentials` to obtain a brand-new
                    API token from your API key.
                  required:
                    - client_id
                    - client_secret
                    - grant_type
                    - scope
                  properties:
                    client_id:
                      type: string
                      description: |
                        Specifies client ID from the API key for the account.

                        Example: 59483870959438697242c
                      example: 59483870959438697242c
                    client_secret:
                      type: string
                      description: >
                        Specifies the client secret from the API key for the
                        account.


                        Example: 9eb2c6859daa4d8ae5da02a9
                      example: 9eb2c6859daa4d8ae5da02a9
                    grant_type:
                      type: string
                      enum:
                        - client_credentials
                      description: |
                        Specifies the literal value `client_credentials`.

                        Example: client_credentials
                      example: client_credentials
                    scope:
                      type: string
                      enum:
                        - offline_access
                      description: |
                        Specifies the literal value `offline_access`.

                        Example: offline_access
                      example: offline_access
                - type: object
                  title: Refresh an existing token
                  description: >-
                    Use `grant_type=refresh_token` with a prior `refresh_token`
                    value to get a new API token without re-authenticating.
                  required:
                    - client_id
                    - client_secret
                    - grant_type
                    - refresh_token
                  properties:
                    client_id:
                      type: string
                      description: |
                        Specifies client ID from the API key for the account.

                        Example: 59483870959438697242c
                      example: 59483870959438697242c
                    client_secret:
                      type: string
                      description: >
                        Specifies the client secret from the API key for the
                        account.


                        Example: 9eb2c6859daa4d8ae5da02a9
                      example: 9eb2c6859daa4d8ae5da02a9
                    grant_type:
                      type: string
                      enum:
                        - refresh_token
                      description: |
                        Specifies the literal value `refresh_token`.

                        Example: refresh_token
                      example: refresh_token
                    refresh_token:
                      type: string
                      description: >
                        Specifies the refresh token received from a prior token
                        request.


                        Example: YhjQpM...EVkVuB
                      example: YhjQpM...EVkVuB
      responses:
        '200':
          description: OK. The API token was issued successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                  - token_type
                properties:
                  access_token:
                    type: string
                    description: |
                      Indicates the API token.

                      Example: 213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14
                    example: 213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14
                  token_type:
                    type: string
                    description: |
                      Indicates the token type.

                      Example: Bearer
                    example: Bearer
                  expires_in:
                    type: integer
                    description: >
                      Indicates the expiry, or lifetime, (in seconds) of the API
                      token.


                      Example: 900
                    example: 900
                  refresh_token:
                    type: string
                    description: >
                      Indicates the refresh token (only for authorization_code
                      grant).


                      Example: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25
                    example: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25
                  scope:
                    type: string
                    description: |
                      Indicates the granted scopes, space-delimited.

                      Example: null
                    example: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
  /v2/customers:
    get:
      tags:
        - Customers
      summary: Lists customers
      operationId: flute-v2-get-customers
      description: >
        <a id="flute-v2-get-customers"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/customers</span>


        This endpoint lists customers.


        <span class="api-seealso">See Also:</span><br>

        To create a new customer, see `POST /v2/customers`.<br>

        To retrieve a customer by ID, see `GET /v2/customers/{customerId}`.<br>

        To update a customer, see `PATCH /v2/customers/{customerId}`.


        <span style="font-size:8pt;">
          [ <a href="#get_v2_customers_query_parameters">Query parameters</a> ]
          [ <a href="#get_v2_customers_response_body">Response body</a> ]
        </span>


        <a id="get_v2_customers_query_parameters"></a>
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/asc'
        - $ref: '#/components/parameters/sortby'
        - name: fullName
          in: query
          description: Filters by the full name.
          schema:
            type: string
            x-method: query
            example: Alexandro Peppared
        - name: email
          in: query
          description: |
            Filters by an email.
          schema:
            type: string
            x-method: query
            example: pepparedstreetcafe@example.com
        - name: companyName
          in: query
          description: |
            Filters by a company name.
          schema:
            type: string
            x-method: query
            example: Peppared Street Cafe
        - name: mobilePhoneNumber
          in: query
          description: |
            Filters by a mobile phone number.

            Free-form search input, E.164 format is not required.
            This allows partial digits or legacy formats.
          schema:
            type: string
            x-method: query
            example: '+14155552309'
        - $ref: '#/components/parameters/createdFrom'
        - $ref: '#/components/parameters/createdTo'
      responses:
        '200':
          description: OK <a id="get_v2_customers_response_body"></a>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfListCustomersResponseDto'
              example:
                items:
                  - customerId: f81ca0b7-fa2e-4a6c-be9e-7def348c1ddf
                    externalId: CUST-EXT-001
                    firstName: John
                    lastName: Doe
                    companyName: Acme Corp
                    email: john.doe@acme.com
                    mobilePhoneNumber: '+14125553845'
                    billingAddress:
                      city: New York
                      countryCode: US
                      addressLine1: 123 Main Street
                      addressLine2: null
                      postalCode: '10001'
                      stateCode: NY
                    lastTransactionDate: '2026-05-29T22:04:31.771Z'
                    paymentMethodsCount: 3
                  - customerId: a98bbbba-40e6-4114-970a-078ebfdcbac2
                    externalId: CUST-EXT-002
                    firstName: Jane
                    lastName: Smith
                    companyName: Tech Solutions Inc
                    email: jane.smith@techsolutions.com
                    mobilePhoneNumber: '+14155557890'
                    billingAddress:
                      city: Los Angeles
                      countryCode: US
                      addressLine1: 456 Oak Avenue
                      addressLine2: null
                      postalCode: '90001'
                      stateCode: CA
                    lastTransactionDate: '2026-06-01T22:04:31.771Z'
                    paymentMethodsCount: 1
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 150
                  totalPages: 8
                  hasMore: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
        - Customers
      summary: Creates a customer
      operationId: flute-v2-post-customers
      description: >
        <a id="flute-v2-post-customers"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/customers</span>


        This endpoint creates a customer.


        <span class="api-seealso">See Also:</span><br>

        To list customers, see `GET /v2/customers`.<br>

        To retrieve a customer by ID, see `GET /v2/customers/{customerId}`.<br>

        To update a customer, see `PATCH /v2/customers/{customerId}`.<br>

        To delete a customer, see `DELETE /v2/customers/{customerId}`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequestDto'
            example:
              firstName: John
              lastName: Doe
              companyName: Acme Corp
              email: john.doe@acme.com
              mobilePhoneNumber: '+14125553845'
              hasSmsConsent: true
              shouldUseBillingAsShippingAddress: false
              billingAddress:
                city: New York
                countryCode: US
                addressLine1: 123 Main Street
                addressLine2: Suite 100
                postalCode: '10001'
                stateCode: NY
              shippingAddress:
                city: Brooklyn
                countryCode: US
                addressLine1: 456 Market Street
                addressLine2: Suite 7B
                postalCode: '11201'
                stateCode: NY
              paymentMethodsCreditCards:
                - paymentName: My Visa Card
                  cardNumber: '4111111111111111'
                  securityCode: '123'
                  expirationMonth: 12
                  expirationYear: 2032
              paymentMethodsAchAccounts:
                - paymentName: Business Checking
                  routingNumber: '021000021'
                  accountNumber: '123456789'
                  taxId: 12-3456789
                  accountHolderType: Personal
                  accountType: Checking
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerResponseDto'
              example:
                customerId: e0bfe4be-c02a-4ded-bbdf-07a8bf8544c8
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/customers/{customerId}:
    get:
      tags:
        - Customers
      summary: Retrieves a customer by ID
      operationId: flute-v2-get-customers-customerId
      description: >
        <a id="flute-v2-get-customers-customerId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/customers/{{customerId}}</span>


        This endpoint retrieves a customer by ID.


        <span class="api-seealso">See Also:</span><br>

        To create a new customer, see `POST /v2/customers`.<br>

        To list customers, see `GET /v2/customers`.<br>

        To update a customer, see `PATCH /v2/customers/{customerId}`.<br>

        To delete a customer, see `DELETE /v2/customers/{customerId}`.
      parameters:
        - name: customerId
          in: path
          x-method: path
          required: true
          description: |
            Specifies a customer's identifier.
          schema:
            type: string
            format: uuid
            example: c4b210e9-be39-4ebc-8195-0c422de87f90
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerResponseDto'
              example:
                customerId: 61e5435f-7cec-4a7b-8523-64358cac7fac
                externalId: CUST-EXT-12345
                firstName: John
                lastName: Doe
                companyName: Acme Corp
                email: john.doe@acme.com
                mobilePhoneNumber: '+14125553845'
                hasSmsConsent: true
                shouldUseBillingAsShippingAddress: true
                billingAddress:
                  city: New York
                  countryCode: US
                  addressLine1: 123 Main Street
                  addressLine2: Suite 100
                  postalCode: '10001'
                  stateCode: NY
                shippingAddress: null
                lastTransactionDate: '2026-05-29T22:04:31.792Z'
                transactionsCount: 25
                transactionsVolume: 12500
                lastTransactionAmount: 150
                numberOfSubscriptions: 2
                cards:
                  - cardMask: '************1111'
                    expirationMonth: 12
                    expirationYear: 2026
                    cardTokenType: null
                    cardType: Visa
                    creditDebitType: Credit
                    paymentMethodId: e5348db9-85cf-4d9d-a27c-88013f8944be
                    paymentName: My Visa Card
                    isDefault: true
                  - cardMask: '************5555'
                    expirationMonth: 6
                    expirationYear: 2033
                    cardTokenType: null
                    cardType: MasterCard
                    creditDebitType: Debit
                    paymentMethodId: 911e5ed6-95db-4ceb-8c49-5dc997ce0b3d
                    paymentName: Personal MasterCard
                    isDefault: false
                achAccounts:
                  - accountNumber: '****6789'
                    routingNumber: '021000021'
                    accountType: Checking
                    accountHolderType: Personal
                    taxId: '***-**-6789'
                    paymentMethodId: a7402e6f-7b52-4884-9214-b68dcd7b80bf
                    paymentName: Business Checking
                    isDefault: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
        - Customers
      summary: Updates a customer's information
      operationId: flute-v2-patch-customers-customerId
      description: >
        <a id="flute-v2-patch-customers-customerId"></a>

        <span class="api-endpoint">PATCH {{<a
        href="#urlbases">baseURL</a>}}/v2/customers/{{customerId}}</span>


        This endpoint updates a customer's information.


        This endpoint is a partial update.

        Send only the fields needed to be changed.

        * An omitted field is left unchanged.

        * A field marked with `null` clears a field.


        Nested structures are also affected.


        <span class="api-seealso">See Also:</span><br>

        To create a new customer, see `POST /v2/customers`.<br>

        To list customers, see `GET /v2/customers`.<br>

        To retrieve a customer by ID, see `GET /v2/customers/{customerId}`.<br>

        To delete a customer, see `DELETE /v2/customers/{customerId}`.
      parameters:
        - name: customerId
          in: path
          x-method: path
          required: true
          description: |
            Specifies a customer's identifier.
          schema:
            type: string
            format: uuid
            example: c4b210e9-be39-4ebc-8195-0c422de87f90
      requestBody:
        description: The customer fields to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequestDto'
            example:
              firstName: Jane
              lastName: Smith
              companyName: Tech Solutions Inc
              email: jane.smith@techsolutions.com
              mobilePhoneNumber: '+15559876543'
              hasSmsConsent: false
              shouldUseBillingAsShippingAddress: false
              billingAddress:
                city: Los Angeles
                countryCode: US
                addressLine1: 456 Oak Avenue
                addressLine2: Floor 5
                postalCode: '90001'
                stateCode: CA
              shippingAddress:
                city: San Francisco
                countryCode: US
                addressLine1: 789 Pine Road
                addressLine2: null
                postalCode: '94102'
                stateCode: CA
      responses:
        '200':
          description: OK. The customer information was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
        - Customers
      summary: Deletes a customer
      operationId: flute-v2-delete-customers-customerId
      description: >
        <a id="flute-v2-delete-customers-customerId"></a>

        <span class="api-endpoint">DELETE {{<a
        href="#urlbases">baseURL</a>}}/v2/customers/{{customerId}}</span>


        This endpoint deletes a customer.


        <span class="api-seealso">See Also:</span><br>

        To create a new customer, see `POST /v2/customers`.<br>

        To list customers, see `GET /v2/customers`.<br>

        To retrieve a customer by ID, see `GET /v2/customers/{customerId}`.<br>

        To update a customer, see `PATCH /v2/customers/{customerId}`.
      parameters:
        - name: customerId
          in: path
          x-method: path
          required: true
          description: |
            Specifies the identifier of the customer to delete.
          schema:
            type: string
            format: uuid
            example: c4b210e9-be39-4ebc-8195-0c422de87f90
      responses:
        '200':
          description: OK. The customer was successfully deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/api-keys:
    get:
      tags:
        - Merchant API Keys
      summary: Lists merchant API keys
      operationId: flute-v2-get-api-keys
      description: >
        <a id="flute-v2-get-api-keys"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/api-keys</span>


        This endpoint lists merchant's API keys.


        <span class="api-seealso">See Also:</span><br>

        To create an API key, see `POST /v2/api-keys`.<br>

        To revoke an API key, see `DELETE /v2/api-keys/{{clientId}}`.
      parameters:
        - name: merchantId
          in: query
          description: >
            Specifies a merchant identifier to filter API keys.


            If the API token used for this endpoint was created from a partner
            API key, all merchant API keys associated from that partner will be
            searched.

            A value for `merchantId` may be used to limit the search to a
            specific merchant.


            If the API token used for this endpoint was created from a merchant
            API key, only API keys for that merchant will be returned.

            A value for `merchantId` may be omitted.
          schema:
            type: string
            format: uuid
            x-method: QUERY
            example: 8db2ff47-b143-4adb-ab58-a4a017504db2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeysResponseDto'
              example:
                apiKeys:
                  - clientId: 80bb3659-9a62-470b-92f5-d8c5d16d47b0
                    merchantId: 886e77d0-e86f-4710-92f6-e2b84b29bd9e
                    apiKeyName: Production API Key
                  - clientId: 7f191870-7de7-495a-9037-fabeefbdd089
                    merchantId: 9040dc53-46e3-4816-b3b3-c83d885c2b07
                    apiKeyName: Staging API Key
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
        - Merchant API Keys
      summary: Creates a merchant API key
      operationId: flute-v2-post-api-keys
      description: >
        <a id="flute-v2-post-api-keys"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/api-keys</span>


        Creates a new API key for a merchant.


        If the API token used for this endpoint was created from a partner API
        key, an API key can be created only for merchants associated with that
        partner.


        If the API token used for this endpoint was created from a merchant API
        key, an API key can be created only for that merchant.


        <span class="api-seealso">See Also:</span><br>

        To list available keys, see `GET /v2/api-keys`.<br>

        To revoke an API key, see `DELETE /v2/api-keys/{{clientId}}`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequestDto'
            example:
              merchantId: 0b627967-4204-4d7a-aa13-e6eb0d58f543
              apiKeyName: Production API Key
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponseDto'
              example:
                clientId: 97e7c13c-059c-4734-b017-2a20847a79d0
                clientSecret: 1f80d6e1-9901-48b6-a862-6cfad1612e99
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/api-keys/{clientId}:
    delete:
      tags:
        - Merchant API Keys
      summary: Revokes a merchant API key
      operationId: flute-v2-delete-api-keys-clientId
      description: >
        <a id="flute-v2-delete-api-keys-clientId"></a>

        <span class="api-endpoint" style="color: black; font-size: 14pt;
        font-weight: 450;">DELETE {{<a
        href="#urlbases">baseURL</a>}}/v2/api-keys/{{clientId}}</span>


        This endpoint revokes a merchant API key.


        <span class="api-seealso">See Also:</span><br>

        To list available keys, see `GET /v2/api-keys`.<br>

        To create an API key, see `POST /v2/api-keys`.
      parameters:
        - name: clientId
          in: path
          x-method: path
          description: >
            Specifies the API key's client identifier.


            If the API token used for this endpoint was created from a partner
            API key, an API key can be revoked only for merchants associated
            with that partner.


            If the API token used for this endpoint was created from a merchant
            API key, an API key can be revoked only for that merchant.
          required: true
          schema:
            type: string
            format: uuid
            example: aa98aa89-07ae-4a23-b441-48725f0386e6
      responses:
        '200':
          description: OK. The API key was successfully revoked.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-methods:
    get:
      tags:
        - Payment Methods
      summary: Lists a customer's payment methods
      operationId: flute-v2-get-payment-methods
      description: >
        <a id="flute-v2-get-payment-methods"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods</span>


        This endpoint lists a customer's payment methods for the merchant.


        <span class="api-seealso">See Also:</span><br>

        To add a new card payment method, see `POST
        /v2/payment-methods/cards`.<br>

        To add a new ACH payment method, see `POST /v2/payment-methods/ach`.<br>

        To retrieve a payment method, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To update a payment method, see `PATCH
        /v2/payment-methods/{{paymentMethodId}}`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/asc'
        - $ref: '#/components/parameters/sortby'
        - name: search
          in: query
          description: >
            Specifies the search string.


            This performs a case-insensitive search that matches exactly or
            partially.
          schema:
            type: string
            x-method: query
            example: Conners Electric
        - $ref: '#/components/parameters/createdFrom'
        - $ref: '#/components/parameters/createdTo'
        - name: customerId
          in: query
          description: >
            Filters by a customer's identifier.


            If null or omitted, the response includes orphan payment methods
            with customer-linked payment methods.
          schema:
            type: string
            format: uuid
            example: c4b210e9-be39-4ebc-8195-0c422de87f90
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfPaymentMethodResponseDto'
              example:
                items:
                  - paymentMethodId: 8a06469f-25da-4763-990d-11a4bbc74ecb
                    customerId: 4f7d41f8-1d45-4cb7-a1e8-788fea6a2b11
                    name: My Visa Card
                    type: Card
                    isDefault: true
                    createdOn: '2026-01-15T10:30:56.264Z'
                    card:
                      cardMask: '************1111'
                      expirationMonth: 12
                      expirationYear: 2033
                      cardTokenType: Local
                    ach: null
                  - paymentMethodId: 7ada26ab-308a-4d2b-abb2-f0f69711ea38
                    customerId: null
                    name: Acme Bus Savings
                    type: ElectronicCheck
                    isDefault: false
                    createdOn: '2026-02-01T09:00:56.264Z'
                    card: null
                    ach:
                      accountNumber: '****6789'
                      routingNumber: '021000021'
                      accountType: Checking
                      accountHolderType: Business
                      taxId: '***-**-6789'
                      companyName: Acme Corp Inc
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 150
                  totalPages: 8
                  hasMore: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-methods/cards:
    post:
      tags:
        - Payment Methods
      summary: Creates a card payment method
      operationId: flute-v2-post-payment-methods-cards
      description: >
        <a id="flute-v2-post-payment-methods-cards"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/cards</span>


        This endpoint creates a card (credit or debit) payment method.


        The card information is tokenized and stored, assigning it to the
        merchant.


        Tokenization means the sensitive payment data, such as the raw card
        number or bank account number, is submitted to Flute once.

        After that, Flute assigns a non-sensitive value to paymentMethodId. 

        The paymentMethodId is then used as the payment reference for later
        transactions.


        <span class="api-seealso">See Also:</span><br>

        To add a new ACH payment method, see `POST /v2/payment-methods/ach`.<br>

        To list payment methods, see `GET /v2/payment-methods`.<br>

        To retrieve a payment method, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To update a payment method, see `PATCH
        /v2/payment-methods/{{paymentMethodId}}`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardPaymentMethodRequestDto'
            example:
              customerId: 098290e9-49cd-4613-a885-db61a29f80f7
              paymentName: My Visa Card
              cardNumber: '4111111111111111'
              securityCode: '123'
              expirationMonth: 12
              expirationYear: 2030
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentMethodResponseDto'
              example:
                paymentMethodId: 83eed29d-849d-4aff-8ff7-02783bfe97d5
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-methods/ach:
    post:
      tags:
        - Payment Methods
      summary: Creates an ACH payment method
      operationId: flute-v2-post-payment-methods-ach
      description: >
        <a id="flute-v2-post-payment-methods-ach"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/ach</span>


        This endpoint creates an ACH (automated clearing house) payment method.


        The ACH account information is tokenized and stored, assigning it to the
        merchant.


        Tokenization means the sensitive payment data, such as the ACH account
        number or bank account number, is submitted to Flute once.

        After that, Flute assigns a non-sensitive value to paymentMethodId.

        The paymentMethodId is then used as the payment reference for later
        transactions.


        For Business ACH where the orphan caller will not supply ContactInfo on
        transactions, include `companyName` so the legal entity name is
        available at transaction time.


        <span class="api-seealso">See Also:</span><br>

        To add a new card payment method, see `POST
        /v2/payment-methods/cards`.<br>

        To list payment methods, see `GET /v2/payment-methods`.<br>

        To retrieve a payment method by ID, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAchPaymentMethodRequestDto'
            example:
              customerId: 3ad6a05a-48b4-4c77-9601-fdad2963b92b
              name: Business Checking
              companyName: Acme Corp Inc
              routingNumber: '021000021'
              accountNumber: '1234567890'
              taxId: 12-3456789
              accountHolderType: Business
              accountType: Checking
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentMethodResponseDto'
              example:
                paymentMethodId: 83eed29d-849d-4aff-8ff7-02783bfe97d5
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-methods/{paymentMethodId}:
    get:
      tags:
        - Payment Methods
      summary: Retrieves a payment method by ID
      operationId: flute-v2-get-payment-methods-paymentMethodId
      description: >
        <a id="flute-v2-get-payment-methods-paymentMethodId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/{{paymentMethodId}}</span>


        This endpoint retrieves a payment method by ID.


        <span class="api-seealso">See Also:</span><br>

        To add a new card payment method, see `POST
        /v2/payment-methods/cards`.<br>

        To add a new ACH payment method, see `POST /v2/payment-methods/ach`.<br>

        To retrieve a payment method by ID, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.
      parameters:
        - name: paymentMethodId
          in: path
          x-method: path
          description: The payment method identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: c24e0199-7e8e-49b0-ac09-16aae93af4be
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodResponseDto'
              examples:
                Card payment method (customer-linked, default):
                  description: >
                    Indicates a card payment method linked to a customer and
                    marked as the customer's default.
                  value:
                    paymentMethodId: 6e22f0f3-f3ed-407c-a46f-ec9cffde5d5b
                    customerId: 588f57a5-fe6a-4844-851e-e98914e81980
                    name: My Visa Card
                    type: Card
                    isDefault: true
                    createdOn: '2026-01-15T10:30:00.000Z'
                    card:
                      cardMask: '************1111'
                      expirationMonth: 12
                      expirationYear: 2033
                      cardTokenType: Local
                    ach: null
                ACH payment method (orphan, business):
                  description: >
                    Indicates an ACH payment method that belongs to the merchant
                    directly (no linked customer).

                    Business ACH carries the legal entity name in `companyName`.

                    `IsDefault` is always `false` for orphans.
                  value:
                    paymentMethodId: 6bbfbe3e-04dd-41cd-82bf-1466e0159007
                    customerId: null
                    name: Acme Bus Savings
                    type: ElectronicCheck
                    isDefault: false
                    createdOn: 2026-02-01T09:00:000Z
                    card: null
                    ach:
                      accountNumber: '****6789'
                      routingNumber: '021000021'
                      accountType: Checking
                      accountHolderType: Business
                      taxId: '***-**-6789'
                      companyName: Acme Corp Inc
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
        - Payment Methods
      summary: Updates a payment method
      operationId: flute-v2-patch-payment-methods-paymentMethodId
      description: >
        <a id="flute-v2-patch-payment-methods-paymentMethodId"></a>

        <span class="api-endpoint">PATCH {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/{{paymentMethodId}}</span>


        This endpoint updates a payment method.


        Renames the payment method.


        This endpoint is a partial update.

        Send only the fields needed to be changed.

        * An omitted field is left unchanged.

        * A field marked with `null` clears a field.


        Nested structures are also affected.


        The payment method is identified by `paymentMethodId` within the
        merchant.

        The operation works the same for orphan and customer-linked payment
        methods.


        <span class="api-seealso">See Also:</span><br>

        To list payment methods, see `GET /v2/payment-methods`.<br>

        To retrieve a payment method by ID, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To delete a payment method, see `DELETE
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To set a payment method as the default, see `POST
        /v2/payment-methods/{{paymentMethodId}}/set-default`.
      parameters:
        - name: paymentMethodId
          in: path
          x-method: path
          description: |
            Specifies the payment method identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: c857af4c-ced9-4b79-b39b-13c077711d7e
      requestBody:
        description: |
          The payment method fields to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentMethodRequestDto'
            example:
              paymentName: My Updated Card
      responses:
        '200':
          description: OK. The payment method was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
        - Payment Methods
      summary: Deletes a payment method
      operationId: flute-v2-delete-payment-methods-paymentMethodId
      description: >
        <a id="flute-v2-delete-payment-methods-paymentMethodId"></a>

        <span class="api-endpoint">DELETE {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/{{paymentMethodId}}</span>


        This endpoint deletes a payment method.


        <span class="api-seealso">See Also:</span><br>

        To list payment methods, see `GET /v2/payment-methods`.<br>

        To retrieve a payment method by ID, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To update a payment method, see `PATCH
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To set a payment method as the default, see `POST
        /v2/payment-methods/{{paymentMethodId}}/set-default`.
      parameters:
        - name: paymentMethodId
          in: path
          x-method: path
          description: |
            Specifies the payment method identifier to delete.
          required: true
          schema:
            type: string
            format: uuid
            example: a6ae6a86-6831-4422-a646-d9442a1b0ec8
      responses:
        '200':
          description: OK. The payment method was successfully deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-methods/{paymentMethodId}/set-default:
    post:
      tags:
        - Payment Methods
      summary: Sets a default payment method
      operationId: flute-v2-post-payment-methods-paymentMethodId-set-default
      description: >
        <a id="flute-v2-post-payment-methods-paymentMethodId-set-default"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-methods/{{paymentMethodId}}/set-default</span>


        This endpoint set the specified payment method as the default payment
        method.


        Only one payment method can be set as the default.

        When set, the previous default payment method, if there was one, is
        changed to not being the default.


        Only customer-linked payment methods can be made default; CustomerId is
        therefore required.

        Orphan PMs (no linked customer) have no concept of default and cannot
        reach this endpoint without a customer scope.


        <span class="api-seealso">See Also:</span><br>

        To list payment methods, see `GET /v2/payment-methods`.<br>

        To retrieve a payment method by ID, see `GET
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To update a payment method, see `PATCH
        /v2/payment-methods/{{paymentMethodId}}`.<br>

        To delete a payment method, see `DELETE
        /v2/payment-methods/{{paymentMethodId}}`.
      parameters:
        - name: paymentMethodId
          in: path
          x-method: path
          description: Specifies the payment method identifier to set as default.
          required: true
          schema:
            type: string
            format: uuid
            example: 1a4f15c9-f39c-49f1-aad5-04e0e72804ad
        - name: customerId
          in: query
          required: true
          description: |
            Specifies a customer's identifier.
          schema:
            type: string
            format: uuid
            example: c4b210e9-be39-4ebc-8195-0c422de87f90
      responses:
        '200':
          description: OK. The payment method was set as the default.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-sessions:
    post:
      tags:
        - Payment Sessions
      summary: Creates a new payment session
      operationId: flute-v2-post-payment-sessions
      description: >
        <a id="flute-v2-post-payment-sessions"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-sessions</span>


        This endpoint creates a new payment session.


        <span class="api-seealso">See Also:</span><br>

        To retrieve a payment session by Id, see `GET
        /v2/payment-sessions/{{paymentSessionId}}`.<br>

        To cancel a payment session, see `POST
        /v2/payment-sessions/{{paymentSessionId}}/cancel`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentSessionRequestDto'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentSessionResponseDto'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-sessions/{paymentSessionId}:
    get:
      tags:
        - Payment Sessions
      summary: Retrieves payment session details by ID
      operationId: flute-v2-get-payment-sessions-paymentSessionId
      description: >
        <a id="flute-v2-get-payment-sessions-paymentSessionId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-sessions/{{paymentSessionId}}</span>


        This endpoint retrieves the details of the specified payment session by
        ID.


        <span class="api-seealso">See Also:</span><br>

        To create a new payment session, see `POST /v2/payment-sessions`.<br>

        To cancel a payment session, see `POST
        /v2/payment-sessions/{{paymentSessionId}}/cancel`.
      parameters:
        - name: paymentSessionId
          in: path
          x-method: path
          description: |
            Specifies the payment session identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: edf7b36a-1b2c-4d3e-4f5a-6b7c8d9e0f36
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentSessionResponseDto'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v2/payment-sessions/{paymentSessionId}/cancel:
    post:
      tags:
        - Payment Sessions
      summary: Cancels a payment session
      operationId: flute-v2-post-payment-sessions-paymentSessionId-cancel
      description: >
        <a id="flute-v2-post-payment-sessions-paymentSessionId-cancel"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/payment-sessions/{{paymentSessionId}}/cancel</span>


        This endpoint cancels a payment session.


        A payment session can only be canceled successfully if:

        * The payment session must belong to the requesting merchant.

        The `merchantId` from the API token must match the session's merchant.

        It returns 403 Forbidden if it does not.   

        * The session is in `Created` status.

        Any other status, such as `Completed`, `Failed`, or `Cancelled`, fails
        with the validation error: "Payment Session can be canceled only in
        Created status".


        <span class="api-seealso">See Also:</span><br>

        To create a new payment session, see `POST /v2/payment-sessions`.<br>

        To retrieve a payment session by Id, see `GET
        /v2/payment-sessions/{{paymentSessionId}}`.
      parameters:
        - name: paymentSessionId
          in: path
          x-method: path
          description: |
            Specifies the payment session identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: edf7b36a-1b2c-4d3e-4f5a-6b7c8d9e0f36
      responses:
        '200':
          description: OK. The payment session was successfully cancelled.
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /v2/ping:
    get:
      tags:
        - Ping
      summary: Pings an endpoint for health status
      operationId: flute-v2-get-ping
      description: >
        <a id="flute-v2-get-ping"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/ping</span>


        This endpoint pings an endpoint to validate the API token is active and
        valid.


        Returns 200 OK if the service is reachable.

        There is no response body.
      responses:
        '200':
          description: OK. The service is available.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/pos/transactions:
    get:
      tags:
        - POS Transactions
      summary: Lists POS transactions
      operationId: flute-v2-get-pos-transactions
      description: >
        <a id="flute-v2-get-pos-transactions"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/pos/transactions</span>


        This endpoint lists POS transactions.


        Each item in the response contains a reduced transaction object.

        Fields are limited to the most relevant transaction information.

        This is often sufficient for rendering transaction lists, dashboards,
        and reconciliation views.

        Situations requiring full detail context, such as for decline details,
        AVS response, or transaction events, are 

        available with `GET /v2/pos/transactions/{{posTransactionId}}`.


        <span class="api-seealso">See Also:</span><br>

        To retrieve a POS transaction by ID, see `GET
        /v2/pos/transactions/{posTransactionId}`.<br>

        To create a new POS transaction, see `POST /v2/pos/transactions`.<br>

        To cancel a POS transaction, see `POST
        /v2/pos/transactions/{posTransactionId}/cancel`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/sortOrder'
        - $ref: '#/components/parameters/sortby'
        - name: terminalId
          in: query
          description: |
            Specifies to filter by terminal identifier.
          schema:
            type: string
            format: uuid
            x-method: query
            example: 57dbdbc6-fef4-44b8-816a-4372c063f1ec
          example: 57dbdbc6-fef4-44b8-816a-4372c063f1ec
        - name: fromDate
          in: query
          description: >
            Specifies returning items on or after this date (in an ISO 8601
            date-time format) to filter by,.


            If only `fromDate` is specified, the search returns all available
            items from the `fromDate` value to the present.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an exclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2025-01-27T12:05:54.322Z'
        - name: toDate
          in: query
          description: >
            Specifies returning items on or to this date (in an ISO 8601
            date-time format) to filter by,.


            If only `toDate` is specified, the search returns all available
            items up to the `toDate` value.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an explicit range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2026-02-27T12:05:54.322Z'
        - name: posTransactionStatus
          in: query
          schema:
            enum:
              - InProgress
              - Completed
              - Cancelled
              - Failed
            type: string
            description: >
              Specifies the POS transaction status to filter by,


              Valid values are:


              | Value       |
              Description                                                |

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

              | Cancelled   | The POS transaction was canceled before it
              completed.      |

              | Completed   | The POS transaction finished processing
              successfully.      |

              | Failed      | The POS transaction did not complete because of an
              error.  |

              | InProgress  | The POS transaction is still being
              processed.              |
          example: Completed
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfListPosTransactionsResponseDto'
              example:
                items:
                  - posTransactionId: cdf3b72b-6bb5-4707-8963-1f73456323d8
                    createdOn: '2026-06-03T21:54:31.884Z'
                    terminalId: bcd3a843-9f21-4a71-a019-e1b336b65496
                    status: Completed
                    transactionId: 1782bc6c-efb0-416d-8e62-627401707177
                    processedAmount: 135.5
                    currencyCode: USD
                    targetTransactionId: null
                    transactionType: Sale
                  - posTransactionId: 18090b35-0758-4a5b-81ae-927d4496cd53
                    createdOn: '2026-06-03T21:59:31.884Z'
                    terminalId: bff9c356-fb17-4ed8-89ad-d980c92e391e
                    status: TransactionProcessing
                    transactionId: null
                    processedAmount: 135.5
                    currencyCode: USD
                    targetTransactionId: null
                    transactionType: Authorization
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 150
                  totalPages: 8
                  hasMore: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
        - POS Transactions
      summary: Creates a POS transaction
      operationId: flute-v2-post-pos-transactions
      description: >
        <a id="flute-v2-post-pos-transactions"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/pos/transactions</span>


        This endpoint creates a new card present payment transaction on a
        semi-Integrated terminal.

        A semi-integrated terminal is one that is connected to a POS system,
        typically through a network or cable.


        When called, the gateway connects to the specified terminal and starts
        the payment flow.

        This includes screens for:

        * Card type selection

        * Tip entry

        * Card reading, such as for tap, insert, or swipe, depending on the
        merchant's settings.


        The terminal flow is asynchronous.

        Use `GET /pos/transactions/{{posTransactionId}}` until
        `posTransactionStatus` reaches a terminal state, such as `Completed`,
        `Failed`, or `Cancelled`.

        When it is `Completed`, check the linked transaction for the payment
        outcome, which may have been declined.


        <span class="api-seealso">See Also:</span><br>

        To list POS transactions, see `GET /v2/pos/transactions`.<br>

        To retrieve a POS transaction by ID, see `GET
        /v2/pos/transactions/{posTransactionId}`.<br>

        To cancel a POS transaction, see `POST
        /v2/pos/transactions/{posTransactionId}/cancel`.
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePosTransactionRequestDto'
            example:
              posDeviceId: POS-DEV-014
              referenceId: REF-POS-20260812-001
              captureMethod: Manual
              baseAmount: 42.75
              pricingType: Cash
              currencyCode: USD
              paymentProcessorId: 7b1e4a2c-9f3d-4e8b-b2a1-5c6d7e8f9a0b
              customerId: 3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e
              terminalId: f4e3d2c1-b0a9-4f8e-9d7c-6b5a4938271f
              waitForAcceptanceByTerminal: false
              readingMethod: KeyedEntry
              requestPaymentMethodStorageConsent: true
              extraAmounts:
                tipAmount: null
                tipRate: 15
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePosTransactionResponseDto'
              example:
                posTransactionId: 6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b
                createdOn: '2026-08-12T09:15:22.100Z'
                modifiedOn: '2026-08-12T09:16:05.400Z'
                merchantId: 746ba4dd-b1b4-47c3-a034-72aa55007e86
                customerId: 9f2b1c4d-7e3a-4f8b-90c1-2d3e4f5a6b7c
                terminalId: 83a2baf4-2c5a-4326-acd9-65f26e47ac1e
                paymentProcessorId: 2e8c8c3e-e034-42db-8169-1b7999a49cd0
                posDeviceId: POS-DEV-014
                referenceId: REF-POS-20260812-001
                posTransactionStatus: Completed
                captureMethod: Manual
                transactionId: cdb041da-90c6-4e03-82cf-3fa1178680ee
                baseAmount: 42.75
                currencyCode: USD
                extraAmounts:
                  tipAmount: null
                  tipRate: 15
                processedAmount: 49.16
                linkedTransaction:
                  transactionId: cdb041da-90c6-4e03-82cf-3fa1178680ee
                  transactionDateTime: '2026-08-12T09:16:04.900Z'
                  transactionStatus: Captured
                  transactionType: Sale
                  cardTokenType: Network
                  paymentMethodType: Card
                  referenceId: REF-POS-20260812-001
                  originalTransactionId: null
                  processedAmount: 49.16
                  refundDetails:
                    refundedAmount: 0
                    availableRefundAmount: 49.16
                  currencyCode: USD
                  pricingType: Card
                  paymentProcessorId: 2e8c8c3e-e034-42db-8169-1b7999a49cd0
                  customerId: 9f2b1c4d-7e3a-4f8b-90c1-2d3e4f5a6b7c
                  merchantId: 746ba4dd-b1b4-47c3-a034-72aa55007e86
                  batchId: null
                  amountBreakdown:
                    baseAmount: 42.75
                    tipAmount: null
                    tipRate: 15
                    surchargeAmount: null
                    surchargeRate: null
                    discountAmount: null
                    discountRate: null
                  cardDetails:
                    paymentMethodId: 39a95e35-6d50-45ec-884b-c2417edf005d
                    maskedCardNumber: '************1111'
                    cardBrand: Visa
                    cardType: Credit
                    cardProcessedAsType: Credit
                    cardDataSource: EMV
                    cardholderVerificationMethod: PIN
                    emvTags:
                      ac: 9F2604A1B2C3D4E5F6
                      tvr: '0000008001'
                      tsi: '6800'
                      aid: A0000000031010
                      applicationLabel: VISA CREDIT
                      rawTags: null
                  achDetails: null
                  processorDetails:
                    mid: '932129304958123'
                    tid: '6095275263'
                    authCode: VTLMC1
                    rrn: 59d5df1aa58d4de3969175eeece571c1
                  declineDetails: null
                  addressVerificationServiceResponse:
                    action: Allow
                    responseCode: 'Y'
                    description: Address and ZIP match
                  transactionEvents:
                    - type: Sale
                      status: Approved
                      amount: 49.16
                      dateTime: '2026-08-12T09:16:04.900Z'
                      originalTransactionId: null
                      declineDetails: null
                  source:
                    sourceType: Terminal
                    sourceId: 83a2baf4-2c5a-4326-acd9-65f26e47ac1e
                    sourceName: Front Counter Terminal 3
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/pos/transactions/{posTransactionId}:
    get:
      tags:
        - POS Transactions
      summary: Retrieves a POS transaction by ID
      operationId: flute-v2-get-pos-transactions-posTransactionId
      description: >
        <a id="flute-v2-get-pos-transactions-posTransactionId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/pos/transactions/{{posTransactionId}}</span>


        This endpoint retrieves a POS transaction by ID.


        <span class="api-seealso">See Also:</span><br>

        To list POS transactions, see `GET /v2/pos/transactions`.<br>

        To create a new POS transaction, see `POST /v2/pos/transactions`.<br>

        To cancel a POS transaction, see `POST
        /v2/pos/transactions/{posTransactionId}/cancel`.
      parameters:
        - name: posTransactionId
          in: path
          x-method: path
          description: |
            Specifies the POS transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 361c152f-72fa-4654-84f1-a664584ce3de
        - name: waitForTransactionProcessing
          in: query
          description: >
            Specifies the long poll for the transaction to reach a completed
            status before responding.


            This could be success, failure, or cancellation.


            If `true`, the response is held until completion or timeout.<br>

            If `false`, the response returns immediately.

            The endpoint `GET /pos/transactions/{{posTransactionId}}` must be
            called for updates.
          schema:
            type: boolean
            x-method: query
            default: false
          example: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPosTransactionResponseDto'
              example:
                posTransactionId: 51efbd85-3e2b-459c-87d0-34f4c046a21f
                createdOn: '2026-06-03T21:59:31.891Z'
                merchantId: 746ba4dd-b1b4-47c3-a034-72aa55007e86
                terminalId: a84af02c-6de3-40ac-abda-0d8db96dec7b
                paymentProcessorId: 451e4f53-9d81-48d8-a7c4-8167595adffa
                posDeviceId: POS-DEVICE-001
                referenceId: REF-12345
                status: Completed
                transactionId: 7a62ba78-c4e2-4317-bc4e-c90a9d169107
                processedAmount: 135.5
                currencyCode: USD
                targetTransactionId: null
                transactionType: Sale
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/pos/transactions/{posTransactionId}/cancel:
    post:
      tags:
        - POS Transactions
      summary: Cancels a POS transaction by ID
      operationId: flute-v2-post-pos-transactions-posTransactionId-cancel
      description: >
        <a id="flute-v2-post-pos-transactions-posTransactionId-cancel"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/pos/transactions/{{posTransactionId}}/cancel</span>


        This endpoint cancels a POS transaction by ID.


        This sends a cancellation signal to the gateway to abort an in-progress
        POS transaction.


        It can only be called while the transaction is in a cancellable state.

        This is typically before the customer has presented their card on the
        terminal.


        A cancellation request is not guaranteed if the terminal has already
        begun processing the payment.

        In that case the `posTransactionStatus` reflects the actual terminal
        outcome.


        <span class="api-seealso">See Also:</span><br>

        To list POS transactions, see `GET /v2/pos/transactions`.<br>

        To retrieve a POS transaction by ID, see `GET
        /v2/pos/transactions/{posTransactionId}`.<br>

        To create a POS transaction reversal, see `POST
        /v2/pos/transactions/reversal`.<br>

        To print a receipt for a POS transaction, see `POST
        /v2/pos/transactions/{posTransactionId}/print-receipt`.
      parameters:
        - name: posTransactionId
          in: path
          x-method: path
          description: |
            Specifies the POS transaction identifier to cancel.
          required: true
          schema:
            type: string
            format: uuid
            example: bc037464-05f0-4cc6-b1d9-66d44636a1a1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePosTransactionResponseDto'
              example:
                posTransactionId: 2eca4f2c-0cc2-4355-aa0b-a3e65368591d
                status: TransactionProcessing
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/pos/transactions/{posTransactionId}/print-receipt:
    post:
      tags:
        - POS Transactions
      summary: Prints a POS transaction receipt
      operationId: flute-v2-post-pos-transactions-posTransactionId-print-receipt
      description: >
        <a
        id="flute-v2-post-pos-transactions-posTransactionId-print-receipt"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/pos/transactions/{{posTransactionId}}/print-receipt</span>


        This endpoint prints a POS transaction receipt.


        The terminal must be in semi-integrated mode and available (online and
        ready).

        A semi-integrated terminal is one that is connected to a POS system,
        typically through a network or cable.


        <span class="api-seealso">See Also:</span><br>

        To list POS transactions, see `GET /v2/pos/transactions`.<br>

        To retrieve a POS transaction by ID, see `GET
        /v2/pos/transactions/{posTransactionId}`.<br>

        To create a new POS transaction, see `POST /v2/pos/transactions`.<br>

        To cancel a POS transaction, see `POST
        /v2/pos/transactions/{posTransactionId}/cancel`.
      parameters:
        - name: posTransactionId
          in: path
          x-method: path
          description: >
            Specifies the POS transaction identifier whose receipt should be
            printed.
          required: true
          schema:
            type: string
            format: uuid
            example: 6b486f55-e922-4a34-90c0-c78c75055eb1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintTransactionReceiptRequestDto'
            example:
              terminalId: 5ddd62a7-bb28-41b1-bc50-179e98dce577
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/settings/payment-config:
    get:
      tags:
        - Settings
      summary: Lists payments configuration
      operationId: flute-v2-get-settings-payment-config
      description: >
        <a id="flute-v2-get-settings-payment-config"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/settings/payment-config</span>


        This endpoint lists the payment configuration settings.


        <span class="api-seealso">See Also:</span><br>

        To retrieve the contact information, see `GET
        /v2/settings/contact-information`.<br>

        To retrieve the transaction autofill settings, see `GET
        /v2/settings/transaction-autofill`.<br>

        To update the transaction autofill settings, see `PATCH
        /v2/settings/transaction-autofill`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentConfigurationResponseDto'
              example:
                zeroCostProcessingOption: None
                defaultTipsOptions:
                  - 10
                  - 15
                  - 20
                defaultSurchargeRate: 1.5
                defaultCashDiscountRate: 2
                defaultDualPricingRate: 1.8
                availableCurrencies:
                  - USD
                availableCardTypes:
                  - Visa
                  - MasterCard
                  - AmericanExpress
                  - Discover
                availableTransactionTypes:
                  - Sale
                  - Capture
                  - Refund
                  - Void
                isTipsEnabled: true
                availablePaymentProcessors:
                  - paymentProcessorId: ecd7c87b-7165-4a67-a067-24c9c9e1bbf4
                    processorName: TSYS
                    isDefault: true
                    type: Tsys
                    settlementBatchTimeSlots:
                      - hours: 2
                        minutes: 10
                        timezoneName: America/New_York
                addressVerificationServiceOptions:
                  isEnabled: true
                  profile: Strict
                isCustomerCardSavingByTerminalEnabled: true
                companyName: Test Company
                mccCode: '5411'
                mccCodeDescription: Grocery Stores, Supermarkets
                currency: USD
                maxTransactionAmount: 10000
                ttpIosTerminalProfileId: ios-terminal-profile-id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/settings/contact-information:
    get:
      tags:
        - Settings
      summary: Lists contact information
      operationId: flute-v2-get-settings-contact-information
      description: >
        <a id="flute-v2-get-settings-contact-information"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/settings/contact-information</span>


        This endpoint lists contact information for the merchant.


        <span class="api-seealso">See Also:</span><br>

        To retrieve the payment configuration, see `GET
        /v2/settings/payment-config`.<br>

        To retrieve the transaction autofill settings, see `GET
        /v2/settings/transaction-autofill`.<br>

        To update the transaction autofill settings, see `PATCH
        /v2/settings/transaction-autofill`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactInfoResponseDto'
              example:
                contactInfos:
                  - contactInfoId: 8d638f27-1a16-4f1b-92fe-0ea16d4a6461
                    addressName: Main Office
                    email: contact@company.com
                    mobilePhoneNumber: '+12125550100'
                    isMainAddress: true
                    isDefaultAddress: true
                    city: New York
                    countryCode: US
                    addressLine1: 123 Main St
                    addressLine2: Suite 100
                    postalCode: '10001'
                    stateCode: NY
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/settings/transaction-autofill:
    get:
      tags:
        - Settings
      summary: Lists levels 2 and 3 autofill settings
      operationId: flute-v2-get-settings-transaction-autofill
      description: >
        <a id="flute-v2-get-settings-transaction-autofill"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/settings/transaction-autofill</span>


        This endpoint lists levels 2 and 3 autofill settings.


        The additional levels 2 and 3 information must be included in
        transactions requiring that level.

        This information can be pre-configured at the merchant settings level.

        This allows merchants to automatically include the information instead
        of manually entering each time.

        This automatic inclusion is called autofill.


        With autofill, a merchant configures defaults once.

        To set the defaults and values, see `PATCH
        /v2/settings/transaction-autofill`.

        Thereafter, Flute automatically appends those values to every
        transaction even if not included in the transaction request.

        For example, a merchant selling the same product, such as a subscription
        service could set the following:

        * taxRate: 8.5 for Level 2

        * product.code: SUB-001, product.unitPrice: 29.99 for Level 3


        Every transaction then automatically includes that data, qualifying for
        lower interchange rates without any extra work per transaction.


        <span class="api-seealso">See Also:</span><br>

        To retrieve the payment configuration, see `GET
        /v2/settings/payment-config`.<br>

        To retrieve the contact information, see `GET
        /v2/settings/contact-information`.<br>

        To update the transaction autofill settings, see `PATCH
        /v2/settings/transaction-autofill`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionAutofillResponseDto'
              example:
                level2Settings:
                  taxRate: 8.5
                level3Settings:
                  product:
                    productName: Office Supplies
                    code: OFF001
                    unitPrice: 25
                    measurementUnit: pcs
                    quantity: 10
                    discountPercentage: 5
                    description: Standard office supplies
                  shippingChargeRate: 5
                  dutyChargeRate: 2.5
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
        - Settings
      summary: Updates levels 2 and 3 settings
      operationId: flute-v2-patch-settings-transaction-autofill
      description: >
        <a id="flute-v2-patch-settings-transaction-autofill"></a>

        <span class="api-endpoint">PATCH {{<a
        href="#urlbases">baseURL</a>}}/v2/settings/transaction-autofill</span>


        This endpoint updates or sets levels 2 and 3 autofill settings.


        This endpoint is a partial update.

        Send only the fields needed to be changed.

        * An omitted field is left unchanged.

        * A field marked with `null` clears a field.


        Nested structures are also affected.


        The additional levels 2 and 3 information must be included in
        transactions requiring that level.

        This information can be pre-configured at the merchant settings level.

        This allows merchants to automatically include the information instead
        of manually entering each time.

        This automatic inclusion is called autofill.


        With autofill, a merchant configures defaults once.

        For the existing set of defaults and values, see `GET
        /v2/settings/transaction-autofill`.

        Thereafter, Flute automatically appends those values to every
        transaction even if not included in the transaction request.

        For example, a merchant selling the same product, such as a subscription
        service could set the following:

        * taxRate: 8.5 for Level 2

        * product.code: SUB-001, product.unitPrice: 29.99 for Level 3


        Every transaction then automatically includes that data, qualifying for
        lower interchange rates without any extra work per transaction.


        <span class="api-seealso">See Also:</span><br>

        To retrieve the payment configuration, see `GET
        /v2/settings/payment-config`.<br>

        To retrieve the contact information, see `GET
        /v2/settings/contact-information`.<br>

        To retrieve the transaction autofill settings, see `GET
        /v2/settings/transaction-autofill`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTransactionAutofillRequestDto'
            example:
              level2Settings:
                taxRate: 8.5
              level3Settings:
                product:
                  productName: Office Supplies
                  code: OFF001
                  unitPrice: 25
                  measurementUnit: pcs
                  quantity: 10
                  discountPercentage: 5
                  description: Standard office supplies
                shippingChargeRate: 5
                dutyChargeRate: 2.5
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/settlements/batches:
    get:
      tags:
        - Settlements
      summary: Lists transaction batch settlements
      operationId: flute-v2-get-settlements-batches
      description: >
        <a id="flute-v2-get-settlements-batches"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/settlements/batches</span>


        This endpoint lists transaction batch settlements.


        <span class="api-seealso">See Also:</span><br>

        To settle transactions, see `POST /v2/settlements/settle`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/asc'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/dateFrom'
        - $ref: '#/components/parameters/dateTo'
        - name: batchIds
          in: query
          description: |
            Filters by with an array of specified batch identifiers.
          schema:
            type: array
            x-method: query
            items:
              type: string
              format: uuid
              example: fe08c47b-2c3d-4e4f-5a6b-7c8d9e0f1a47
            example:
              - fe08c47b-2c3d-4e4f-5a6b-7c8d9e0f1a47
              - 0f19d58c-3d4e-4f5a-6b7c-8d9e0f1a2b58
        - name: paymentProcessorIds
          in: query
          description: |
            Filters by an array of specified payment processor identifiers.
          schema:
            type: array
            x-method: query
            items:
              type: string
              format: uuid
              example: 1a2ae69d-4e5f-4a6b-7c8d-9e0f1a2b3c69
        - $ref: '#/components/parameters/SettlementBatchStatus'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfListBatchesResponseDto'
              example:
                items:
                  - batchId: 21c75430-a316-456f-9126-365760dca33a
                    paymentProcessorId: 1092a854-1708-4e0c-8d86-1b8fe34b37ec
                    paymentProcessorName: TSYS
                    externalBatchId: BATCH-001
                    batchDateTime: '2026-03-23T12:00:56.264Z'
                    transactionCount: 15
                    netAmount: 1250
                    salesAmount: 1300
                    refundsAmount: 50
                    status: Settled
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 150
                  totalPages: 8
                  hasMore: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/settlements/settle:
    post:
      tags:
        - Settlements
      summary: Settles transactions
      operationId: flute-v2-post-settlements-settle
      description: >
        <a id="flute-v2-post-settlements-settle"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/settlements/settle</span>


        This endpoint explicitly settles batched transactions.


        <span class="api-seealso">See Also:</span><br>

        To list settlement batches, see `GET /v2/settlements/batches`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettleTransactionsRequestDto'
            example:
              paymentProcessorId: 70f07e54-ad9d-417c-9ab4-d4acc5302aa8
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleTransactionsResponseDto'
              example:
                status: Approve
                message: Batch closed successfully
                processorResponseCode: '00'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/terminals:
    get:
      tags:
        - Terminals
      summary: Lists merchant's terminals
      operationId: flute-v2-get-terminals
      description: >
        <a id="flute-v2-get-terminals"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/terminals</span>


        This endpoint lists all available terminals for the authenticated
        merchant.


        Only active terminals are returned.

        Terminals in the following conditions are excluded:

        * Pre-activation states, such as pending shipment or in transit

        * Deactivated terminals


        <span class="api-seealso">See Also:</span><br>

        To retrieve a terminal's status by ID, see `GET
        /v2/terminals/{terminalId}/status`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - name: sortBy
          in: query
          description: |
            Specifies a field name to sort the results by.

            If null or omitted, results come back newest first.

            Valid values are:<br>
            terminalManufacturer<br>
            merchantCompanyName
          schema:
            type: string
            example: terminalManufacturer
        - $ref: '#/components/parameters/sortOrder'
        - name: terminalStatus
          in: query
          description: |
            Indicates the availability status of the terminal.

            Valid values are:

            | Status  | Meaning                                            |
            |---------|----------------------------------------------------|
            | Busy    | The terminal is processing a transaction.          |
            | Ready   | The terminal is available for a new transaction.   |
            | Offline | The terminal is unavailable for a new transaction. |
          schema:
            enum:
              - Ready
              - Busy
              - Offline
            type: string
          example: Ready
        - name: terminalMode
          in: query
          description: >
            Indicates the operating mode of the terminal.


            Valid values are:

            | Mode            | Meaning |

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

            | Standalone      | The terminal operates independently of any POS
            system.<br><br>The amount is entered directly on the terminal itself
            (no electronic connection to a cash register/POS software), and it
            runs the transaction on its own. |

            | SemiIntegrated  | The terminal is connected to a POS system,
            typically through a network or cable.<br><br>The POS sends the
            transaction amount to the terminal electronically, rather than
            requiring manual entry. However, the POS never touches card or
            payment data directly. The terminal handles all sensitive payment
            processing itself. This architecture is commonly used to reduce PCI
            compliance scope on the POS side. |
          schema:
            enum:
              - Standalone
              - SemiIntegrated
            type: string
            example: SemiIntegrated
        - name: connectionStatus
          in: query
          description: >
            Indicates the line status of the terminal.


            Valid values are:


            | Status  | Meaning |

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

            | Online  | The terminal is currently connected and
            reachable.<br><br>It has active network or internet connectivity. It
            is able to process transactions and communicate with the backend in
            real time. |

            | Offline | The terminal is disconnected or unreachable.<br><br>It
            may be powered off, have lost its network connection, or otherwise
            be unable to communicate. As a result, it cannot process
            transactions, or can only do so in a stored or deferred mode
            depending on the platform. |
          schema:
            enum:
              - Online
              - Offline
            type: string
          example: Online
        - name: serialNumber
          in: query
          description: |
            Filters by the serial number.

            This is an exact match search.
          schema:
            type: string
            example: SN100001
          example: SN100001
        - name: search
          in: query
          description: >
            Filters using a search string.


            This performs a case-insensitive search that matches exactly or
            partially.


            The field does not have to be specified.

            If the results are to be sorted, use the `sortBy` field to specify
            the sort field.


            The search includes the following fields:<br>

            serialNumber<br>

            terminalModel<br>

            terminalManufacturer<br>

            terminalId<br>

            merchantCompanyName


            Example:<br>

            Peppared Street Cafe<br>

            Street<br>

            ree
          schema:
            type: string
            example: Peppared Street Cafe
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfListTerminalsResponseDto'
              example:
                items:
                  - terminalId: 0b61c6b6-e633-4c3d-91ae-9810ff42ccdc
                    merchantId: fffcecc3-2e15-4e93-8144-5353785cec3b
                    merchantCompanyName: Peppared Street Cafe
                    serialNumber: SN100001
                    terminalManufacturer: Sunmi
                    terminalModel: SunmiP2
                    terminalMode: SemiIntegrated
                    terminalStatus: Ready
                    connectionStatus: Online
                    lastSeenOn: '2026-08-11T18:44:45.638Z'
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 3
                  totalPages: 1
                  hasMore: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/terminals/{terminalId}/status:
    get:
      tags:
        - Terminals
      summary: Retrieves a merchant's terminal POS status by ID
      operationId: flute-v2-get-terminals-terminalId-status
      description: >
        <a id="flute-v2-get-terminals-terminalId-status"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/terminals/{{terminalId}}/status</span>


        This endpoint Retrieves a merchant's terminal POS status by ID.


        information includes the connection and network state, hardware info and
        software version. 

        This provides the latest available information about a terminal, updated
        in near real-time.

        Use this endpoint before initiating a POS transaction.

        It verifies the terminal is reachable and ready to accept a payment.


        Before creating a POS transaction, check the `terminalStatus`.

        It must be `Ready` and not `Busy` or `Offline`. 

        The fields `batteryLevel` and p`rinterStatus` can be used to warn
        merchants of low battery or printer issues before starting a
        transaction.


        Depending on the terminal's internet connectivity and operational
        status, the response may include limited terminal data.
      parameters:
        - name: terminalId
          in: path
          x-method: path
          description: |
            Specifies the terminal identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: ad307589-17b9-4f8a-9489-6b4c48f0c40d
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTerminalStatusResponseDto'
              example:
                terminalId: 03a88aa0-14ef-4334-8b7a-13356fec8202
                merchantId: fffcecc3-2e15-4e93-8144-5353785cec3b
                terminalStatus: Ready
                lastSeenOn: '2026-08-11T18:44:45.6451072Z'
                debitPinKey: Injected
                terminalAppVersion: 1.0.0
                connectionStatus: Online
                connectionType: WiFi
                wifiConnectionStrength: 85
                mobileConnectionStrength: 0
                batteryLevel: 90
                printerStatus: Normal
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions:
    get:
      tags:
        - Transactions
      summary: Lists transactions
      operationId: flute-v2-get-transactions
      description: >
        <a id="flute-v2-get-transactions"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions</span>


        This endpoint lists transactions.


        Items returned here present a limited amount of details.

        These are intended to be a brief summary of the transactions.

        For complete details of a specific transaction, see `GET
        /v2/transactions/{transactionId}`.


        <span class="api-seealso">See Also:</span><br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - name: sortBy
          in: query
          description: |
            Specifies a field name to sort the results by.

            If null or omitted, results come back newest first.

            Valid values are:<br>
            cardTokenType<br>
            customerCompanyName<br>
            customerName<br>
            maskedCardNumber<br>
            merchantCompanyName<br>
            paymentMethodType<br>
            processedAmount<br>
            transactionDateTime<br>
            transactionId<br>
            transactionStatus
          schema:
            type: string
            example: transactionDateTime
        - $ref: '#/components/parameters/sortOrder'
        - name: fromDate
          in: query
          description: >
            Specifies a filter to return items created on or after this date (in
            an ISO 8601 date-time format).


            If only `fromDate` is specified, the search returns all available
            items from the `fromDate` value to the present.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an exclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2025-01-27T12:05:54.322Z'
        - name: toDate
          in: query
          description: >
            Specifies a filter to return items created on or to this date (in an
            ISO 8601 date-time format).


            If only `toDate` is specified, the search returns all available
            items up to the `toDate` value.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an explicit range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2026-02-27T12:05:54.322Z'
        - name: sourceType
          in: query
          description: >
            Specifies a filter by the transaction source.


            Valid values are:

            | Value         |
            Description                                                        |

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

            | ApiKey        | An external application created the transaction
            using an API key.  |

            | Invoice       | A billed invoice created the
            transaction.                          |

            | MobileApp     | A mobile application created the
            transaction.                      |

            | Portal        | A staff member created the transaction through the
            web portal.     |

            | QuickPayment  | A one-time payment link created the
            transaction.                   |

            | Subscription  | A recurring subscription created the
            transaction.                  |

            | TapToPay      | A mobile device using tap to pay created the
            transaction.          |

            | Terminal      | A physical payment terminal created the
            transaction.               |

            | WebComponent  | An embedded web component created the
            transaction.                 |
          schema:
            enum:
              - ApiKey
              - Invoice
              - MobileApp
              - Portal
              - QuickPayment
              - Subscription
              - TapToPay
              - Terminal
              - WebComponent
            type: string
          example: ApiKey
        - name: sourceId
          in: query
          description: |
            Specifies a filter by the source identifier.
          schema:
            type: string
            format: uuid
            example: 81915d04-1f2a-4b3c-4d5e-6f7a8b9c0d36
        - name: batchId
          in: query
          description: |
            Specifies a filter by the settlement batch identifier.

            Use `null` to return transactions not yet settled into a batch.<br>
            Omit this value to not filter by batch identifier.
          schema:
            type: string
            example: 0b7aa955-6b52-4dcb-b0d8-7c3d82f27b62
          example: 0b7aa955-6b52-4dcb-b0d8-7c3d82f27b62
        - $ref: '#/components/parameters/AggregatedTransactionParameterStatus'
        - name: paymentMethodType
          in: query
          description: |
            Specifies a filter by the payment method type.

            Valid values are:

            | Type  | Description                                |
            |-------|--------------------------------------------|
            | ACH   | Payment made through an ACH bank transfer. |
            | Card  | Payment made with a credit or debit card.  |
            | Cash  | Payment made with physical currency.       |
          schema:
            type: string
            example: Cash
          example: Card
        - name: customerId
          in: query
          description: |
            Specifies a filter by the customer identifier.
          schema:
            type: string
            format: uuid
            x-method: query
            example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c
        - name: merchantId
          in: query
          description: |
            Specifies a filter by the merchant identifier.
          schema:
            type: string
            format: uuid
            x-method: query
            example: 92a26e15-2a3b-4c4d-5e6f-7a8b9c0d1e47
        - name: minAmount
          in: query
          description: >
            Specifies a filter by the minimum transaction amount to include in
            the results.


            Only transactions with this amount or more are returned.


            If only `minAmount` is specified, the search returns all
            transactions with at least this amount.

            The fields `minAmount` and `maxAmount` may be used together to
            create an exclusive range. 

            We recommend creating an inclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: number
            format: double
            multipleOf: 0.01
            x-method: query
            example: 500
        - name: maxAmount
          in: query
          description: >
            Specifies a filter by the maximum transaction amount to include in
            the results.


            Only transactions with this amount or less are returned.


            If only `maxAmount` is specified, the search returns all
            transactions with no more than this amount.

            The fields `minAmount` and `maxAmount` may be used together to
            create an exclusive range. 

            We recommend creating an inclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: number
            format: double
            multipleOf: 0.01
            x-method: query
            example: 500
        - name: referenceId
          in: query
          description: >
            Specifies a filter by the reference identifier provided by the
            merchant.


            A referenceId is a duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.
          schema:
            type: string
            nullable: true
            minLength: 0
            maxLength: 36
            x-method: query
            example: REF-EXT-12345
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                items:
                  - transactionId: 3a2257af-e059-4718-b1c6-ee60bd83816e
                    transactionDateTime: '2025-06-15T14:30:56.264Z'
                    status: Captured
                    paymentMethodType: Card
                    referenceId: REF-001
                    processedAmount: 115.5
                    currencyCode: USD
                    amountBreakdown:
                      baseAmount: 99.99
                      tipAmount: 10
                      tipRate: 0
                      surchargeAmount: 5.5
                      discountAmount: 0
                      discountARate: 0
                    addressVerificationServiceResponse:
                      action: Allow
                      responseCode: 'Y'
                      description: Address and ZIP code match
                    cardDetails:
                      maskedCardNumber: 411111******1111
                      cardType: Visa
                      creditDebitType: Credit
                    achDetails: null
                    transactionEvents:
                      - type: Sale
                        status: Approved
                        amount: 115.5
                        dateTime: '2025-06-15T14:30:56.264Z'
                        processorResponse:
                          processorName: TSYS
                          responseCode: '00'
                          responseMessage: APPROVAL
                          responseDefinition: Approved
                  - transactionId: 53c558a4-b01a-4a43-a8c1-1c9820250958
                    transactionDateTime: '2025-06-15T10:00:56.264Z'
                    status: Captured
                    paymentMethodType: ACH
                    referenceId: REF-002
                    processedAmount: 200
                    currencyCode: USD
                    amountBreakdown:
                      baseAmount: 200
                      tipAmount: 0
                      tipRate: 5.5
                      surchargeAmount: 0
                      discountAmount: 0
                      discountRate: 0
                    addressVerificationServiceResponse: null
                    cardDetails: null
                    achDetails:
                      maskedAccountNumber: '****6789'
                      maskedRoutingNumber: '****0001'
                      accountHolderType: Personal
                      accountType: Checking
                      secCode: Web
                    transactionEvents:
                      - type: Sale
                        status: Approved
                        amount: 200
                        dateTime: 2025-06-15T10:00:000Z
                        processorResponse:
                          processorName: ACH
                          responseCode: '1'
                          responseMessage: Approved
                          responseDefinition: null
                pageInfo:
                  pageIndex: 0
                  pageSize: 20
                  totalItems: 150
                  totalPages: 8
                  hasMore: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
        - Transactions
      summary: Creates a transaction
      operationId: flute-v2-post-transactions
      description: >
        <a id="flute-v2-post-transactions"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions</span>


        This endpoint creates a transaction.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.<br>

        To calculate a transaction amount, see `POST
        /v2/transactions/calculate-amount`.`
      requestBody:
        description: Transaction request with payment method and transaction type
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransactionRequestDto'
            examples:
              Card — saved payment method:
                description: >
                  Specifies a charge a with a previously saved card.


                  `billingAddress` and `contactInfo` are optional because the
                  stored payment method already carries that data.
                value:
                  paymentProcessorId: a2f2c2e7-0b23-4682-8f99-ab7707205461
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: REF-CARD-SAVED-001
                  isCustomerInitiatedTransaction: true
                  pricingType: Card
                  extraAmounts: null
                  transactionEnhancedData: null
                  billingAddress: null
                  shippingAddress: null
                  contactInfo: null
                  transactionDetails:
                    cardData:
                      captureMethod: Auto
                      paymentMethodId: e397e367-bc4a-4b69-bd78-32e3e12327c2
                      paymentMethodDetails: null
                    achData: null
                  deviceId: null
                  platform: null
                  appVersion: null
                  sdkVersion: null
              Card — new card:
                description: >
                  Specifies a charge with card details supplied inline.


                  Populating `billingAddress` and `contactInfo` is recommended
                  to improve processor acceptance.
                value:
                  paymentProcessorId: a2f2c2e7-0b23-4682-8f99-ab7707205461
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: REF-CARD-NEW-001
                  isCustomerInitiatedTransaction: true
                  pricingType: Card
                  extraAmounts: null
                  transactionEnhancedData: null
                  billingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 123 Main Street
                    addressLine2: Suite 100
                    postalCode: '10001'
                    stateCode: NY
                  shippingAddress: null
                  contactInfo:
                    firstName: John
                    lastName: Doe
                    companyName: null
                    email: john.doe@example.com
                    mobilePhoneNumber: '+14125553845'
                    hasSmsConsent: true
                  transactionDetails:
                    cardData:
                      captureMethod: Auto
                      paymentMethodId: null
                      paymentMethodDetails:
                        cardNumber: '4111111111111111'
                        securityCode: '123'
                        expirationMonth: 12
                        expirationYear: 2030
                    achData: null
                  deviceId: null
                  platform: null
                  appVersion: null
                  sdkVersion: null
              ACH — saved payment method:
                description: >
                  Specifies a debit with a previously saved ACH account.


                  Populating `billingAddress` and `contactInfo` is recommended
                  to improve processor acceptance.
                value:
                  paymentProcessorId: 8932c37e-9ae0-46ed-8da4-e70eb9458596
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: REF-ACH-SAVED-001
                  isCustomerInitiatedTransaction: true
                  pricingType: null
                  extraAmounts: null
                  transactionEnhancedData: null
                  billingAddress: null
                  shippingAddress: null
                  contactInfo: null
                  transactionDetails:
                    cardData: null
                    achData:
                      paymentMethodId: bc665a1b-4231-4e52-bc43-dc04623165ec
                      paymentMethodDetails: null
                      secCode: Web
                      isSameDayProcessing: false
                      requesterIpAddress: 203.0.113.45
                  deviceId: null
                  platform: null
                  appVersion: null
                  sdkVersion: null
              ACH — new account:
                description: >
                  Specifies a debit for an ACH account with routing or account
                  details supplied inline.


                  Populating `billingAddress` and `contactInfo` is recommended
                  to improve processor acceptance.
                value:
                  paymentProcessorId: 8932c37e-9ae0-46ed-8da4-e70eb9458596
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: REF-ACH-NEW-001
                  isCustomerInitiatedTransaction: true
                  pricingType: null
                  extraAmounts: null
                  transactionEnhancedData: null
                  billingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 123 Main Street
                    addressLine2: Suite 100
                    postalCode: '10001'
                    stateCode: NY
                  shippingAddress: null
                  contactInfo:
                    firstName: John
                    lastName: Doe
                    companyName: Acme Inc
                    email: john.doe@example.com
                    mobilePhoneNumber: '+14125553845'
                    hasSmsConsent: false
                  transactionDetails:
                    cardData: null
                    achData:
                      paymentMethodId: null
                      paymentMethodDetails:
                        routingNumber: '021000021'
                        accountNumber: '1234567890'
                        taxId: 12-3456789
                        accountHolderType: Personal
                        accountType: Checking
                      secCode: PPD
                      isSameDayProcessing: false
                      requesterIpAddress: 203.0.113.45
                  deviceId: null
                  platform: null
                  appVersion: null
                  sdkVersion: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              examples:
                Create transaction response (Authorization):
                  description: >
                    Indicates an approved authorization (pre-auth).


                    Capture the transaction later with `POST
                    /transactions/{{transactionId}}/capture`.
                  value:
                    transactionId: 90d084d6-55b8-4fb8-b658-861534d07f9a
                    transactionStatus: Pending
                    processedAmount: 100
                    currencyCode: USD
                    amountDetails:
                      baseAmount: 100
                      tipAmount: 0
                      tipRate: 0
                      surchargeAmount: 0
                      discountAmount: 0
                      discountRate: 0
                    processorResponse:
                      processorName: TSYS
                      responseCode: '00'
                      responseMessage: Approved
                      responseDefinition: Approved and completed
                    responseDetails: null
                    addressVerificationServiceResponse:
                      action: Allow
                      responseCode: 'Y'
                      description: Address and ZIP match
                    receipt: null
                Create transaction response (Sale):
                  description: Response after approved sale (auth + capture in one step).
                  value:
                    transactionId: 5f6f782f-37af-44e1-bb18-2bc35e411899
                    transactionStatus: Approved
                    processedAmount: 115.5
                    currencyCode: USD
                    amountDetails:
                      baseAmount: 100
                      tipAmount: 15
                      tipRate: 0
                      surchargeAmount: 3
                      discountAmount: 2.5
                      discountRate: 0
                    processorResponse:
                      processorName: TSYS
                      responseCode: '00'
                      responseMessage: Approved
                      responseDefinition: Approved and completed
                    responseDetails: null
                    addressVerificationServiceResponse:
                      action: Allow
                      responseCode: 'Y'
                      description: Address and ZIP match
                    receipt: null
                Create transaction response (ACH):
                  description: >-
                    Response after approved ACH debit transaction. No AVS
                    (address verification service).
                  value:
                    transactionId: c5b0299f-e9f6-498b-90c7-688bffec2e6e
                    transactionStatus: Approved
                    processedAmount: 100
                    currencyCode: USD
                    amountDetails:
                      baseAmount: 100
                      tipAmount: 0
                      tipRate: 0
                      surchargeAmount: 0
                      discountAmount: 0
                      discountRate: 0
                    processorResponse:
                      processorName: ACH
                      responseCode: '1'
                      responseMessage: Approved
                      responseDefinition: Transaction approved
                    responseDetails: null
                    addressVerificationServiceResponse: null
                    receipt: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Retrieves a transaction by ID
      operationId: flute-v2-get-transactions-transactionId
      description: >
        <a id="flute-v2-get-transactions-transactionId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}</span>


        This endpoint retrieves a transaction by ID.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 3c25d7e4-dfe0-4ede-a3f0-fb280cac281c
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTransactionResponseDtoFull'
              examples:
                Card transaction (Completed):
                  description: >
                    A completed card sale transaction with AVS (address
                    verification service) response and amount breakdown.
                  value:
                    transactionId: f184155d-5737-440c-abd4-1b58f0b9119c
                    transactionDateTime: '2025-06-15T14:30:56.264Z'
                    status: Captured
                    paymentMethodType: Card
                    referenceId: REF-001
                    processedAmount: 115.5
                    currencyCode: USD
                    amountBreakdown:
                      baseAmount: 100
                      tipAmount: 10
                      surchargeAmount: 5.5
                      discountAmount: 0
                    addressVerificationServiceResponse:
                      action: Allow
                      responseCode: 'Y'
                      description: Address and postal code match
                    cardDetails:
                      maskedCardNumber: 411111******1111
                      cardType: Visa
                      creditDebitType: Credit
                    achDetails: null
                    transactionEvents:
                      - type: Sale
                        status: Approved
                        amount: 115.5
                        dateTime: '2025-06-15T14:30:56.264Z'
                        processorResponse:
                          processorName: TSYS
                          responseCode: '00'
                          responseMessage: APPROVAL
                          responseDefinition: Approved
                ACH transaction (Completed):
                  description: >
                    A completed ACH debit transaction. No AVS (address
                    verification service) response.
                  value:
                    transactionId: 77838fb3-9701-4f37-8c17-6fa5ab6e2dc1
                    transactionDateTime: '2025-06-15T10:00:56.264Z'
                    status: Captured
                    paymentMethodType: ACH
                    referenceId: REF-002
                    processedAmount: 200
                    currencyCode: USD
                    amountBreakdown:
                      baseAmount: 200
                      tipAmount: 0
                      tipRate: 0
                      surchargeAmount: 0
                      discountAmount: 0
                      discountRate: 0
                    addressVerificationServiceResponse: null
                    cardDetails: null
                    achDetails:
                      maskedAccountNumber: '****6789'
                      maskedRoutingNumber: '****0001'
                      accountHolderType: Personal
                      accountType: Checking
                      secCode: Web
                    transactionEvents:
                      - type: Sale
                        status: Approved
                        amount: 200
                        dateTime: '2025-06-15T10:00:56.264Z'
                        processorResponse:
                          processorName: ACH
                          responseCode: '1'
                          responseMessage: Approved
                          responseDefinition: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/capture:
    post:
      tags:
        - Transactions
      summary: Captures a transaction
      operationId: flute-v2-post-transactions-transactionId-capture
      description: >
        <a id="flute-v2-post-transactions-transactionId-capture"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/capture</span>


        This endpoint captures a transaction.


        This captures a previously authorized transaction and settling it for
        the specified amount. 

        It is used when a transaction was created with `captureMethod` of
        `Manual`.

        This allows merchants to delay settlement until fulfillment is
        confirmed. 

        The `captureAmount` can be less than or equal to the original authorized
        amount to support partial captures.


        If successful, this returns the full transaction object reflecting the
        updated status. 

        A processor declining the transaction returns a 402 error.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 487471b7-0149-44ed-840b-97d920e06829
      requestBody:
        description: >
          Specifies an object defining the transaction.


          If the request body is null or omitted, a full capture is
          included.<br>

          If `baseAmount` is included, a partial capture is made.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureRequestDto'
            example:
              amount: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: 1db9c80e-1265-49b9-b2ef-fbf92acf5d42
                transactionStatus: Approved
                processedAmount: 100
                currencyCode: USD
                amountDetails:
                  baseAmount: 100
                  tipAmount: 0
                  surchargeAmount: 0
                  discountAmount: 0
                processorResponse:
                  processorName: TSYS
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Approved and completed
                responseDetails: null
                addressVerificationServiceResponse: null
                receipt: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/reversal:
    post:
      tags:
        - Transactions
      summary: Reverses a transaction
      operationId: flute-v2-post-transactions-transactionId-reversal
      description: >
        <a id="flute-v2-post-transactions-transactionId-reversal"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/reversal</span>


        This endpoint reverses, or refunds, a transaction.


        Payment method (card vs ACH) is auto-detected.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.<br>

        To create an unreferenced credit, see `POST /v2/transactions/credit`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier to refund.
          required: true
          schema:
            type: string
            format: uuid
            example: d4e39f93-a128-45f4-9b27-140042a5efa5
      requestBody:
        description: Reversal options including optional `Amount` for a partial refund.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReversalRequestDto'
            example:
              amount: 25
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: e54f0127-fee5-47a2-8e06-b73fcf69fbe2
                transactionStatus: Approved
                processedAmount: 25
                currencyCode: USD
                processorResponse:
                  processorName: TSYS
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Approved and completed
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/credit:
    post:
      tags:
        - Transactions
      summary: Credits from a transaction without reference
      operationId: flute-v2-post-transactions-credit
      description: >
        <a id="flute-v2-post-transactions-credit"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/credit</span>


        This endpoint refunds or returns funds without a reference.


        This includes refunding to a credit card or provides an ACH credit.


        Without a reference means the customer does not have the link to the
        original transaction identifier.

        This creates a refund transaction that is not linked to a specific
        previous transaction.

        Instead of refunding a known transaction identifier, the system
        processes a standalone credit back to the cardholder's payment method.


        As a warning, these are considered high-risk transaction types.

        Funds are returned directly from the merchant's account even if the
        original sale was not processed through Flute.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditRequestDto'
            examples:
              Card unreferenced refund:
                description: >
                  Unreferenced card refund using raw card data.

                  Saved payment methods are not supported for unreferenced
                  credits.
                value:
                  paymentProcessorId: 7538ed96-b5ec-488e-94a0-b44ef5e77833
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: ext-ref-123
                  billingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 123 Main Street
                    addressLine2: Suite 100
                    postalCode: '10001'
                    stateCode: NY
                  shippingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 456 Delivery Ave
                    addressLine2: Floor 2
                    postalCode: '10002'
                    stateCode: NY
                  contactInfo:
                    firstName: John
                    lastName: Doe
                    companyName: Acme Inc
                    email: john.doe@example.com
                    mobilePhoneNumber: '+14125553845'
                    hasSmsConsent: false
                  creditDetails:
                    cardData:
                      paymentMethodDetails:
                        cardNumber: '4111111111111111'
                        securityCode: '123'
                        expirationMonth: 12
                        expirationYear: 2033
                    achData: null
              ACH credit:
                description: >
                  ACH credit using new bank-account details (routing/account
                  supplied directly in the request).
                value:
                  paymentProcessorId: e77570bc-981c-4ffd-ac8c-a33e950016b2
                  baseAmount: 100
                  currencyCode: USD
                  referenceId: ext-ref-123
                  billingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 123 Main Street
                    addressLine2: Suite 100
                    postalCode: '10001'
                    stateCode: NY
                  shippingAddress:
                    city: New York
                    countryCode: US
                    addressLine1: 456 Delivery Ave
                    addressLine2: Floor 2
                    postalCode: '10002'
                    stateCode: NY
                  contactInfo:
                    firstName: John
                    lastName: Doe
                    companyName: Acme Inc
                    email: john.doe@example.com
                    mobilePhoneNumber: '+14125553845'
                    hasSmsConsent: false
                  creditDetails:
                    cardData: null
                    achData:
                      paymentMethodId: null
                      paymentMethodDetails:
                        routingNumber: '021000021'
                        accountNumber: '1234567890'
                        taxId: 12-3456789
                        accountHolderType: Personal
                        accountType: Checking
                      secCode: PPD
                      isSameDayProcessing: false
                      requesterIpAddress: 203.0.113.45
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: ca1a4988-7541-4be1-83d5-4111a50b16a3
                transactionStatus: Approved
                processedAmount: 100
                currencyCode: USD
                processorResponse:
                  processorName: TSYS
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Approved and completed
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/tip-adjustment:
    post:
      tags:
        - Transactions
      summary: Adjusts for tips
      operationId: flute-v2-post-transactions-transactionId-tip-adjustment
      description: >
        <a id="flute-v2-post-transactions-transactionId-tip-adjustment"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/tip-adjustment</span>


        This endpoint adjusts, or adds, for tips to transaction.


        This may only be used with card-present transactions.

        Specifically, this is for either:

        * Authorized transaction, that is, a pre-authorized transaction that
        hasn't been captured yet.

        * Captured transactions that have not yet settled or not fully refunded.


        The following is a typical workflow:

        1) For authorization: `POST /v2/transactions`

        1) For the tip adjustment: `POST /v2/transactions/tip-adjustment`

        1) For the capture: `POST
        /v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/capture`.<br>

        The transactionId, the UUID in the path, is returned from `POST
        /v2/transactions`.

        1) For the transaction settlement: `POST /v2/settlements/settle`


        Notes for the workflow:

        * Tip adjustment requires both `merchant.IsTipsEnabled` and
        `merchant.IsTipAdjustmentEnabled`.

        * Tip adjustment is only allowed on credit card transactions
        (`CreditDebitType.Credit`), not debit cards.

        * Settlement closes the entire batch for that processor, not just this
        one transaction.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To calculate a transaction amount, see `POST
        /v2/transactions/calculate-amount`.<br>

        To share a transaction receipt by SMS, see `POST
        /v2/transactions/{transactionId}/share-receipt`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 487471b7-0149-44ed-840b-97d920e06829
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TipAdjustmentRequestDto'
            example:
              tipAmount: 22.75
              tipRate: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: 066706fe-d3c7-4a7c-8671-8ff3cc9e94ec
                transactionStatus: Approved
                processedAmount: 105
                currencyCode: USD
                amountDetails:
                  baseAmount: 100
                  tipAmount: 5
                  surchargeAmount: 0
                  discountAmount: 0
                processorResponse:
                  processorName: TSYS
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Approved and completed
                responseDetails: null
                addressVerificationServiceResponse: null
                receipt: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/hold:
    post:
      tags:
        - Transactions
      summary: Holds an ACH transaction
      operationId: flute-v2-post-transactions-transactionId-ach-hold
      description: >
        <a id="flute-v2-post-transactions-transactionId-ach-hold"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/ach-hold</span>


        This endpoint holds an ACH transaction.


        <span class="api-seealso">See Also:</span><br>

        To release a held ACH transaction, see `POST
        /v2/transactions/{{transactionId}}/ach-release`


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To calculate a transaction amount, see `POST
        /v2/transactions/calculate-amount`.<br>

        To share a transaction receipt by SMS, see `POST
        /v2/transactions/{transactionId}/share-receipt`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 487471b7-0149-44ed-840b-97d920e06829
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: 4b22b7a3-b536-4247-975e-b8c428fc48e6
                type: Hold
                transactionStatus: Approved
                processorResponse:
                  processorName: ACH
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Transaction hold applied successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/release-hold:
    post:
      tags:
        - Transactions
      summary: Releases a held ACH transaction
      operationId: flute-v2-post-transactions-transactionId-ach-release
      description: >
        <a id="flute-v2-post-transactions-transactionId-ach-release"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/ach-release</span>


        This endpoint releases a held ACH transaction.


        <span class="api-seealso">See Also:</span><br>

        To hold an ACH transaction, see `POST /v2/transactions/ach-hold`


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.<br>

        To share a transaction receipt by SMS, see `POST
        /v2/transactions/{transactionId}/share-receipt`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier.
          required: true
          schema:
            type: string
            format: uuid
            example: 487471b7-0149-44ed-840b-97d920e068
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageOfGetTransactionResponseDto'
              example:
                transactionId: db2d3d8b-bd69-44a8-8960-e932fbe61365
                type: UnHold
                transactionStatus: Approved
                processorResponse:
                  processorName: ACH
                  responseCode: '00'
                  responseMessage: Approved
                  responseDefinition: Transaction hold released successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/calculate-amount:
    post:
      tags:
        - Transactions
      summary: Calculates transaction amounts
      operationId: flute-v2-post-transactions-calculate-amount
      description: >
        <a id="flute-v2-post-transactions-calculate-amount"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/calculate-amount</span>


        This endpoint calculates transaction amounts.


        The amounts are based on the merchant's ZCP (zero cost processing) mode.

        This includes dual pricing, cash discounts, or credit card surcharges.

        Applications, such as payment terminals or point of service devices, can
        then display the appropriate amounts.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To share a transaction receipt by SMS, see `POST
        /v2/transactions/{transactionId}/share-receipt`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                baseAmount:
                  type: number
                  format: double
                  multipleOf: 0.01
                  x-method: request
                  description: |
                    Specifies the base transaction amount before adjustments.

                    Examples:<br>
                    125<br>
                    125.5<br>
                    125.50
                  example: 125.5
                currencyCode:
                  $ref: '#/components/schemas/currencyCode'
                pricingType:
                  $ref: '#/components/schemas/PricingType'
                tipAmount:
                  type: number
                  format: double
                  multipleOf: 0.01
                  x-method: request
                  description: >
                    Specifies the absolute tip amount (in USD) to add.


                    <br><span class="note">

                    Care must be taken that a value other than zero can be
                    provided to either `tipAmount` or `tipRate`.

                    A non-zero value cannot be provided to both.

                    </span><br>


                    Example: 10.5 (as $10.5)
                  example: 10.5
                tipRate:
                  type: number
                  format: double
                  x-method: request
                  description: >
                    Specifies the tip rate to apply.


                    Encoded as raw percentage.

                    For example: 18.5 for 18.5%.


                    <br><span class="note">

                    Care must be taken that a value other than zero can be
                    provided to either `tipAmount` or `tipRate`.

                    A non-zero value cannot be provided to both.

                    </span><br>


                    Example: 18.5 (as 18.5%)
                  example: 18.5
                discountAmount:
                  type: number
                  format: double
                  multipleOf: 0.01
                  x-method: response
                  description: >
                    Indicates the absolute amount (in USD) of discount to be
                    applied.


                    If this value is provided, it must be greater than zero.


                    <br><span class="note">

                    Care must be taken that a value other than zero can be
                    provided to either `discountAmount` or `discountRate`.

                    A non-zero value cannot be provided to both.

                    </span><br>


                    Example: 25 (for $25)
                  example: 25
                discountRate:
                  type: number
                  format: double
                  x-method: response
                  description: >
                    Indicates a percentage of a discount to be applied.


                    If this value is provided, it must be greater than zero.


                    <br><span class="note">

                    Care must be taken that a value other than zero can be
                    provided to either `discountAmount` or `discountRate`.

                    A non-zero value cannot be provided to both.

                    </span><br>


                    Example: 5.5 (for 5.5%)
                  example: 5.5
                surchargeRate:
                  type: number
                  format: double
                  x-method: request
                  description: |
                    Specifies the credit Card surcharge rate override.

                    Example: 2.5 (for 2.5%)
                  example: 2.5
            example:
              baseAmount: 100
              currencyCode: USD
              pricingType: Card
              discountAmount: 0
              discountRate: 5
              surchargeRate: 2.5
              tipAmount: 15
              tipRate: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateAmountResponseDto'
              example:
                currencyCode: USD
                zeroCostProcessingOption: Surcharge
                pricingType: Card
                cash:
                  baseAmount: 100
                  discountAmount: 15
                  discountRate: 0
                  surchargeAmount: 0
                  surchargeRate: 0
                  tipAmount: 15
                  tipRate: 0
                  totalAmount: 110
                creditCard:
                  baseAmount: 100
                  discountAmount: 15
                  discountRate: 0
                  surchargeAmount: 3.5
                  surchargeRate: 0
                  tipAmount: 15
                  tipRate: 0
                  totalAmount: 113.5
                debitCard:
                  baseAmount: 100
                  discountAmount: 5
                  discountRate: 0
                  surchargeAmount: 0
                  surchargeRate: 0
                  tipAmount: 15
                  tipRate: 0
                  totalAmount: 110
                ach:
                  baseAmount: 100
                  discountAmount: 5
                  discountRate: 0
                  surchargeAmount: 0
                  surchargeRate: 0
                  tipAmount: 15
                  tipRate: 0
                  totalAmount: 110
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/transactions/{transactionId}/share-receipt:
    post:
      tags:
        - Transactions
      summary: Sends a transaction receipt by SMS
      operationId: flute-v2-post-transactions-transactionId-share-receipt
      description: >
        <a id="flute-v2-post-transactions-transactionId-share-receipt"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/transactions/{{transactionId}}/share-receipt</span>


        This endpoint shares a transaction receipt by SMS.


        The following is a typical workflow:

        1) For authorization: `POST /v2/transactions`

        1) For sharing the receipt:
        `/v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/share-receipt`.<br>

        The transactionId, the UUID in the path, is returned from `POST
        /v2/transactions`.

        1) A successful response is 200 OK with no response body.


        Notes for the workflow:

        * The `hasCustomerConsent` is required and must be `true`.

        The endpoint will reject the request if the customer has not explicitly
        consented to receive an SMS.

        * The `mobileNumber` does not have to match the one on the original
        transaction.

        A receipt can be sent to any phone number the customer provides at time
        of receipt.


        <span class="api-seealso">See Also:</span><br>

        To list transactions, see `GET /v2/transactions`.<br>

        To retrieve a transaction by ID, see `GET
        /v2/transactions/{transactionId}`.<br>

        To create a new transaction, see `POST /v2/transactions`.<br>

        To capture a transaction, see `POST
        /v2/transactions/{transactionId}/capture`.<br>

        To reverse a transaction, see `POST
        /v2/transactions/{transactionId}/reversal`.
      parameters:
        - name: transactionId
          in: path
          x-method: path
          description: |
            Specifies the transaction identifier to send a receipt for.
          required: true
          schema:
            type: string
            format: uuid
            example: e6d064c0-b2a5-4cb3-bc57-8135123ed791
      requestBody:
        description: Specifies the recipient mobile number for the SMS receipt.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendReceiptRequestDto'
            example:
              mobilePhoneNumber: '+15551234567'
              hasCustomerConsent: true
      responses:
        '200':
          description: OK. The receipt was successfully shared.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/endpoints:
    get:
      tags:
        - Webhooks
      summary: Lists webhook endpoints
      operationId: flute-v2-get-webhooks-endpoints
      description: >
        <a id="flute-v2-get-webhooks-endpoints"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints</span>


        This endpoint lists all webhook endpoints.


        The endpoints are for both active and inactive webhooks.


        <span class="api-seealso">See Also:</span><br>

        To create a webhook, see `POST /v2/webhooks/endpoints`.<br>

        To retrieve a specified webhook, see `GET
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/sortOrder'
        - $ref: '#/components/parameters/sortby'
        - name: fromDate
          in: query
          description: >
            Filters returning items on or after this date (in an ISO 8601
            date-time format) to filter by,.


            If only `fromDate` is specified, the search returns all available
            items from the `fromDate` value to the present.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an exclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2025-01-27T12:05:54.322Z'
        - name: toDate
          in: query
          description: >
            Filters returning items on or to this date (in an ISO 8601 date-time
            format) to filter by,.


            If only `toDate` is specified, the search returns all available
            items up to the `toDate` value.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an explicit range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2026-02-27T12:05:54.322Z'
        - name: endpointStatus
          in: query
          description: >
            Filters by the endpoint status.


            Valid values are:

            | Value     | Description                                      |

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

            | Active    | The webhook endpoint is enabled and available for
            use.       |

            | Inactive  | The webhook endpoint is disabled and not available for
            use.<br><br>It still exists but will not send event notifications.
            It may be re-activated. In contrast, a deleted webhook has been
            removed entirely and cannot be re-activated. A new webhook must be
            created. |
          schema:
            enum:
              - Active
              - Inactive
            type: string
            example: Active
        - name: search
          in: query
          description: |
            Filters using a search string.

            This is a partial, case-insensitive text search.

            The following fields are searched:<br>
            endpointName<br>
            endpointUrl
          schema:
            type: string
            x-method: query
            example: Peppared Street Cafe
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookEndpointsIsvResponseDto'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
        - Webhooks
      summary: Creates a webhook endpoint
      operationId: flute-v2-post-webhooks-endpoints
      description: >
        <a id="flute-v2-post-webhooks-endpoints"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints</span>


        This endpoint creates a new webhook endpoint.


        New endpoints default to `Active` on creation.

        Only `Active` endpoints are eligible for real event dispatch.


        <span class="api-seealso">See Also:</span><br>

        To list all of available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To retrieve a specified webhook, see `GET
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To update a webhook, see `PATCH
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To delete a webhook, see `DELETE /v2/webhooks/endpoints/{{endpointId}}`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - endpointName
                - endpointUrl
                - eventTypes
              properties:
                endpointName:
                  type: string
                  maxLength: 255
                  description: |
                    Specifies the display name for the webhook.

                    This is a free-formed name that is convenient to recognize.

                    Example: Peppared Street Cafe's Reconciliation
                  example: Peppared Street Cafe's Reconciliation
                endpointUrl:
                  type: string
                  maxLength: 2048
                  x-method: request
                  description: >
                    Specifies the HTTPS callback URL that receives webhook
                    events.


                    Example: https://example.com/webhooks/pepparedstreetcafe
                  example: https://example.com/webhooks/pepparedstreetcafe
                eventTypes:
                  $ref: '#/components/schemas/WebhookEventType'
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookEndpointIsvResponseDto'
              example:
                endpointId: 1e3fd30d-5fc2-4a69-9ea6-d0dcf05ab5ce
                endpointName: Peppared Street Cafe's Reconciliation
                endpointUrl: https://example.com/webhooks/pepparedstreetcafe
                endpointStatus: Active
                hmacSecret: >-
                  7b3e9a1f4c8d2056e1a9b7c3f5d80426a9c1e3b5d7f9024680ace13579bdf024
                eventTypes:
                  - transaction.card.captured
                  - transaction.card.refunded
                  - settlement.batch.completed
                createdOn: '2026-05-05T14:30:00Z'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/endpoints/{endpointId}:
    get:
      tags:
        - Webhooks
      summary: Retrieves a webhook endpoint by ID
      operationId: flute-v2-get-webhooks-endpoints-endpointId
      description: >
        <a id="flute-v2-get-webhooks-endpoints-endpointId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints/{{endpointId}}</span>


        This endpoint retrieves a webhook endpoint by ID.


        <span class="api-seealso">See Also:</span><br>

        To list all available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To update a webhook, see `PATCH
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To test a webhook, see `POST
        /v2/webhooks/endpoints/{{endpointId}}/ping`.
      parameters:
        - name: endpointId
          in: path
          required: true
          description: |
            <br>Specifies the webhook identifier to retrieve.
          schema:
            type: string
            format: uuid
            required: true
            example: 0dab4e68-8d18-42ce-93ba-77b0e8dbafdc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWebhookEndpointIsvResponseDto'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
        - Webhooks
      summary: Updates a webhook endpoint
      operationId: flute-v2-patch-webhooks-endpoints-endpointId
      description: >
        <a id="flute-v2-patch-webhooks-endpoints-endpointId"></a>

        <span class="api-endpoint">PATCH {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints/{{endpointId}}</span>


        This endpoint updates a webhook endpoint.


        <span class="api-seealso">See Also:</span><br>

        To list all available  webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To retrieve a specified webhook, see `GET
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To delete a webhook, see <a
        href="#flute-v2-api-keys-{{clientId}}">`DELETE
        /v2/webhooks/endpoints/{{endpointId}}`</a>.


        <span style="font-size:8pt;">
          [ <a href="#patch_v2_webhooks_endpoints_endpointId_request_body">Query parameters</a> ]
          [ <a href="#patch_v2_webhooks_endpoints_endpointId_response_body">Response fields</a> ]
        </span>
      parameters:
        - name: endpointId
          in: path
          required: true
          description: |
            <br>Specifies the webhook identifier to retrieve.
          schema:
            type: string
            format: uuid
            required: true
            example: 76804cf3-4a5b-4c6d-7e8f-9a0b1c2d3e69
      requestBody:
        description: |
          <a id="patch_v2_webhooks_endpoints_endpointId_request_body"></a>

          This endpoint is a partial update.
          Send only the fields needed to be changed.
          * An omitted field is left unchanged.
          * A field marked with `null` clears a field.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updatewebhookendpointisvrequestdto'
            example:
              endpointName: Peppared Street Cafe's Reconciliation
              endpointUrl: https://example.com/webhooks/pepparedstreetcafe
              endpointStatus: Active
              eventTypes:
                - transaction.card.captured
                - transaction.card.refunded
                - settlement.batch.completed
      responses:
        '200':
          description: OK <a id="patch_v2_webhooks_endpoints_endpointId_response_body"></a>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWebhookEndpointIsvResponseDto'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
        - Webhooks
      summary: Deletes a webhook endpoint
      operationId: flute-v2-delete-webhooks-endpoints-endpointId
      description: >
        <a id="flute-v2-delete-webhooks-endpoints-endpointId"></a>

        <span class="api-endpoint">DELETE {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints/{{endpointId}}</span>


        This endpoint deletes a webhook endpoint.


        All outstanding pending and scheduled retries for this specified webhook
        are cancelled.

        References in log files are not erased.


        <span class="api-seealso">See Also:</span><br>

        To create a webhook, see `POST /v2/webhooks/endpoints`.<br>

        To update a webhook, see `PATCH
        /v2/webhooks/endpoints/{{endpointId}}`.<br>

        To test a webhook, see `POST /v2/webhooks/endpoints/{{endpointId}}/ping`
      parameters:
        - name: endpointId
          in: path
          required: true
          description: |
            Specifies the webhook identifier to delete.
          schema:
            type: string
            format: uuid
            required: true
            example: e8570526-3b2c-4776-ad1c-1303ccb5bc2d
      responses:
        '200':
          description: OK. The webhook was successfully deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/endpoints/{endpointId}/ping:
    post:
      tags:
        - Webhooks
      summary: Pings a webhook endpoint
      operationId: flute-v2-post-webhooks-endpoints-endpointId-ping
      description: >
        <a id="flute-v2-post-webhooks-endpoints-endpointId-ping"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/endpoints/{{endpointId}}/ping</span>


        This endpoint validates connectivity to the registered endpoint URL.
      parameters:
        - name: endpointId
          in: path
          x-method: path
          description: |
            Specifies the webhook endpoint identifier to ping.
          required: true
          schema:
            type: string
            format: uuid
          example: c94e10ae-378e-4124-9b35-ecdfb9085a62
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pingwebhookisvresponsedto'
              example:
                isDelivered: true
                endpointHTTPResponseCode: 200
                roundTripDurationMs: 142
                errorMessage: null
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/event-types:
    get:
      tags:
        - Webhooks
      summary: Lists webhook event types
      operationId: flute-v2-get-webhooks-event-types
      description: >
        <a id="flute-v2-get-webhooks-event-types"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/event-types</span>


        This endpoint lists available webhook event types.


        The list of available webhook event types are provided by Flute.

        These are the only events types available to be selected from.

        Operating system or other company's events cannot be used.


        Each webhook must include at least one.

        Multiple events types may be included in a specific webhook but
        duplicates are not allowed.

        Each webhook is independent from other webhooks.

        The same events type may be included in different webhooks.


        The set of events types do not have to relate to each other.

        It is the set of all event types of interest for the client.

        Clients may create multiple webhooks to provide granularity for their
        processes.

        In that case, the set of events types would likely be related for the
        client's intent.


        <span class="api-seealso">See Also:</span><br>

        To create a webhook, see `POST /v2/webhooks/endpoints`.<br>

        To update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookEndpointsIsvResponseDto'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/delivery-logs:
    get:
      tags:
        - Webhooks
      summary: Lists webhook delivery logs
      operationId: flute-v2-get-webhooks-delivery-logs
      description: >
        <a id="flute-v2-get-webhooks-delivery-logs"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/delivery-logs</span>


        This endpoint lists webhook delivery logs for the merchant account.


        <span class="api-seealso">See Also:</span><br>

        To list all available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To retrieve a specified delivery log, see `GET
        /v2/webhooks/delivery-logs/{{endpointId}}`.<br>

        To export delivery log, see `GET /v2/webhooks/delivery-logs/export`.


        Query parameters may be combined to filter the exported results.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pagesize'
        - $ref: '#/components/parameters/sortby'
        - $ref: '#/components/parameters/sortOrder'
        - name: endpointId
          in: query
          description: |
            <br>Specifies the webhook identifier to filter by.
          schema:
            type: string
            format: uuid
            required: true
            example: 0dab4e68-8d18-42ce-93ba-77b0e8dbafdc
        - $ref: '#/components/parameters/WebhookEventTypeQuery'
        - name: deliveryLogStatus
          in: query
          description: |
            Filters by the delivery success status code.

            | HTTP Status | Meaning |
            |-------------|---------|
            | Success     | Delivery succeeded |
            | Failure     | Delivery failed |
          schema:
            $ref: '#/components/schemas/webhookdeliverylogstatus'
        - name: endpointHTTPResponseCode
          in: query
          description: >
            Filters by the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning |

            |:-----------:|---------|

            | 200 | Delivery succeeded |

            | 400 | Bad request |

            | 401 | Unauthorized |

            | 404 | Endpoint not found |

            | 429 | Rate limited |
          schema:
            type: integer
            format: int32
            example: 401
        - name: fromDate
          in: query
          description: >
            Filters returning webhooks created on or after this date (in an ISO
            8601 date-time format).


            If only `fromDate` is specified, the search returns all available
            items from the `fromDate` value to the present.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an exclusive range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2025-01-27T12:05:54.322Z'
        - name: toDate
          in: query
          description: >
            Filters returning webhooks created on or to this date (in an ISO
            8601 date-time format).


            If only `toDate` is specified, the search returns all available
            items up to the `toDate` value.

            The fields `fromDate` and `toDate` may be used together to create an
            exclusive range.

            We recommend creating an explicit range to avoid a potentially
            excessive number of returns.
          schema:
            type: string
            format: date-time
            example: '2026-02-27T12:05:54.322Z'
        - name: search
          in: query
          description: >
            Filters using a search string.


            This performs a case-insensitive search that matches exactly or
            partially.


            The field does not have to be specified.

            If the results are to be sorted, use the `orderby` field to specify
            the sort field.


            The search includes the following fields:<br>

            EventId (Exact match and complete UUID only. Otherwise, this value
            is ignored.)<br>

            WebhookName<br>

            EndpointUrl
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listwebhookdeliverylogsisvresponsedto'
        '400':
          $ref: '#/components/responses/400'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/delivery-logs/{deliveryLogId}:
    get:
      tags:
        - Webhooks
      summary: Retrieves a delivery log by ID
      operationId: flute-v2-get-webhooks-delivery-logs-deliveryLogId
      description: >
        <a id="flute-v2-get-webhooks-delivery-logs-deliveryLogId"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/delivery-logs/{{deliveryLogId}}</span>


        This endpoint retrieves a delivery log by ID.


        <span class="api-seealso">See Also:</span><br>

        To list all available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To test a webhook, see `POST
        /v2/webhooks/endpoints/{{endpointId}}/ping`.<br>

        To manually retry a webhook delivery attempt, see `POST
        /v2/webhooks/delivery-logs/{{deliveryLogId}}/retry`.
      parameters:
        - name: deliveryLogId
          in: query
          description: |
            <br>Specifies the delivery log identifier to retrieve.
          schema:
            type: string
            format: uuid
            required: true
            example: 30d1d958-cf5a-446c-be96-5a78b2220c19
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhookdeliverylogisvdetaildto'
              example:
                requestHeaders:
                  Content-Type: application/json
                  X-Flute-Signature: >-
                    t=1746450622,v1=5257a869e7ecebeda32affa6c66e8fb5e5e64a50b9b3e8bbf9c1a8d8f5e9d0a1
                  X-Flute-Event-Id: 0e991cfc-28cf-4558-8874-bf2bbee8a406
                  X-Flute-Event-Type: settlement.batch.completed
                requestBody: >-
                  {"id":"8b7f1c87-c1da-48f7-82d1-426ae0960c53","type":"settlement.batch.completed","createdAt":"2026-05-05T13:10:00Z","data":{"batchId":"617f9259-8900-4134-b035-c53dd5d9675e","settledAmount":12500.00}}
                responseHeaders:
                  Content-Type: text/plain
                  Server: nginx
                responseBody: Service Unavailable
                nextRetryAt: '2026-05-05T13:25:22Z'
                deliveryLogId: 98602c85-294d-4215-8e02-78c4458106d6
                endpointId: fa48084e-ed38-46e3-b761-774b76d06de1
                endpointName: Peppared Street Cafe's Reconciliation
                endpointUrl: https://example.com/webhooks/pepparedstreetcafe
                eventId: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
                eventType: settlement.batch.completed
                attemptNumber: 3
                deliveryLogStatus: Failure
                endpointHTTPResponseCode: 503
                roundTripDurationMs: 5012
                errorMessage: Service Unavailable
                createdOn: '2026-05-05T13:10:22Z'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/delivery-logs/export:
    get:
      tags:
        - Webhooks
      summary: Exports webhook delivery logs
      operationId: flute-v2-get-webhooks-delivery-logs-export
      description: >
        <a id="flute-v2-get-webhooks-delivery-logs-export"></a>

        <span class="api-endpoint">GET {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/delivery-logs/export</span>


        This endpoint exports webhook delivery logs as a CSV or JSON file.


        Query parameters may be combined to filter the exported results.


        <span class="api-seealso">See Also:</span><br>

        To list all available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To list all delivery logs, see `GET /v2/webhooks/delivery-logs`.<br>

        To retrieve a specified delivery log, see `GET
        /v2/webhooks/delivery-logs/{{endpointId}}`.
      parameters:
        - name: endpointId
          in: query
          description: |
            <br>Specifies the webhook identifier to retrieve.
          schema:
            type: string
            format: uuid
            required: true
            example: a9b37f26-7d8e-4f9a-0b1c-2d3e4f5a6b92
        - $ref: '#/components/parameters/WebhookEventTypeQuery'
        - name: deliveryLogStatus
          in: query
          description: |
            Indicates the delivery success status code.

            | HTTP Status | Meaning |
            |:-----------:|---------|
            | Success | Delivery succeeded |
            | Failure | Delivery failed |
          schema:
            $ref: '#/components/schemas/webhookdeliverylogstatus'
        - name: endpointHTTPResponseCode
          in: query
          description: >
            Specifies the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning |

            |:-----------:|---------|

            | 200         | Delivery succeeded |

            | 400         | Bad request |

            | 401         | Unauthorized |

            | 404         | Endpoint not found |

            | 429         | Rate limited |
          schema:
            type: integer
            format: int32
            example: 200
        - $ref: '#/components/parameters/dateFrom'
        - $ref: '#/components/parameters/dateTo'
        - name: format
          in: query
          description: |
            Specifies the data format to return the items in.

            Valid values are:

            | Value  | Description                        |
            | ------ | ---------------------------------- |
            | Csv    | Returns the export as a CSV file.  |
            | Json   | Returns the export as a JSON file. |
          schema:
            type: string
            enum:
              - Csv
              - Json
            default: Csv
            example: Csv
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                type: string
                format: byte
                description: |
                  Indicates the returned file in the specified format.
            application/json:
              schema:
                type: string
                format: byte
                description: |
                  Indicates the returned file in the specified format.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /v2/webhooks/delivery-logs/{deliveryLogId}/retry:
    post:
      tags:
        - Webhooks
      summary: Retries a failed webhook delivery
      operationId: flute-v2-post-webhooks-delivery-logs-deliveryLogId-retry
      description: >
        <a id="flute-v2-post-webhooks-delivery-logs-deliveryLogId-retry"></a>

        <span class="api-endpoint">POST {{<a
        href="#urlbases">baseURL</a>}}/v2/webhooks/delivery-logs/{{endpointId}}/retry</span>


        This endpoint manually retries a failed webhook delivery.


        This is a single try each time.

        It does not automatically retry multiple times.

        It does not interfere with or interrupt the normal retry procedures.


        <span class="api-seealso">See Also:</span><br>

        To list all available webhooks, see `GET /v2/webhooks/endpoints`.<br>

        To test a webhook, see `POST
        /v2/webhooks/endpoints/{{endpointId}}/ping`.<br>

        To list all available delivery logs, see `GET
        /v2/webhooks/delivery-logs`
      parameters:
        - name: deliveryLogId
          in: path
          required: true
          description: |
            <br>Specifies the delivery log identifier to retry.
          schema:
            type: string
            format: uuid
            required: true
            example: 87915d04-5b6c-4d7e-8f9a-0b1c2d3e4f70
      responses:
        '200':
          description: OK. Attempt retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrywebhookdeliveryisvresponsedto'
              example:
                requestHeaders:
                  Content-Type: application/json
                  X-Flute-Signature: >-
                    t=1746450622,v1=5257a869e7ecebeda32affa6c66e8fb5e5e64a50b9b3e8bbf9c1a8d8f5e9d0a1
                  X-Flute-Event-Id: 0e991cfc-28cf-4558-8874-bf2bbee8a406
                  X-Flute-Event-Type: settlement.batch.completed
                requestBody: >-
                  {"id":"8b7f1c87-c1da-48f7-82d1-426ae0960c53","type":"settlement.batch.completed","createdAt":"2026-05-05T13:10:00Z","data":{"batchId":"617f9259-8900-4134-b035-c53dd5d9675e","settledAmount":12500.00}}
                responseHeaders:
                  Content-Type: text/plain
                  Server: nginx
                responseBody: Service Unavailable
                nextRetryAt: '2026-05-05T13:25:22Z'
                deliveryLogId: 98602c85-294d-4215-8e02-78c4458106d6
                endpointId: fa48084e-ed38-46e3-b761-774b76d06de1
                endpointName: Peppared Street Cafe's Reconciliation
                endpointUrl: https://example.com/webhooks/pepparedstreetcafe
                eventId: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
                eventType: settlement.batch.completed
                attemptNumber: 3
                deliveryLogStatus: Failure
                endpointHTTPResponseCode: 503
                roundTripDurationMs: 5012
                errorMessage: Service Unavailable
                createdOn: '2026-05-05T13:10:22Z'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    Bearer:
      type: http
      description: Specify the authorization token.
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CommonExceptionExample:
      type: object
      properties:
        details:
          type: string
          x-method: response
          nullable: true
          description: >
            Indicates details about the error.


            Example: Validation failed: -- Email: 'Email' is not a valid email
            address. Severity: Error
          example: >-
            Validation failed: -- Email: 'Email' is not a valid email address.
            Severity: Error
        statusCode:
          type: integer
          format: int32
          x-method: response
          nullable: true
          description: >
            Specifies the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning |

            |:-----------:|---------|

            | 200 | Delivery succeeded |

            | 400 | Bad request |

            | 401 | Unauthorized |

            | 404 | Endpoint not found |

            | 429 | Rate limited |


            Example: 401
          example: 401
        source:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the source of the error.

            Example: &lt;Service&gt;
          example: <Service>
        exceptionType:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the error's exception type.

            Example: FluentValidation.ValidationException
          example: FluentValidation.ValidationException
        correlationId:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the correlation identifier.

            Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
          example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
        entityId:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the entity identifier.

            Example:<br>
            null
        errorCode:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the error code.

            Example:<br>
            null
        title:
          type: string
          x-method: response
          nullable: true
        cause:
          type: string
          x-method: response
          nullable: true
        resolution:
          type: string
          x-method: response
          nullable: true
        documentationUrl:
          type: string
          x-method: response
          nullable: true
          description: https://developer.flute.com/
      additionalProperties: false
    customerId:
      type: string
      format: uuid
      x-method: response
      nullable: true
      description: >
        Identifies the customer to link this payment method to.


        This value may be null when this payment method is an orphan owned by
        the merchant directly.

        An orphan payment method is a payment method in the merchant's vault but
        has no customer record associated with it.


        Example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c
      example: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c
    AddressDto:
      type: object
      required:
        - countryCode
      description: |
        Identifies the address information.
      properties:
        addressLine1:
          type: string
          nullable: true
          x-method: request
          description: |
            Identifies the street address.

            Example: 21 E. Main Street
          example: 21 E. Main Street
        addressLine2:
          type: string
          nullable: true
          x-method: request
          description: |
            Identifies additional street address information.

            Example: Office 3
          example: Office 3
        city:
          type: string
          x-method: request
          nullable: true
          description: |
            Identifies the name of the city.

            Examples:<br>
            Chicago<br>
            New York<br>
            Salt Lake City
          example: Chicago
        postalCode:
          type: string
          x-method: request
          minLength: 2
          maxLength: 15
          nullable: true
          description: |
            Identifies the postal or ZIP code.

            Examples:<br>
            60601<br>
            60601-0001
          example: 60601-0001
        stateCode:
          type: string
          nullable: true
          x-method: request
          description: >
            Identifies the state identifier (in two-letter USPS [United States
            Postal Service] postal code).


            For regions outside the US, use the ISO 3166-2 format.


            Examples:<br>

            TX<br>

            WA<br>

            IL
          example: NY
        countryCode:
          type: string
          nullable: true
          x-method: request
          description: |
            Identifies the country identifier (in two letter ISO 3166-1 format).

            Examples:<br>
            US<br>
            CA<br>
            GB
          example: US
      additionalProperties: false
    ListCustomersResponseDto:
      type: object
      properties:
        customerId:
          $ref: '#/components/schemas/customerId'
        externalId:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the external identifier.

            This value is used to detect duplicate transactions.
            For example, a duplicate pending record is marked as `Skipped`.

            Example: CUST-EXT-001
          example: CUST-EXT-001
        firstName:
          type: string
          x-method: response
          description: |
            Indicates the customer's first name.

            Example: Alexandro
          example: Alexandro
          nullable: true
        lastName:
          type: string
          x-method: response
          description: |
            Indicates the customer's last name.

            Example: Peppared
          example: Peppared
          nullable: true
        companyName:
          type: string
          x-method: response
          description: |
            Indicates the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        email:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: response
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Indicates the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        lastTransactionDate:
          type: string
          format: date-time
          x-method: response
          nullable: true
          description: >
            Indicates the timestamp (in an ISO 8601 date-time UTC format) of the
            last transaction.


            Example: 2026-05-01T12:00:56.264Z
          example: '2026-05-01T12:00:56.264Z'
        paymentMethodsCount:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the number of payment methods.

            Example: 3
          example: 3
      additionalProperties: false
    pageInfo:
      type: object
      description: >
        Indicates an object describing the pagination status.


        If additional pages to review are needed, repeat the exact same search
        but include a new pageIndex value.

        Typically, this will increment the current `pageIndex` by one.

        However, any valid value may be used.

        Value restrictions include:

        * A value less than zero is not permitted.<br>

        * Values equal to or greater than `totalPages` end successfully but will
        not return any items.
      properties:
        pageIndex:
          type: integer
          format: int32
          minimum: 0
          x-method: response
          description: >
            Indicates the page number from the search results.


            The pageIndex value is zero-based.

            Valid values range from zero to `totalPages` less one.<br>

            For example, if `totalPages` = 10, then the valid range is zero to
            nine. 


            Example: 0
          example: 0
        pageSize:
          type: integer
          format: int32
          minimum: 0
          maximum: 200
          x-method: response
          description: |
            Indicates the number of items returned per page.

            Example: 20
          example: 20
        totalItems:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the total number of items across all pages.

            Example: 1012
          example: 1012
        totalPages:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the total number of pages available.

            Example: 51
          example: 51
        hasMore:
          type: boolean
          description: >
            Indicates additional pages are available after the current one.


            If `true`, additional pages are available after the current one.<br>

            If `false`, additional pages are not available after the current
            one.


            Example: true
          example: true
    PageOfListCustomersResponseDto:
      type: object
      description: <a id="get_v2_customers_response_body"></a>
      properties:
        items:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/ListCustomersResponseDto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    ValidationExceptionExample:
      type: object
      properties:
        details:
          type: string
          x-method: response
          nullable: true
          description: >
            Indicates details about the error.


            Example: Validation failed: -- Email: 'Email' is not a valid email
            address. Severity: Error
          example: >-
            Validation failed: -- Email: 'Email' is not a valid email address.
            Severity: Error
        statusCode:
          type: integer
          format: int32
          x-method: response
          nullable: true
          description: >
            Specifies the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning |

            |:-----------:|---------|

            | 200 | Delivery succeeded |

            | 400 | Bad request |

            | 401 | Unauthorized |

            | 404 | Endpoint not found |

            | 429 | Rate limited |


            Example: 401
          example: 401
        source:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the source of the error.

            Example: &lt;Service&gt;
          example: <Service>
        exceptionType:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the error's exception type.

            Example: FluentValidation.ValidationException
          example: FluentValidation.ValidationException
        correlationId:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the correlation identifier.

            Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
          example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
        entityId:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the entity identifier.

            Example:<br>
            null
        errorCode:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the error code.

            Example:<br>
            null
        title:
          type: string
          x-method: response
          nullable: true
        cause:
          type: string
          x-method: response
          nullable: true
        resolution:
          type: string
          x-method: response
          nullable: true
        documentationUrl:
          type: string
          x-method: response
          nullable: true
          description: https://developer.flute.com/
        errors:
          type: object
          x-method: response
          additionalProperties:
            type: array
            items:
              type: string
            description: |
              Indicates the precise error.

              Example:
            example:
              - Email
            nullable: true
          nullable: true
      additionalProperties: false
    CustomerPaymentMethodCardDto:
      type: object
      required:
        - cardNumber
        - expirationMonth
        - expirationYear
      properties:
        paymentName:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize. 


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        cardNumber:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the card number.

            This is the PAN (primary account number) for the transaction.

            Example: 411235455213655
          example: '411235455213655'
        securityCode:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the securityCode (sometimes also called similarly to CCV)
            for the card.


            This is a three or four digit security code on the credit card.


            Example: 483
          example: '483'
        expirationMonth:
          type: integer
          format: int32
          x-method: request
          nullable: true
          description: >
            Specifies the expiration month of the card (in 2-digit numeric
            format).


            Examples:<br>

            02<br>

            10<br>

            12
          example: 12
        expirationYear:
          type: integer
          format: int32
          x-method: request
          nullable: true
          description: |
            Specifies the expiration year of the card (in 4-digit YYYY format).

            Example: 2032
          example: 2032
      additionalProperties: false
    accountNumberRequest:
      type: string
      nullable: true
      x-method: request
      description: |
        Specifies the bank account number for the ACH transaction.

        We recommend avoiding the use of an account number.
        Instead, use `paymentMethodId` when possible.

        Example: 1234567890
      example: '1234567890'
    AccountHolderType:
      enum:
        - Business
        - Personal
      type: string
      description: |
        Identifies the holder type of the account.

        Valid values are:

        | Type     | Description                                    |
        |----------|------------------------------------------------|
        | Business | Card issued to a business or company account.  |
        | Personal | Card issued to an individual for personal use. |

        Example: Business
      example: Business
    AccountType:
      enum:
        - Checking
        - Savings
      type: string
      description: |
        Identifies the type of the account.

        Valid values are:

        | Type     | Description                                    |
        |----------|------------------------------------------------|
        | Checking | Account used for regular daily transactions.   |
        | Savings  | Account used to hold and grow funds over time. |   

        Example: Checking
      example: Checking
    CustomerPaymentMethodAchDto:
      type: object
      properties:
        paymentName:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        routingNumber:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the ACH's account routing number.

            Example: 021000021
          example: '021000021'
        accountNumber:
          $ref: '#/components/schemas/accountNumberRequest'
        taxId:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the tax identifier.

            Example: 12-3456789
          example: 12-3456789
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        accountType:
          $ref: '#/components/schemas/AccountType'
      additionalProperties: false
    CreateCustomerRequestDto:
      required:
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          minLength: 1
          type: string
          x-method: request
          description: |
            Specifies the customer's first name.

            Example: Alexandro
          example: Alexandro
        lastName:
          minLength: 1
          type: string
          x-method: request
          description: |
            Specifies the customer's last name.

            Example: Peppared
          example: Peppared
        companyName:
          type: string
          x-method: request
          description: |
            Specifies the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        email:
          type: string
          x-method: request
          nullable: true
          description: |
            Specifies the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: request
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Specifies the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        hasSmsConsent:
          type: boolean
          nullable: true
          default: false
          x-method: request
          description: |
            Specifies the customer has consented to receiving the SMS.

            If `true`, the customer has consented to receiving the SMS.<br>
            If `false`, the customer has not consented to receiving the SMS.

            Example: true
          example: true
        shouldUseBillingAsShippingAddress:
          type: boolean
          x-method: request
          description: |
            Specifies to use the billing address as shipping address.

            If `true`, use the billing address as shipping address.<br>
            If `false`, do not use the billing address as shipping address.

            Example: true
          example: true
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        shippingAddress:
          $ref: '#/components/schemas/AddressDto'
        paymentMethodsCards:
          type: array
          nullable: true
          x-method: request
          items:
            $ref: '#/components/schemas/CustomerPaymentMethodCardDto'
          description: |
            Specifies accepted cards (credit or debit) payment methods.
        paymentMethodsAchAccounts:
          type: array
          nullable: true
          x-method: request
          items:
            $ref: '#/components/schemas/CustomerPaymentMethodAchDto'
          description: |
            Specifies accepted ACH accounts payment methods.
      additionalProperties: false
    CreateCustomerResponseDto:
      type: object
      properties:
        customerId:
          $ref: '#/components/schemas/customerId'
      additionalProperties: false
    paymentMethodIdResponse:
      type: string
      format: uuid
      x-method: request
      nullable: true
      description: |
        Indicates the payment method identifier.

        This is the identifier of a previously saved ACH account to charge.

        Example: 39a95e35-6d50-45ec-884b-c2417edf005d
      example: 39a95e35-6d50-45ec-884b-c2417edf005d
    expirationMonthRequest:
      type: integer
      format: int32
      nullable: true
      minimum: 1
      maximum: 12
      description: >
        Identifies the expiration month (in a two-digit number format) of the
        card.


        Examples:<br>

        07<br>

        12<br>
      example: 12
    expirationYearRequest:
      type: integer
      format: int32
      nullable: true
      description: |
        Identifies the expiration year (in a four-digit number) of the card.

        Example: 2032
      example: 2032
    TokenType:
      enum:
        - Local
        - Network
      type: string
      description: >
        Indicates the type of the token.


        Valid values are:


        | Type    | Meaning |

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

        | Local   | Tokenized and stored within Flute's own vault |

        | Network | Tokenized through a card network, such as Visa or
        Mastercard, using their network tokenization services |


        Example: Local
      example: Local
    CardType:
      enum:
        - Unknown
        - Visa
        - MasterCard
        - AmericanExpress
        - DinersClub
        - Discover
        - JCB
      type: string
      description: >
        Indicates the type of the card.


        Valid values are:


        | Type              | Description                                      
        |

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

        | AmericanExpress   | Card issued by American Express network.         
        |

        | DinersClub        | Card issued by the Diners Club network.          
        |

        | Discover          | Card issued by the Discover network.             
        |

        | JCB               | Card issued by the Japan Credit Bureau network.  
        |

        | MasterCard        | Card issued by the MasterCard network.           
        |

        | Unknown           | Card type could not be determined.               
        |

        | Visa              | Card issued by the Visa network.                 
        |


        Example: Visa
      example: Visa
    CreditDebitType:
      enum:
        - Credit
        - Debit
        - Unknown
      type: string
      description: |
        Indicates the card is either credit or debit.

        Valid values are:

        | Type    | Description                                |
        |---------|--------------------------------------------|
        | Credit  | Card draws funds from a credit line.       |
        | Debit   | Card draws funds from a bank account.      |
        | Unknown | Card funding type could not be determined. |

        Example: Credit
      example: Credit
    GetCustomerResponseDtoCardDto:
      type: object
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        paymentName:
          type: string
          x-method: response
          description: |
            Indicates the name of the payment method.

            This is a free-formed name that is convenient to recognize.

            Example: Personal Visa
          nullable: true
          example: Personal Visa
        isDefault:
          type: boolean
          x-method: response
          description: |
            Indicates this payment method is the default payment method.

            If `true`, the card is the default payment method.<br>
            If `false`, the card is not the default payment method.

            Example: true
          example: true
        cardMask:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the PAN (primary account number).


            This value may be partially obscured as additional security.

            This value can be safely displayed to clients without revealing the
            actual or full account number.


            Example: ************3655
          example: '************3655'
        expirationMonth:
          $ref: '#/components/schemas/expirationMonthRequest'
        expirationYear:
          $ref: '#/components/schemas/expirationYearRequest'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
        cardType:
          $ref: '#/components/schemas/CardType'
        creditDebitType:
          $ref: '#/components/schemas/CreditDebitType'
      additionalProperties: false
    GetCustomerResponseDtoAchAccountDto:
      type: object
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        paymentName:
          type: string
          x-method: response
          description: >
            Indicates the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
          nullable: true
        isDefault:
          type: boolean
          x-method: response
          description: |
            Indicates this payment method is the default payment method.

            If `true`, this ACH account is the default payment method.<br>
            If `false`, this ACH account is not the default payment method.

            Example: true
          example: true
        accountNumber:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the bank account number for the ACH transaction.


            This value may be partially obscured as additional security.

            It can then be safely displayed to clients without revealing the
            actual or full account number.


            Examples:<br>

            1234567890<br>

            ******7890
          example: '******7890'
        routingNumber:
          type: string
          x-method: response
          description: |
            Indicates the ACH's account routing number.

            Example: 021000021
          example: '021000021'
          nullable: true
        accountType:
          $ref: '#/components/schemas/AccountType'
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        taxId:
          type: string
          x-method: response
          description: |
            Indicates the tax identifier.

            Example: 12-3456789
          example: 12-3456789
          nullable: true
      additionalProperties: false
    GetCustomerResponseDto:
      type: object
      properties:
        customerId:
          $ref: '#/components/schemas/customerId'
        externalId:
          type: string
          x-method: response
          description: |
            Indicates the external identifier.

            This value is used to detect duplicate transactions.
            For example, a duplicate pending record is marked as `Skipped`.

            Example: CUST-EXT-12345
          nullable: true
          example: CUST-EXT-12345
        firstName:
          type: string
          x-method: response
          description: |
            Indicates the customer's first name.

            Example: Alexandro
          example: Alexandro
          nullable: true
        lastName:
          type: string
          x-method: response
          description: |
            Indicates the customer's last name.

            Example: Peppared
          example: Peppared
          nullable: true
        companyName:
          type: string
          x-method: response
          description: |
            Indicates the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        email:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: response
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Indicates the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        hasSmsConsent:
          type: boolean
          x-method: response
          description: |
            Specifies the customer has consented to receiving the SMS.

            If `true`, the customer has consented to receiving the SMS.<br>
            If `false`, the customer has not consented to receiving the SMS.

            Example: true
          example: true
        shouldUseBillingAsShippingAddress:
          type: boolean
          x-method: response
          description: |
            Indicates to use the billing address as shipping address.

            If `true`, use the billing address as shipping address.<br>
            If `false`, do not use the billing address as shipping address.

            Example: true
          example: true
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        shippingAddress:
          $ref: '#/components/schemas/AddressDto'
        transactionsCount:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the number of transactions.

            Example: 31
          example: 31
        transactionsVolume:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the sum of the transactions.

            Example: 1234.56
          example: 1234.56
        lastTransactionAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: response
          nullable: true
          description: |
            Indicates the amount of the last transaction.

            Example: 99.99
          example: 99.99
        lastTransactionDate:
          type: string
          format: date-time
          x-method: response
          nullable: true
          description: >
            Indicates the date-time (in an ISO 8601 date-time format) of the
            last transaction.


            Example: 2026-05-01T12:00:56.264Z
          example: '2026-05-01T12:00:56.264Z'
        numberOfSubscriptions:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the number of active subscriptions.

            Example: 6
          example: 6
        cards:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/GetCustomerResponseDtoCardDto'
          description: |
            Indicates the card payment methods.
          nullable: true
        achAccounts:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/GetCustomerResponseDtoAchAccountDto'
          description: |
            Indicates the ACH (automated clearing house) payment methods.
          nullable: true
      additionalProperties: false
    UpdateCustomerRequestDto:
      type: object
      properties:
        firstName:
          type: string
          x-method: request
          description: |
            Specifies the customer's first name.

            Example: Alexandro
          example: Alexandro
          nullable: true
        lastName:
          type: string
          x-method: request
          description: |
            Specifies the customer's last name.

            Example: Peppared
          example: Peppared
          nullable: true
        companyName:
          type: string
          x-method: request
          description: |
            Specifies the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        email:
          type: string
          x-method: request
          nullable: true
          description: |
            Specifies the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: request
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Specifies the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        hasSmsConsent:
          type: boolean
          nullable: true
          default: false
          x-method: request
          description: |
            Specifies the customer has consented to receiving the SMS.

            If `true`, the customer has consented to receiving the SMS.<br>
            If `false`, the customer has not consented to receiving the SMS.

            Example: true
          example: true
        shouldUseBillingAsShippingAddress:
          type: boolean
          x-method: request
          description: |
            Specifies to use the billing address as shipping address.

            If `true`, use the billing address as shipping address.<br>
            If `false`, do not use the billing address as shipping address.

            Example: true
          example: true
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        shippingAddress:
          $ref: '#/components/schemas/AddressDto'
      additionalProperties: false
    merchantId:
      type: string
      format: uuid
      x-method: REQUEST
      description: |
        Identifies the merchant identifier.

        Example: 5611f824-48ef-4255-978d-91ce13953bbd
      example: 5611f824-48ef-4255-978d-91ce13953bbd
    GetApiKeysResponseDtoApiKeyDto:
      type: object
      properties:
        clientId:
          type: string
          description: |
            Indicates the client identifier.

            Example: 5c0f39f6-02a8-4053-9e72-56d9d5947c1c
          format: uuid
          x-method: response
          example: 5c0f39f6-02a8-4053-9e72-56d9d5947c1c
        merchantId:
          $ref: '#/components/schemas/merchantId'
        apiKeyName:
          type: string
          x-method: response
          description: |
            Indicates the display name for the API key.

            Example: Production integration key
          nullable: true
          example: Production integration key
      additionalProperties: false
    GetApiKeysResponseDto:
      type: object
      properties:
        apiKeys:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/GetApiKeysResponseDtoApiKeyDto'
          description: An array of the merchant's API keys.
          nullable: true
      additionalProperties: false
    CreateApiKeyRequestDto:
      required:
        - apiKeyName
        - merchantId
      type: object
      properties:
        merchantId:
          $ref: '#/components/schemas/merchantId'
        apiKeyName:
          minLength: 1
          type: string
          x-method: REQUEST
          description: |
            Specifies a display name for the API key.

            Example: Production integration key
          example: Production integration key
      additionalProperties: false
    CreateApiKeyResponseDto:
      type: object
      properties:
        clientId:
          type: string
          description: |
            Indicates the client identifier.

            Example: 919c19ac-09cf-40c1-b093-413b9cabde43
          format: uuid
          x-method: response
          example: 919c19ac-09cf-40c1-b093-413b9cabde43
        clientSecret:
          type: string
          format: UUID
          x-method: response
          description: >
            Indicates the client secret.


            The client secret is returned once and only during its creation
            here.

            Store it securely.

            Protect the `clientSecret` as if it were a password.


            Example: bcaa0840-2872-44ea-9122-552a804a054a
          nullable: true
          example: bcaa0840-2872-44ea-9122-552a804a054a
      additionalProperties: false
    PaymentMethodType:
      enum:
        - Card
        - ACH
        - Cash
      type: string
      description: |
        Identifies the payment method type.

        Valid values are:

        | Type  | Description                                |
        |-------|--------------------------------------------|
        | ACH   | Payment made through an ACH bank transfer. |
        | Card  | Payment made with a credit or debit card.  |
        | Cash  | Payment made with physical currency.       |

        Example: Card
      example: Card
    PaymentMethodResponseDtoCardDetails:
      type: object
      properties:
        cardMask:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the PAN (primary account number).


            This value may be partially obscured as additional security.

            This value can be safely displayed to clients without revealing the
            actual or full account number.


            Example: ************3655
          example: '************3655'
        expirationMonth:
          $ref: '#/components/schemas/expirationMonthRequest'
        expirationYear:
          $ref: '#/components/schemas/expirationYearRequest'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
      additionalProperties: false
    PaymentMethodResponseDtoAchDetails:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the bank account number for the ACH transaction.


            This value may be partially obscured as additional security.

            It can then be safely displayed to clients without revealing the
            actual or full account number.


            Examples:<br>

            1234567890<br>

            ******7890
          example: '******7890'
        routingNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the ACH (automated clearing house) account routing number.

            Example: 021000021
          example: '021000021'
        accountType:
          $ref: '#/components/schemas/AccountType'
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        taxId:
          type: string
          x-method: response
          description: >
            Indicates the tax identifier.


            This value may be partially obscured as additional security.

            This value can be safely displayed to clients without revealing the
            actual or full value.


            Example: **-***6789
          example: '**-***6789'
          nullable: true
        companyName:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the name of the customer's company or organization.


            This is the ACH legal-entity name.

            Set on business orphan payment methods at create time so it is
            available at transaction time when `ContactInfo.CompanyName` is
            omitted on the request.


            Example: Peppared Street Cafe
          example: Peppared Street Cafe
      additionalProperties: false
    PaymentMethodResponseDto:
      type: object
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        customerId:
          $ref: '#/components/schemas/customerId'
        name:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        type:
          $ref: '#/components/schemas/PaymentMethodType'
        isDefault:
          type: boolean
          x-method: response
          description: |
            Indicates this payment method is the default payment method.

            If `true`, this is the default payment method.<br>
            If `false`, this is not the default payment method.

            Example: true
          example: true
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            payment method was created on.


            Example: 2026-01-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
        card:
          $ref: '#/components/schemas/PaymentMethodResponseDtoCardDetails'
        ach:
          $ref: '#/components/schemas/PaymentMethodResponseDtoAchDetails'
      additionalProperties: false
    PageOfPaymentMethodResponseDto:
      type: object
      properties:
        items:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/PaymentMethodResponseDto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    CreateCardPaymentMethodRequestDto:
      type: object
      properties:
        cardNumber:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the credit card number used for the transaction.

            Example: 4111111111111111
          example: '4111111111111111'
        securityCode:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the securityCode (sometimes also called similarly to CCV)
            for the card.


            This is a three or four digit security code on the credit card.


            Example: 483
          example: '483'
        expirationMonth:
          $ref: '#/components/schemas/expirationMonthRequest'
        expirationYear:
          $ref: '#/components/schemas/expirationYearRequest'
        customerId:
          $ref: '#/components/schemas/customerId'
        paymentName:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
      additionalProperties: false
    CreatePaymentMethodResponseDto:
      type: object
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
      additionalProperties: false
    CreateAchPaymentMethodRequestDto:
      type: object
      properties:
        routingNumber:
          type: string
          x-method: request
          description: |
            Specifies the ACH's account routing number.

            Example: 021000021
          example: '021000021'
          nullable: true
        accountNumber:
          $ref: '#/components/schemas/accountNumberRequest'
        taxId:
          type: string
          x-method: request
          description: |
            Specifies the tax identifier.

            Example: 12-3456789
          example: 12-3456789
          nullable: true
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        accountType:
          $ref: '#/components/schemas/AccountType'
        customerId:
          $ref: '#/components/schemas/customerId'
        name:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        companyName:
          type: string
          x-method: request
          description: >
            Specifies the name of the customer's company or organization.


            This is the legal entity name.

            Required for orphan Business ACH transactions when the request does
            not supply it on the transaction's ContactInfo.
          nullable: true
          example: Acme Corp Inc
      additionalProperties: false
    UpdatePaymentMethodRequestDto:
      type: object
      properties:
        paymentName:
          type: string
          x-method: request
          description: >
            Specifies the name for the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
          nullable: true
      additionalProperties: false
    SessionMode:
      type: string
      enum:
        - Payment
        - SaveMethod
        - PaymentAndSave
      format: enum
      default: Payment
      description: >
        Indicates the intent of the session.


        | Name           | Description                                   |

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

        | Payment        | Standard payment session.                     |

        | SaveMethod     | Vault-only session to store a payment method. The
        amount must be zero.<br><br>No payment is processed. This stores the
        customer's card details for future use. `vaultedPaymentMethodId` is
        returned on the session once confirmed. |

        | PaymentAndSave | Charge the payment and store the customer's card
        details for future use.<br><br>`vaultedPaymentMethodId` is returned on
        the session once confirmed. |


        Example: Payment
      example: Payment
    CreatePaymentSessionRequestDto:
      type: object
      description: Request DTO for creating a payment session (v2).
      additionalProperties: false
      required:
        - amount
      properties:
        amount:
          type: number
          format: double
          minimum: 0.01
          multipleOf: 0.01
          nullable: true
          description: >
            Specifies the base amount (in USD) to charge.


            For payment sessions (mode of either `SaveMethod` or
            `PaymentAndSave`), this value must be greater than zero.


            For vault-only payment sessions (mode of `SaveMethod`), this value
            must be zero.


            A value of null creates a flexible-amount payment session where the
            amount is set at checkout.


            Examples:<br>

            64.99<br>

            0<br>

            null
          example: 64.99
        mode:
          $ref: '#/components/schemas/SessionMode'
        skipAddressVerification:
          type: boolean
          default: false
          nullable: true
          description: >
            Specifies to bypass the AVS (address verification service) in the
            payment gateway.


            This value is applicable only to `Payment` and `PaymentAndSave` from
            `mode`.


            If `true`, bypasses AVS in the payment gateway.<br>

            If `false`, does not bypass AVS in the payment gateway.


            Example: true
          example: true
        referenceId:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: 10001
          example: '10001'
        tipAmount:
          type: number
          format: double
          nullable: true
          multipleOf: 0.01
          description: >
            Specifies the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            Example: 14.50 (for $14.50)
          example: 14.5
        customerId:
          $ref: '#/components/schemas/customerId'
        successUrl:
          type: string
          nullable: true
          description: >
            Specifies the URL to redirect the payer to after a successful
            payment.


            This value is not needed if using Flute Elements and Flute Checkout.


            Example:
            https://api.payments.flute.com/xOut/sessions/session-complete.html
          example: https://api.payments.flute.com/xOut/sessions/session-complete.html
        paymentMethodTypes:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Specifies payment methods to be shown at checkout.

            Valid values are:

            | Payment method | Type |
            |----------------|------|
            | Card           | Credit or debit card payment |
            | ACH            | ACH (automated clearing house) payment |

            Example: Card
          example: Card
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
            nullable: true
          description: >
            Specifies arbitrary key-value pairs to attach to the payment session
            object.


            These values are used to store supplemental information.

            They are not functionally used in this endpoint.

            Instead, they are included while retrieving the payment session.

            This allows additional notes to be passed along to the operator.


            Pass null to clear all metadata.


            Examples:<br>

            [ {"orderId": "9921"} ]<br>

            [ {"Guest notes": "Member of The World of Hyatt Credit Card."} ]<br>

            [{"orderId": "9921"}, {"Guest notes": "Member of The World of Hyatt
            Credit Card.}]
          example:
            - orderId: '9921'
            - Guest notes: Member of The World of Hyatt Credit Card.
        afterCompletionMessage:
          type: string
          nullable: true
          description: >
            Specifies a message shown to the payer after the payment session
            completes.


            This value is not needed if using Flute Elements and Flute Checkout.


            Example: Thank you for shopping with us.
          example: Thank you for shopping with us.
        isMultiUse:
          type: boolean
          nullable: true
          description: >
            Specifies the checkout URL can be used for multiple payments.


            This value is applied only if using Flute Elements or Flute
            Checkout.


            If `true`, the checkout URL can be used for multiple payments.<br>

            If `false`, the checkout URL cannot be used for multiple payments.


            Example: true
          example: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
          default: null
          description: >
            Specifies the date-time (in an ISO 8601 date-time format) expiration
            for the payment session.


            The time must be in the future.


            If this value is null or omitted, there is no expiration date.


            Example: 2027-02-19T20:24:52.934Z
          example: '2027-02-19T20:24:52.934Z'
        pageName:
          type: string
          nullable: true
          description: >
            Specifies the display name shown on the checkout page.


            This is a free-formed name that is convenient for the merchant to
            recognize. 


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        paymentNotes:
          type: string
          nullable: true
          description: |
            Specifies additional notes shown to the payer on the checkout page.

            Example: The client's server is being repaired.
          example: The client's server is being repaired.
    CreatePaymentSessionResponseDto:
      type: object
      description: Response DTO for creating a payment session (v2).
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: >
            Indicates the identifier of the created payment session.


            This is also called the `paymentSessionId`.


            If `mode` was `SaveMethod`, a payment session was successfully
            created but with an automatic `Completed` status.

            That payment session is not available for additional processing.

            The paymentSessionId may be used to retrieve the payment session
            information.

            For those details, see `GET
            /v2/payment-sessions/{{paymentSessionId}}`.


            If the mode was `PaymentAndSave`, a payment session was successfully
            created. 

            That payment session is available for additional processing.


            Example: dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25
          example: dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25
        checkoutUrl:
          type: string
          nullable: true
          description: >
            Indicates full URL of the hosted checkout page for this payment
            session.


            Example:
            https://api.payments.flute.com/xOut/sessions/session-complete.html
          example: https://api.payments.flute.com/xOut/sessions/session-complete.html
        checkoutUrlShort:
          type: string
          nullable: true
          description: >
            Indicates the shortened URL of the hosted checkout page for this
            payment session.


            Example: https://smallurl.com/4kxm9p2
          example: https://smallurl.com/4kxm9p2
    TransactionSourceResponseDto:
      type: object
      description: Transaction source information.
      additionalProperties: false
      properties:
        name:
          type: string
          nullable: true
          description: >
            Indicates the name of that specific instance.


            This is a free-formed type name that is convenient for the merchant
            to recognize.


            Example: Front Counter Terminal
          example: Front Counter Terminal
        type:
          type: string
          nullable: true
          description: >
            Indicates the description of the source.


            This is a free-formed type name that is convenient for the merchant
            to recognize.


            Example: Terminal
          example: Terminal
        id:
          type: string
          format: uuid
          nullable: true
          description: |
            Indicates an identifier specifying the instance of the source.

            Example: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03
          example: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03
        typeId:
          type: integer
          format: int32
          nullable: true
          description: |
            Reserved for internal use only.

            Do not use.
        version:
          type: string
          nullable: true
          x-method: request
          description: |
            Indicates the version.

            Example: 1.4.2
          example: 1.4.2
    TransactionReceiptDtoTransactionReceiptAmountDto:
      type: object
      additionalProperties: false
      properties:
        baseAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          description: |
            Specifies the base transaction amount before adjustments.

            Example: 99.99
          example: 99.99
        percentageOffAmount:
          type: number
          format: double
          description: >
            Specifies the discount amount (in USD) taken off.


            This discount was calculated using the preset percentage from
            `percentageOffRate`.


            Example: 12.50
          example: 12.5
        percentageOffRate:
          type: number
          format: double
          description: >
            Identifies the discount percentage.


            This value is percentage rate for the discount.

            This discount percentage calculates the discount amount for
            `percentageOffAmount`.


            Example: 3.5 (as 3.5%)
          example: 3.5
        cashDiscountAmount:
          type: number
          format: double
          description: |
            Identifies the cash discount amount (in USD) taken off.

            Example: 12.50 (for $12.50)
          example: 12.5
        cashDiscountRate:
          type: number
          format: double
          description: >
            Identifies the discount percentage for a cash (or cash-equivalent)
            discount.


            Example: 1.5 (for 1.5%)
          example: 1.5
        surchargeAmount:
          type: number
          format: double
          x-method: request
          description: >
            Specifies the surcharge amount (in USD) applied.


            Care must be taken that a value other than zero can be provided to
            either `surchargeAmount` or `surchargeRate`.

            A non-zero value cannot be provided to both.


            Example: 22 (for $22)
          example: 22
        surchargeRate:
          type: number
          format: double
          description: >
            Indicates the percent of transaction surcharge amount.


            This value is added to the base amount after `PercentageOffRate` has
            been applied.


            Care must be taken that a value other than zero can be provided to
            either `surchargeAmount` or `surchargeRate`.

            A non-zero value cannot be provided to both.


            Example: 2.5 (for 2.5%)
          example: 2.5
        tipAmount:
          type: number
          multipleOf: 0.01
          format: double
          description: >
            Indicates the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          description: >
            Indicates a percentage of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
        taxAmount:
          type: number
          format: double
          x-method: response
          nullable: true
          description: |
            Indicates the tax amount established on a product.

            Example: 3.75 (for 3.75%)
          example: 3.75
        taxRate:
          type: number
          format: double
          minimum: 0
          maximum: 22
          x-method: request
          nullable: true
          description: |
            Indicates the default level 2 autoFill sales tax rate.

            Examples:<br>
            5.0 (for 5.0%)<br>
            8.5 (for 8.5%)<br>
            10.25 (for 10.25%)
          example: 8.5
        totalAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          description: |
            Indicates the final total amount (in USD).

            Example: 124.99
          example: 124.99
    currencyCode:
      type: string
      nullable: true
      default: USD
      x-method: request/response
      description: |
        Identifies the transaction's currency code (in ISO 4217 currency code).

        Example: USD
      example: USD
    paymentprocessorid:
      type: string
      format: uuid
      nullable: true
      x-method: request/response
      description: |
        Identifies the payment processor.

        Example: 76215e54-a85b-4d42-9553-163fe393cb02
      example: 76215e54-a85b-4d42-9553-163fe393cb02
    TransactionType:
      type: string
      enum:
        - AchCancel
        - AchCredit
        - AchDebit
        - AchHold
        - AchRefund
        - AchUnHold
        - Authorization
        - Capture
        - CardAuthentication
        - Refund
        - RefundWORef
        - Sale
        - Settle
        - TipAdjustment
        - Void
      description: |
        Identifies the type of the transaction.

        Valid values are:

        | Type               | Explanation                                  |
        |--------------------|----------------------------------------------|
        | AchCancel          | Cancels a pending ACH transaction.           |
        | AchCredit          | Sends funds to a bank account.               |
        | AchDebit           | Pulls funds from a bank account.             |
        | AchHold            | Holds an ACH transaction temporarily.        |
        | AchRefund          | Returns funds from an ACH payment.           |
        | AchUnHold          | Releases a held ACH transaction.             |
        | Authorization      | Reserves funds for later capture.            |
        | Capture            | Collects funds from an authorization.        |
        | CardAuthentication | Confirms cardholder identity before payment. |
        | Refund             | Returns funds from a transaction.            |
        | RefundWORef        | Refunds a transaction without a reference.   |
        | Sale               | Authorizes and captures funds together.      |
        | Settle             | Submits a batch for final processing.        |
        | TipAdjustment      | Changes the tip amount on a transaction.     |
        | Void               | Cancels a transaction before settlement.     |

        Example: AchDebit
      example: AchDebit
    TransactionReceiptDtoTransactionReceiptSourceResponseDto:
      type: object
      description: |
        Indicates an object describing the source of the transaction.
      additionalProperties: false
      properties:
        name:
          type: string
          nullable: true
          description: >
            Indicates the name of that specific instance.


            This is a free-formed type name that is convenient for the merchant
            to recognize.


            Example: Front Counter Terminal
          example: Front Counter Terminal
        type:
          type: string
          nullable: true
          description: >
            Indicates the description of the source.


            This is a free-formed type name that is convenient for the merchant
            to recognize.


            Example: Terminal
          example: Terminal
        id:
          type: string
          format: uuid
          nullable: true
          description: |
            Indicates an identifier specifying the instance of the source.

            Example: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03
          example: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03
        typeId:
          type: integer
          format: int32
          nullable: true
          description: |
            Reserved for internal use only.

            Do not use.
    CardholderAuthenticationMethodDto:
      type: string
      enum:
        - NotAuthenticated
        - PIN
        - ElectronicSignatureAnalysis
        - ManualSignature
        - ManualOther
        - Unknown
        - SystematicOther
        - ETicketEnvAmex
        - OfflinePin
      description: >
        Indicates the method the cardholder was authenticated with.


        Valid values are:


        | Item                         |
        Explanation                                        |

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

        | ElectronicSignatureAnalysis  | Electronic signature captured and
        analyzed.        |

        | ETicketEnvAmex               | E-ticket environment specific to
        American Express. |

        | ManualOther                  | Other manual verification
        method.                  |

        | ManualSignature              | Paper or screen signature
        obtained.                |

        | NotAuthenticated             | No cardholder verification
        performed.              |

        | OfflinePin                   | Offline PIN verified by card chip, no
        network.     |

        | PIN                          | Online PIN verified by
        issuer.                     |

        | SystematicOther              | Systematic or automated method not
        listed.         |

        | Unknown                      | Verification method is
        unknown.                    |


        Example: PIN
      example: PIN
    CardDataSourceDto:
      type: string
      enum:
        - Internet
        - Swipe
        - NFC
        - EMV
        - EMVContactless
        - FallbackSwipe
        - Manual
      description: |
        Indicates the source of the card (credit or debit).

        Valid values are:

        | Item           | Explanation                                    |
        |----------------|------------------------------------------------|
        | EMV            | Chip read using EMV tags.                      |
        | EMVContactless | Tap chip read using EMV tags.                  |
        | FallbackSwipe  | Swipe used after failed chip read.             |
        | Internet       | Virtual terminal or API entry.                 |
        | Manual         | Card present, keyed entry.                     |
        | NFC            | Contactless tap using EMV tags and track data. |
        | Swipe          | Magnetic stripe track data read.               |

        Example: Swipe
      example: Swipe
    TransactionReceiptDtoCardDetailsDto:
      type: object
      additionalProperties: false
      properties:
        authCode:
          type: string
          nullable: true
          description: |
            Indicates the authorization code from the card processor.

            This authorization does not apply to tip adjustments.
            The code explicitly falls back to the original.

            Example: ABC123
          example: ABC123
        mid:
          type: string
          nullable: true
          description: >
            Indicates the MID (merchant identifier).


            This is an identifier the acquirer or processor assigns to a
            specific merchant account. 


            Example: 700123456789
          example: '700123456789'
        tid:
          type: string
          nullable: true
          description: >
            Indicates the TID (terminal identifier).


            This is an identifier of the specific physical terminal or device
            used in the transaction.


            Example: 00012345
          example: '00012345'
        rrn:
          type: string
          nullable: true
          description: >
            Indicates the RRN (retrieval reference number).


            This is a card-network, such as for Visa or Mastercard, reference
            number assigned to every card transaction.

            It is used to trace or retrieve the transaction later, such as for
            chargebacks or disputes.


            Example: 625031412345
          example: '625031412345'
        cardCreditDebitType:
          $ref: '#/components/schemas/CreditDebitType'
        processCreditDebitType:
          $ref: '#/components/schemas/CreditDebitType'
        cardType:
          $ref: '#/components/schemas/CardType'
    TransactionReceiptDtoElectronicCheckDetails:
      type: object
      additionalProperties: false
      properties:
        customerAccountNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the ACH account number.

            This displays only the last four numbers.

            Example: 4111111111111111
          example: '4111111111111111'
        customerRoutingNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the ACH routing number.

            Example: 867320021
          example: '867320021'
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        accountType:
          $ref: '#/components/schemas/AccountType'
        taxId:
          type: string
          nullable: true
          description: |
            Specifies the tax identifier.

            Example: 12-3456789
          example: 12-3456789
    SuggestedTipsDto:
      type: object
      properties:
        tipPercent:
          type: number
          format: double
          description: >
            Indicates a percentage of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
        tipAmount:
          type: number
          format: double
          multipleOf: 0.01
          description: >
            Indicates the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
      additionalProperties: false
      description: Suggested tips information.
    TransactionOperationDto:
      type: object
      description: Transaction operation information.
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/TransactionType'
        availableAmount:
          type: number
          format: double
          nullable: true
          description: >
            Indicates the maximum amount (in USD) eligible for the specified
            operation type.


            See the field `type`.


            Example: 49.99 (for $49.99)
          example: 49.99
        suggestedTips:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SuggestedTipsDto'
    AvsActionsDto:
      enum:
        - Allow
        - Deny
      type: string
      description: >
        Indicates allowing an action after address verification.


        Valid values are:


        | Status | Explanation                          |

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

        | Allow  | If address verification passes, the payment proceeds. |

        | Deny   | If address verification does not pass, the payment is denied.
        |


        Example: Allow
      example: Allow
    AvsCodeGroupTypeDto:
      enum:
        - NoMatch
        - PartialMatch
        - Incompatible
        - Unavailable
        - ValidGroup
      type: string
      description: |
        Indicates the AVS (address verification service) group type.

        Valid values are:

        | Status        | Explanation                                          |
        |---------------|------------------------------------------------------|
        | Incompatible  | The card issuer does not support this address check. |
        | NoMatch       | The billing address and postal code did not match.   |
        | PartialMatch  | One part of the billing address matched, not both.   |
        | Unavailable   | The address check result was not available.          |
        | ValidGroup    | The billing address and postal code matched.         |
    AvsResponseResultDto:
      enum:
        - Passed
        - Failed
      type: string
      description: |
        Indicates the AVS (address verification service) result.

        Valid values are:

        | Status | Explanation               |
        |--------|---------------------------|
        | Failed | The address check failed. |
        | Passed | The address check passed. |
    AvsResponseDto:
      type: object
      description: Indicates the AVS (address verification service) response.
      additionalProperties: false
      properties:
        action:
          $ref: '#/components/schemas/AvsActionsDto'
        responseCode:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the response code from processor.


            For a simplified explanation of the result, see the field
            `codeDescription`.


            Example: Y
          example: 'Y'
        codeDescription:
          type: string
          nullable: true
          description: >
            Indicates a simplified explanation of the result.


            For the actual AVS (address verification service) result, see the
            field `responseCode`.


            Example: Address and ZIP code match
          example: Address and ZIP code match
        group:
          $ref: '#/components/schemas/AvsCodeGroupTypeDto'
        result:
          $ref: '#/components/schemas/AvsResponseResultDto'
    KeyValuePairOfStringAndString:
      type: object
      properties:
        key:
          type: string
          nullable: true
          description: |
            Indicates the key of the pair.

            Example: ac
          example: ac
        value:
          type: string
          nullable: true
          description: |
            Indicates the value of the pair.

            Example: 9F26
          example: 9F26
      additionalProperties: false
    TransactionReceiptDtoEmvTagsDto:
      type: object
      additionalProperties: false
      properties:
        ac:
          type: string
          nullable: true
          description: >
            Indicates the AC (application cryptogram).


            This is the cryptographic value generated by the card chip so the
            issuer can authenticate the transaction.


            Example: A123456789ABCDEF
          example: A123456789ABCDEF
        tvr:
          type: string
          nullable: true
          description: >
            Indicates the TVR (terminal verification results).


            This is a bitmask showing which checks the terminal ran and the
            success status of each one.

            The individual checks include data authentication, cardholder
            verification, and risk management.


            Example: 0000008000
          example: '0000008000'
        tsi:
          type: string
          nullable: true
          description: >
            Indicates the TSI (transaction status information).


            This is a bitmask showing which processes were actually performed
            during the transaction.


            Example: E800
          example: E800
        aid:
          type: string
          nullable: true
          description: >
            Indicates the AID (application identifier).


            This identifies the specific card payment application on the chip,
            such as Visa Credit or Mastercard Debit.


            Example: A0000000031010
          example: A0000000031010
        applicationLabel:
          type: string
          nullable: true
          description: >
            Indicates the application Label.


            This is the human-readable name of that application, often shown on
            the terminal display.


            Example: VISA CREDIT
          example: VISA CREDIT
        rawTags:
          description: >
            Indicates the EMV chip transaction data elements, or tags. 


            Each data element is identified by its own hex tag number according
            to the EMV specifications.

            For example, the five most commonly needed ones are: ac (9F26), tvr
            (95), tsi (9B), aid (4F), and applicationLabel (50).

            An actual EMV transaction can return many more tags than that,
            sometimes with dozens of possible values.


            This tag array object contains all the returned pairings.
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/KeyValuePairOfStringAndString'
    TransactionReceiptDto:
      type: object
      description: Transaction receipt information.
      additionalProperties: false
      properties:
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        transactionDateTime:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 date-time format) of the
            transaction.


            Example: 2026-05-05T14:30:42.938Z
          example: '2026-05-05T14:30:42.938Z'
        amount:
          $ref: >-
            #/components/schemas/TransactionReceiptDtoTransactionReceiptAmountDto
        currency:
          $ref: '#/components/schemas/currencyCode'
        processorId:
          $ref: '#/components/schemas/paymentprocessorid'
        processor:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the name of the payment processor.

            Example: TSYS
          example: TSYS
        operationTypeId:
          type: integer
          format: int32
          description: |
            For internal use only.

            Do not use.
        operationType:
          type: string
          default: PayNow
          enum:
            - PayNow
            - Subscription
          description: |
            Identifies the type of the operation.

            Valid values are:

            | Item         | Explanation                           |
            |--------------|---------------------------------------|
            | PayNow       | One-time charge for a service.        |
            | Subscription | Recurring charge for ongoing service. |

            Example: PayNow
          example: PayNow
        paymentMethodTypeId:
          type: integer
          format: int32
          description: |
            For internal use only.

            Do not use.
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
        transactionTypeId:
          type: integer
          format: int32
          description: |
            For internal use only.

            Do not use.
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        customerId:
          $ref: '#/components/schemas/customerId'
        customerPan:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked card number.

            This displays only the last four numbers.

            Example: ************1111
          example: '************1111'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
        statusId:
          type: integer
          format: int32
          description: |
            For internal use only.

            Do not use.
        status:
          type: string
          nullable: true
          enum:
            - Cancelled
            - Completed
            - Created
            - Failed
          description: >
            Indicates the status of the transaction.


            Valid values are:


            | Status    |
            Explanation                                                            
            |

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

            | Cancelled | The transaction was cancelled before
            completion.                        |

            | Completed | The payment attempt finished processing. This does not
            mean the payment was approved — check `responseCode` and
            `responseDescription` on this same object to confirm approval or
            decline. |

            | Created   | The transaction was initialized but not yet
            processed.                  |

            | Failed    | The payment was attempted but did not succeed. A new
            session is needed. |


            Example: Completed
          example: Completed
        merchantName:
          type: string
          x-method: response
          description: |
            Indicates the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        merchantAddress:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the customer's company address.

            Example: 123 Main St, Suite 100, New York
          example: 123 Main St, Suite 100, New York
        merchantPhoneNumber:
          type: string
          x-method: response
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Indicates the customer's phone number.

            Example: +14155552309
          example: '+14155552309'
        merchantEmailAddress:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        merchantWebsite:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the customer's URL.

            Example: PepparedStreetCafe.example.com
          example: PepparedStreetCafe.example.com
        authCode:
          type: string
          nullable: true
          description: |
            Indicates the authorization code from the card processor.

            This authorization does not apply to tip adjustments.
            The code explicitly falls back to the original.

            Example: ABC123
          example: ABC123
        source:
          $ref: >-
            #/components/schemas/TransactionReceiptDtoTransactionReceiptSourceResponseDto
        cardholderAuthenticationMethodId:
          $ref: '#/components/schemas/CardholderAuthenticationMethodDto'
        cardholderAuthenticationMethod:
          $ref: '#/components/schemas/CardholderAuthenticationMethodDto'
        cvmResultMsg:
          type: string
          nullable: true
          description: >
            Indicates a message describing the CVM (cardholder verification
            method) the terminal attempted.


            It also indicates whether the verification succeeded or failed.


            Examples:<br>

            CVM Failed<br>

            Signature Verified
          example: Signature Verified
        cardDataSourceId:
          type: string
          description: |
            For internal use only.

            Do not use.
        cardDataSource:
          $ref: '#/components/schemas/CardDataSourceDto'
        responseCode:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the response code from processor.

            Examples:<br>
            00<br>
            051
          example: '00'
        responseDescription:
          type: string
          nullable: true
          description: >
            Indicates a human-readable message that explains the response and
            response code.


            Examples:<br>

            Approved or completed successfully<br>

            Declined - Do Not Honor
          example: Declined - Do Not Honor
        cardProcessingDetails:
          $ref: '#/components/schemas/TransactionReceiptDtoCardDetailsDto'
        achProcessingDetails:
          $ref: '#/components/schemas/TransactionReceiptDtoElectronicCheckDetails'
        availableOperations:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/TransactionOperationDto'
        avsResponse:
          $ref: '#/components/schemas/AvsResponseDto'
        emvTags:
          $ref: '#/components/schemas/TransactionReceiptDtoEmvTagsDto'
        orderNumber:
          type: string
          nullable: true
          description: >
            Indicates a merchant-assigned order or invoice identifier associated
            to the transaction.


            Example: ORD-4521
          example: ORD-4521
    baseAmount:
      type: number
      format: double
      nullable: true
      multipleOf: 0.01
      minimum: 0.01
      x-method: response
      description: |
        Identifies the base transaction amount (in USD) before adjustments.
          
        Examples:<br>
        125<br>
        125.5<br>
        125.50
      example: 125.5
    AmountDto:
      type: object
      properties:
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        percentageOffAmount:
          type: number
          format: double
          description: >
            Identifies the discount amount (in USD) taken off.


            This discount was calculated using the preset percentage from
            `percentageOffRate`.


            Example: 12.50
          example: 12.5
        percentageOffRate:
          type: number
          format: double
          description: >
            Identifies the discount percentage.


            This value is percentage rate for the discount.

            This discount percentage calculates the discount amount for
            `percentageOffAmount`.


            Example: 3.5 (as 3.5%)
          example: 3.5
        cashDiscountAmount:
          type: number
          format: double
          description: |
            Identifies the cash discount amount (in USD) taken off.

            Example: 12.50 (for $12.50)
          example: 12.5
        cashDiscountRate:
          type: number
          format: double
          description: >
            Identifies the discount percentage for a cash (or cash-equivalent)
            discount.


            Example: 1.5 (for 1.5%)
          example: 1.5
        surchargeAmount:
          type: number
          format: double
          x-method: response
          description: >
            Specifies the surcharge amount (in USD) applied.


            Care must be taken that a value other than zero can be provided to
            either `surchargeAmount` or `surchargeRate`.

            A non-zero value cannot be provided to both.


            Example: 22 (for $22)
          example: 22
        surchargeRate:
          type: number
          format: double
          description: >
            Indicates the percent of transaction amount.


            This value is added to the base amount after `PercentageOffRate` has
            been applied.


            Care must be taken that a value other than zero can be provided to
            either `surchargeAmount` or `surchargeRate`.

            A non-zero value cannot be provided to both.


            Example: 2.5 (for 2.5%)
          example: 2.5
        tipAmount:
          type: number
          multipleOf: 0.01
          format: double
          description: >
            Indicates the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          description: >
            Indicates a percentage of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
        taxAmount:
          type: number
          format: double
          x-method: request/response
          nullable: true
          description: |
            Indicates the tax amount established on a product.

            Example: 3.75 (for 3.75%)
          example: 3.75
        taxRate:
          type: number
          format: double
          minimum: 0
          maximum: 22
          x-method: request
          nullable: true
          description: |
            Indicates the default level 2 autoFill sales tax rate.

            Examples:<br>
            5.0 (for 5.0%)<br>
            8.5 (for 8.5%)<br>
            10.25 (for 10.25%)
          example: 8.5
        totalAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          description: |
            Indicates the final total amount (in USD).

            Example: 124.99
          example: 124.99
    GetPaymentSessionTransactionDetailsDto:
      type: object
      properties:
        transactionReceiptUrl:
          type: string
          nullable: true
          description: >
            Indicates the direct URL link to the transaction receipt.


            Example:
            https://receipts.flute.com/r/90d084d6-55b8-4fb8-b658-861534d07f9a
          example: https://receipts.flute.com/r/90d084d6-55b8-4fb8-b658-861534d07f9a
        transactionReceiptShortUrl:
          type: string
          nullable: true
          description: |
            Indicates the shortened direct URL link to the transaction receipt.

            Example: "https://s.flute.com/745iZYxF83t"
          example: https://s.flute.com/745iZYxF83t
        source:
          $ref: '#/components/schemas/TransactionSourceResponseDto'
        transactionReceipt:
          $ref: '#/components/schemas/TransactionReceiptDto'
        id:
          type: string
          format: uuid
          description: |
            Indicates the payment method identifier.

            This is the identifier of a previously saved ACH account to charge.

            Example: 39a95e35-6d50-45ec-884b-c2417edf005d
          example: 39a95e35-6d50-45ec-884b-c2417edf005d
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        date:
          type: string
          format: date-time
          nullable: true
          description: >
            Indicates the date-time (in an ISO 8601 date-time format) of the
            transaction.


            Example: 2025-02-19T20:24:52.934Z
          example: '2025-02-19T20:24:52.934Z'
        amount:
          $ref: '#/components/schemas/AmountDto'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        createdBy:
          type: string
          nullable: true
          description: |
            Indicates the creator of the transaction.

            Example: Alexandro Peppared
          example: Alexandro Peppared
        merchant:
          type: string
          x-method: response
          description: |
            Indicates the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        processorId:
          $ref: '#/components/schemas/paymentprocessorid'
        processor:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the name of the payment processor.

            Example: TSYS
          example: TSYS
        operationMode:
          $ref: '#/components/schemas/PaymentMethodType'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
        paymentMethodName:
          type: string
          nullable: true
          description: >
            Indicates the name of the payment method.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Cafe Peppared Payments
          example: Cafe Peppared Payments
        customerId:
          $ref: '#/components/schemas/customerId'
        customerName:
          type: string
          nullable: true
          description: |
            Indicates the name of the customer's company or organization.

            Example: Alexandro Peppared
          example: Alexandro Peppared
        customerCompany:
          type: string
          nullable: true
          description: |
            Indicates the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
        customerPan:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked card number.

            This displays only the last four numbers.

            Example: ************1111
          example: '************1111'
        customerEmail:
          type: string
          nullable: true
          description: |
            Indicates the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
    GetPaymentSessionResponseDto:
      type: object
      description: Response DTO for getting payment session details.
      additionalProperties: false
      properties:
        status:
          type: string
          nullable: true
          readOnly: true
          description: >
            Indicates the payment session status.


            Valid values:


            | Status    | Description |

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

            | Created   | Payment session was initialized but not yet processed.
            |

            | Completed | Payment session was completed. Check transaction
            details to verify if the payment was approved or not. |

            | Cancelled | Payment session was cancelled before completion. |

            | Expired   | Payment session expired before being completed. |

            | Failed    | Payment was attempted but did not succeed. A new
            session must be created for a new payment attempt. |


            Example: Created
          example: Created
        mode:
          $ref: '#/components/schemas/SessionMode'
        skipAddressVerification:
          type: boolean
          default: false
          description: >
            Indicates to bypass the AVS (address verification service) in the
            payment gateway.


            This value is applicable only to `Payment` and `PaymentAndSave` from
            `mode`.


            If `true`, bypasses AVS in the payment gateway.<br>

            If `false`, does not bypass AVS in the payment gateway.


            Example: true
          example: true
        customerId:
          $ref: '#/components/schemas/customerId'
        vaultedPaymentMethodId:
          type: string
          format: uuid
          nullable: true
          description: >
            Indicates the identifier of the vaulted payment method when the
            session involves saving or using a stored payment method.


            Example: 990a65f4-519c-44f9-a615-fc9c7781190c
          example: 990a65f4-519c-44f9-a615-fc9c7781190c
        referenceId:
          type: string
          x-method: response
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Indicates a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        tipAmount:
          type: number
          format: double
          nullable: true
          multipleOf: 0.01
          description: |
            Indicates the absolute amount (in USD) of the tip to be added.

            If this value is provided, it must be greater than zero.

            Example: 14.50 (for $14.50)
          example: 14.5
        checkoutUrl:
          type: string
          nullable: true
          description: >
            Indicates full URL of the hosted checkout page for this payment
            session.


            Example:
            https://api.payments.flute.com/xOut/sessions/session-complete.html
          example: https://api.payments.flute.com/xOut/sessions/session-complete.html
        checkoutUrlShort:
          type: string
          nullable: true
          description: >
            Indicates the shortened URL of the hosted checkout page for this
            payment session.


            Example: https://smallurl.com/4kxm9p2
          example: https://smallurl.com/4kxm9p2
        successUrl:
          type: string
          nullable: true
          description: >
            Indicates the URL to redirect the payer to after a successful
            payment.


            This value is not needed if using Flute Elements and Flute Checkout.


            Example:
            https://api.payments.flute.com/xOut/sessions/session-complete.html
          example: https://api.payments.flute.com/xOut/sessions/session-complete.html
        paymentMethodTypes:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Indicates payment methods to be shown at checkout.

            Valid values are:

            | Payment method | Type |
            |----------------|------|
            | Card           | Credit or debit card payment |
            | ACH            | ACH (automated clearing house) payment |

            Example: Card
          example: Card
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
            nullable: true
          description: >
            Indicates arbitrary key-value pairs to attach to the payment session
            object.


            These values are used to store supplemental information.

            They are not functionally used in this endpoint.

            Instead, they are included while retrieving the payment session.

            This allows additional notes to be passed along to the operator.


            Pass null to clear all metadata.


            Examples:<br>

            [ {"orderId": "9921"} ]<br>

            [ {"Guest notes": "Member of The World of Hyatt Credit Card."} ]<br>

            [{"orderId": "9921"}, {"Guest notes": "Member of The World of Hyatt
            Credit Card."}]
          example:
            - orderId: '9921'
            - Guest notes: Member of The World of Hyatt Credit Card.
        afterCompletionMessage:
          type: string
          nullable: true
          description: >
            Specifies a message shown to the payer after the payment session
            completes.


            This value is not needed if using Flute Elements and Flute Checkout.


            Example: Thank you for shopping with us.
          example: Thank you for shopping with us.
        pageName:
          type: string
          nullable: true
          description: >
            Specifies the display name shown on the checkout page.


            This is a free-formed name that is convenient for the merchant to
            recognize. 


            Example: Peppared Street Cafe's Preferred Payment
          example: Peppared Street Cafe's Preferred Payment
        isMultiUse:
          type: boolean
          description: >
            Specifies the checkout URL can be used for multiple payments.


            This value is applied only if using Flute Elements or Flute
            Checkout.


            If `true`, the checkout URL can be used for multiple payments.<br>

            If `false`, the checkout URL cannot be used for multiple payments.


            Example: true
          example: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: >
            Specifies the expiration timestamp (in an ISO 8601 date-time UTC
            format) for the payment session.


            The time must be in the future.


            Example: 2026-02-19T20:24:52.934Z
          example: '2026-02-19T20:24:52.934Z'
        paymentNotes:
          type: string
          nullable: true
          description: |
            Specifies additional notes shown to the payer on the checkout page.

            Example: The client's server is being repaired.
          example: The client's server is being repaired.
        achAccountLast2:
          type: string
          nullable: true
          description: >
            Indicates the last two digits of an ACH (automated clearing house)
            bank account number.


            Example: 84
          example: '84'
        achRoutingLast2:
          type: string
          nullable: true
          description: >
            Indicates the last two digits of an ACH (automated clearing house)
            bank routing number.


            Example: 62
          example: '62'
        surchargeAmount:
          type: number
          format: double
          x-method: response
          description: |
            Specifies the surcharge amount (in USD) applied.

            Example: 18.45 (for $18.45)
          example: 18.45
        transactionDetails:
          $ref: '#/components/schemas/GetPaymentSessionTransactionDetailsDto'
    PosDeviceId:
      type: string
      minLength: 1
      maxLength: 36
      x-method: response
      nullable: true
      description: |
        Indicates the external POS terminal identifier.

        Example: POS-DEVICE-001
      example: POS-DEVICE-001
    PosTransactionStatus:
      enum:
        - Cancelled
        - Completed
        - Failed
        - InProgress
      type: string
      x-method: response
      description: >
        Indicates the status of the transaction.


        Valid values are:

        | Value       |
        Description                                                |

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

        | Cancelled   | The POS transaction was canceled before it
        completed.      |

        | Completed   | The POS transaction finished processing
        successfully.      |

        | Failed      | The POS transaction did not complete because of an
        error.  |

        | InProgress  | The POS transaction is still being
        processed.              |


        Example: Completed
      example: Completed
    CaptureMethod:
      enum:
        - Auto
        - Manual
      type: string
      x-method: request/response
      description: >
        Identifies the capture method.


        Capture is the step that converts an authorization, funds reserved
        before a transaction, into an actual charge or funds captured for
        settlement.


        Possible values:


        | Value  | Description |

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

        | Auto   | The transaction is captured automatically at the same time as
        authorization or immediately after, with no separate action required. |

        | Manual | The transaction has been authorized. However, an explicit
        capture request must be made later to actually allocate the
        money.<br><br>Care must be taken because if the transaction is never
        captured, the authorization simply expires and no funds move.   |


        Example: Auto
      example: Auto
    processedAmount:
      type: number
      format: double
      multipleOf: 0.01
      x-method: response
      nullable: true
      description: |
        Indicates the transaction amount (in USD).

        The value will be null until the transaction is completed.

        Example: 87.39
      example: 87.39
    ExtraAmountsDto:
      type: object
      description: >
        Identifies the extra amounts for the transaction.


        To accept tips, the merchant is required to have tips enabled and
        tip-adjustment disabled.

        If tip collection is enabled and committed at creation time, the tip
        gets prompted to the customer directly on the device.
      properties:
        tipAmount:
          type: number
          format: double
          x-method: request/response
          nullable: true
          multipleOf: 0.01
          minimum: 0.01
          description: >
            Identifies the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            If the tip collection is enabled on the merchant settings and
            committed during POS transaction creation, the tip will be prompted
            to the customer directly on the device.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          x-method: request/response
          description: >
            Identifies a tip percentage to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
        discountAmount:
          type: number
          format: double
          multipleOf: 0.01
          minimum: 0.01
          x-method: response
          description: >
            Identifies the absolute amount (in USD) of discount to be applied.


            If this value is provided, it must be greater than zero.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `discountAmount` or `discountRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 25 (for $25)
          example: 25
        discountRate:
          type: number
          format: double
          x-method: response
          description: >
            Identifies a percentage of a discount to be applied.


            If this value is provided, it must be greater than zero.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `discountAmount` or `discountRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 5.5 (for 5.5%)
          example: 5.5
        surchargeRate:
          type: number
          format: double
          description: |
            Identifies the percent of transaction amount.

            Example: 2.5 (for 2.5%)
          example: 2.5
      additionalProperties: false
    ListPosTransactionsResponseDto:
      type: object
      properties:
        posTransactionId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the POS transaction identifier.

            Example: 8be0aa51-eae6-4c30-a558-8579f3832f98
          example: 8be0aa51-eae6-4c30-a558-8579f3832f98
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            POS payment was created on.


            Example: 2026-01-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
        modifiedOn:
          type: string
          description: Timestamp of the last POS transaction modification.
          format: date-time
          example: '2026-05-05T14:31:15Z'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        customerId:
          $ref: '#/components/schemas/customerId'
        terminalId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the identifier of terminal handling the POS transaction.

            Example: d0fc1606-47ea-464b-a31a-3971c9822d10
          example: d0fc1606-47ea-464b-a31a-3971c9822d10
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        posDeviceId:
          $ref: '#/components/schemas/PosDeviceId'
        referenceId:
          type: string
          x-method: response
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Indicates a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        posTransactionStatus:
          $ref: '#/components/schemas/PosTransactionStatus'
        captureMethod:
          $ref: '#/components/schemas/CaptureMethod'
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the identifier of an attached transaction.

            This value is available after processing.

            Example: a62fa6a1-8a2a-44f9-983d-c757017d4b66
          example: a62fa6a1-8a2a-44f9-983d-c757017d4b66
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        extraAmounts:
          $ref: '#/components/schemas/ExtraAmountsDto'
      additionalProperties: false
    PageOfListPosTransactionsResponseDto:
      type: object
      properties:
        items:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/ListPosTransactionsResponseDto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    PricingType:
      enum:
        - Card
        - Cash
      type: string
      description: >
        Identifies the type of pricing.


        This value is only relevant when Dual Pricing is enabled.


        Valid values are:


        | Status |
        Explanation                                                            
        |

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

        | Card   | The transaction uses the card price, which may include a
        surcharge.     |

        | Cash   | The transaction uses the cash price, which may include a cash
        discount. |


        Example: Card
      example: Card
    PosTransactionReadingMethod:
      enum:
        - KeyedEntry
        - Regular
      type: string
      description: >
        Specifies the POS terminal reading type.


        Valid Values are:


        | Method     | Explanation                               |

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

        | KeyedEntry | Card details are entered manually on the terminal. |

        | Regular    | Card details are read by the device, such as by tap,
        insert, or swipe. |


        Example: Regular
      example: Regular
    CreatePosTransactionRequestDto:
      type: object
      required:
        - posDeviceId
        - baseAmount
        - currencyCode
        - terminalId
        - waitForAcceptanceByTerminal
      properties:
        posDeviceId:
          type: string
          minLength: 1
          maxLength: 36
          x-method: request
          nullable: true
          description: |
            Specifies the external POS terminal identifier.

            Example: POS-DEVICE-001
          example: POS-DEVICE-001
        baseAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          nullable: true
          description: |
            Specifies the transaction amount (in USD).

            <span class="note">
            Required when the `TransactionType` is any of the following:

            | Transaction Type | Notes |
            |------------------|-------|
            | Authorization    | |
            | Capture          | |
            | Refund           | |
            | RefundWORef      | Refund without reference |
            | Sale             | |
            | TipAdjustment    | |

            </span>

            Examples:<br>
            125<br>
            125.5<br>
            125.50
          example: 125.5
        currencyCode:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the transaction's currency code (in ISO 4217 currency
            code).


            <span class="note">

            Required when the <code>TransactionType</code> is any of the
            following:


            | Transaction Type | Description |

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

            | Authorization    | |

            | Capture          | |

            | Refund           | |

            | RefundWORef      | Refund without reference |

            | Sale             | |

            | TipAdjustment    | |


            </span> 


            Example: USD
          example: USD
        terminalId:
          type: string
          format: uuid
          x-method: request
          description: >
            Specifies the terminal identifier that handles the transaction.


            The terminal must be in semi-integrated mode and available (online
            and ready).

            A semi-integrated terminal is one that is connected to a POS system,
            typically through a network or cable.


            Example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
          example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
        waitForAcceptanceByTerminal:
          type: boolean
          x-method: request
          description: >
            Specifies the response mode is either short or long polling.


            If `true`, specifies long polling. HTTP response will be provided
            once the terminal accepts or declines to initiate the transaction or
            a timeout happens (terminal does not respond).<br>

            If `false`, specifies short polling. HTTP response will be returned
            immediately, while the terminal is still receiving the transaction
            request.


            After either case, use `GET
            /v2/pos/transactions/{{posTransactionId}}` to retrieve the latest
            information of the transaction submission.


            Polling refers to how the POS application checks Flute for the
            status or result of a payment after initiating it.

            The choice is mainly about how quickly the final transaction status
            is needed and how much repeated traffic can be tolerated.


            **Short polling**<br>

            The POS application repeatedly sends separate status requests at
            short intervals.

            This checks for the completion status of the transaction.

            Each request gets an immediate response, and the POS application
            keeps asking until the transaction reaches a final state or times
            out.

            Short polling is useful when the POS application can itself
            periodically check status instead of maintaining an open request.

            Examples include checking whether an earlier transaction eventually
            completed, recovering after a connection interruption, or
            reconciling a transaction whose final state is uncertain.


            **Long polling**<br>

            The POS application sends a status request, and Flute holds that
            request open while waiting for the transaction state to change.

            Once there’s a result or the request times out, Flute responds.

            The POS application can then open another long-poll request if
            necessary.

            Long polling is useful when the POS application is actively waiting
            for a transaction to complete.

            For example, the customer has tapped their card and the POS
            application is waiting to show whether the payment was approved or
            declined.

            The request stays open until there’s a status change or timeout, so
            customers get a quick result without the application constantly
            making new requests.


            Example: true
          example: true
        requestPaymentMethodStorageConsent:
          type: boolean
          default: false
          x-method: request
          description: >
            Specifies displaying a message confirming saving the customer
            payment method information on the terminal.


            If `true`, display a message confirming saving the customer payment
            method.<br>

            If `false`, does not display a message confirming saving the
            customer payment method.


            Example: true
          example: true
        extraAmounts:
          $ref: '#/components/schemas/ExtraAmountsDto'
        referenceId:
          type: string
          x-method: request
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Specifies a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        customerId:
          $ref: '#/components/schemas/customerId'
        pricingType:
          $ref: '#/components/schemas/PricingType'
        captureMethod:
          $ref: '#/components/schemas/CaptureMethod'
        readingMethod:
          $ref: '#/components/schemas/PosTransactionReadingMethod'
      additionalProperties: false
    AggregatedTransactionStatus:
      enum:
        - Authorized
        - Captured
        - Voided
        - Refunded
        - Verified
        - Settled
        - PartiallyAuthorized
        - Informational
        - Scheduled
        - Cancelled
        - ChargedBack
        - InProgress
        - Cleared
        - Held
        - HeldByProcessor
        - Pending
        - Declined
        - Failed
      type: string
      description: >
        Indicates the aggregated transaction status.


        Valid values are:


        | Status                |
        Description                                        |

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

        | Authorized            | Payment approved but funds not yet
        captured.        |

        | Cancelled             | Transaction stopped before it
        completed.            |

        | Captured              | Approved funds collected from the
        card.             |

        | ChargedBack           | Cardholder disputed the charge with their
        bank.     |

        | Cleared               | Funds finished processing and
        settled.              |

        | Declined              | Payment rejected by the bank or
        processor.          |

        | Failed                | Transaction could not complete due to an
        error.     |

        | Held                  | Transaction paused and awaiting
        release.            |

        | HeldByProcessor       | Processor paused the transaction for
        review.        |

        | Informational         | Record used for reference only, not a live
        charge.  |

        | InProgress            | Transaction is still
        processing.                    |

        | PartiallyAuthorized   | Only part of the requested amount was
        approved.     |

        | Pending               | Transaction is waiting for a
        result.                |

        | Refunded              | Funds returned to the
        cardholder.                   |

        | Scheduled             | Transaction set to run at a future
        time.            |

        | Settled               | Funds moved from issuer to the merchant
        account.    |

        | Verified              | Card or account confirmed as
        valid.                 |

        | Voided                | Authorization cancelled before
        capture.             |


        Example: Authorized
      example: Authorized
    TransactionDetailEventType:
      enum:
        - Authorization
        - Sale
        - Capture
        - Void
        - Refund
        - TipAdjustment
        - CardAuthentication
        - Hold
        - UnHold
        - Credit
        - Settle
      type: string
      description: >
        Indicates the possible event types.


        Valid values are:

        | Type               |
        Description                                        |

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

        | Authorization      | Authorizes the
        transaction.                        |

        | Capture            | Collects funds from an approved
        authorization.     |

        | CardAuthentication | Confirms cardholder identity before
        payment.       |

        | Credit             | Sends funds back to a cardholder outside a
        refund. |

        | Hold               | Pauses a transaction or account
        temporarily.       |

        | Refund             | Returns funds for a completed
        sale.                |

        | Sale               | Authorizes and captures payment in one
        step.       |

        | Settle             | Submits a batch for final
        processing.              |

        | TipAdjustment      | Adds or changes a tip after the
        sale.              |

        | UnHold             | Removes a hold and resumes normal
        activity.        |

        | Void               | Cancels a transaction before it
        settles.           |


        Example: Capture
      example: Capture
    referenceId:
      type: string
      x-method: response
      nullable: true
      minLength: 0
      maxLength: 36
      description: >
        Indicates a reference identifier provided by the merchant.


        This is included in the duplicate-check key.

        It allows the same card and amount combination to be charged multiple
        times when the reference identifiers are different.


        Example: REF-EXT-12345
      example: REF-EXT-12345
    originalTransactionId:
      type: string
      format: uuid
      x-method: response
      description: >
        Indicates the original transaction identifier.


        This value will be provided if the current transaction is a card
        refund.<br>

        Otherwise, it will be null or omitted.


        Example: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92
      example: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92
    AchSECCode:
      enum:
        - Web
        - PPD
        - CCD
      type: string
      description: |
        Indicates the ACH SEC (standard entry class) code.

        Valid values are:

        | Code      | Description                                          |
        |-----------|------------------------------------------------------|
        | CCD       | Used for business to business payments.              |
        | PPD       | Used for consumer payments like payroll or bill pay. |
        | Web       | Used for a payment authorized on a website.          |

        Example: CCD
      example: CCD
    processorDetails:
      type: object
      properties:
        mid:
          type: string
          nullable: true
          description: |
            Indicates the MID (merchant identifier) assigned by the processor.

            Example: 932129304958123
          example: 932129304958123
        tid:
          type: string
          nullable: true
          description: |
            Indicates the TID (terminal identifier) assigned by the processor.

            example: 6095275263
          example: 6095275263
        authCode:
          type: string
          nullable: true
          description: |
            Indicates the authorization code returned by the processor.

            Example: VTLMC1
          example: VTLMC1
        rrn:
          type: string
          nullable: true
          description: >
            Indicates the RRN (retrieval reference number) returned by the
            processor.


            Example: 59d5df1aa58d4de3969175eeece571c1
          example: 59d5df1aa58d4de3969175eeece571c1
      additionalProperties: false
      description: Payment processor identifiers for a transaction.
    TransactionAddressVerificationServiceResponseDto:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/AvsActionsDto'
        responseCode:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the AVS (address verification service) response code from
            processor.


            Example: A
          example: 'Y'
        description:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the description of the AVS (address verification service)
            result code description.


            Example: Address and ZIP match
          example: Address and ZIP match
      additionalProperties: false
      description: >-
        Indicates the AVS (address verification service) response for card
        payments.
    TransactionStatus:
      enum:
        - Pending
        - Approved
        - Declined
        - Failed
      type: string
      description: |
        Indicates the transaction status.

        Valid values are:

        | Status    | Description                             |
        |-----------|-----------------------------------------|
        | Approved  | Payment passed checks. Funds will move. |
        | Declined  | Bank or card issuer rejected payment.   |
        | Failed    | Payment attempt ended in error.         |
        | Pending   | Payment is waiting for a result.        |

        Example: Approved
      example: Approved
    linkedTransaction:
      type: object
      description: |
        Indicates an object detailing the related POS transaction.

        This value will be null until the transaction is completed.
      properties:
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        transactionDateTime:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the timestamp (in an ISO 8601 date-time format) of the
            transaction.


            Example: 2026-05-05T14:30:42.938Z
          example: '2026-05-05T14:30:42.938Z'
        transactionStatus:
          $ref: '#/components/schemas/AggregatedTransactionStatus'
        transactionType:
          $ref: '#/components/schemas/TransactionDetailEventType'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
        referenceId:
          $ref: '#/components/schemas/referenceId'
        originalTransactionId:
          $ref: '#/components/schemas/originalTransactionId'
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        refundDetails:
          type: object
          properties:
            refundedAmount:
              type: number
              format: double
              multipleOf: 0.01
              description: >
                Indicates the total amount (in USD) already refunded against
                this transaction.


                Examples:<br>

                56.99<br>

                0
              example: 0
            availableRefundAmount:
              type: number
              format: double
              multipleOf: 0.01
              description: |
                Indicates the amount (in USD) still refundable.

                Example: 120.99
              example: 120.99
            isFullyRefunded:
              type: boolean
              description: |
                Indicates the amount has been fully refunded.

                If `true`, the amount has been fully refunded.<br>
                If `false`, the amount has not been fully refunded.

                Example: true
              example: true
          additionalProperties: false
          description: >
            Indicates an object detailing the refund posture for a transaction
            that can be refunded.


            This value is null on transactions that are themselves refunds or
            credits.

            Those cannot be refunded again.
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        pricingType:
          $ref: '#/components/schemas/PricingType'
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        customerId:
          $ref: '#/components/schemas/customerId'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        batchId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the batch settlement identifier.

            Example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6
          example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6
        amountBreakdown:
          type: object
          properties:
            baseAmount:
              $ref: '#/components/schemas/baseAmount'
            tipAmount:
              type: number
              format: double
              nullable: true
              multipleOf: 0.01
              description: >
                Indicates the absolute amount (in USD) of the tip to be added.


                If this value is provided, it must be greater than zero.


                This amount adds to the base amount of the original transaction.

                That transaction must be authorized first (`POST
                /pay-api/v1/transactions/auth`).


                Example: 14.50 (for $14.50)
              example: 14.5
            tipRate:
              type: number
              format: double
              x-method: response
              description: >
                Indicates a percentage of the tip to be added.


                If this value is provided, it must be greater than zero.


                This amount adds to the base amount of the original transaction.

                That transaction must be authorized first (`POST
                /pay-api/v1/transactions/auth`).


                <br><span class="note">

                Care must be taken that a value other than zero can be provided
                to either `tipAmount` or `tipRate`.

                A non-zero value cannot be provided to both.

                </span><br>


                Example: 18.50 (for 18.50%)
              example: 18.5
            surchargeAmount:
              type: number
              format: double
              multipleOf: 0.01
              x-method: response
              description: >
                Indicates the surcharge amount (in USD) applied.


                <br><span class="note">

                Care must be taken that a value other than zero can be provided
                to either `surchargeAmount` or `surchargeRate`.

                A non-zero value cannot be provided to both.

                </span><br>


                Example: 22 (for $22)
              example: 22
            surchargeRate:
              type: number
              format: double
              description: >
                Indicates the percent of transaction amount.


                This value is added to the base amount after `PercentageOffRate`
                has been applied.


                <br><span class="note">

                Care must be taken that a value other than zero can be provided
                to either `surchargeAmount` or `surchargeRate`.

                A non-zero value cannot be provided to both.

                </span><br>


                Example: 2.5 (for 2.5%)
              example: 2.5
            discountAmount:
              type: number
              format: double
              multipleOf: 0.01
              x-method: response
              description: >
                Indicates the absolute amount (in USD) of discount to be
                applied.


                If this value is provided, it must be greater than zero.


                This does not include ZCP (zero cost processing) cash-discount
                amounts.


                <br><span class="note">

                Care must be taken that a value other than zero can be provided
                to either `discountAmount` or `discountRate`.

                A non-zero value cannot be provided to both.

                </span><br>


                Example: 25 (for $25)
              example: 25
            discountRate:
              type: number
              format: double
              x-method: response
              description: >
                Indicates a percentage of a discount to be applied.


                If this value is provided, it must be greater than zero.


                This does not include ZCP (zero cost processing) cash-discount
                amounts.


                <br><span class="note">

                Care must be taken that a value other than zero can be provided
                to either `discountAmount` or `discountRate`.

                A non-zero value cannot be provided to both.

                </span><br>


                Example: 5.5 (for 5.5%)
              example: 5.5
          additionalProperties: false
          description: |
            Indicates an object detailing the amount breakdown details.
        cardDetails:
          type: object
          description: >
            Indicates an object detailing card details exposed on transaction
            responses (masked or non-sensitive fields only).
          properties:
            paymentMethodId:
              $ref: '#/components/schemas/paymentMethodIdResponse'
            maskedCardNumber:
              type: string
              nullable: true
              x-method: response
              description: |
                Indicates the masked card number.

                This displays only the last four numbers.

                Example: ************1111
              example: '************1111'
            cardBrand:
              $ref: '#/components/schemas/CardType'
            cardType:
              $ref: '#/components/schemas/CreditDebitType'
            cardProcessedAsType:
              $ref: '#/components/schemas/CreditDebitType'
            cardDataSource:
              $ref: '#/components/schemas/CardDataSourceDto'
            cardholderVerificationMethod:
              $ref: '#/components/schemas/CardholderAuthenticationMethodDto'
            emvTags:
              $ref: '#/components/schemas/TransactionReceiptDtoEmvTagsDto'
          additionalProperties: false
        achDetails:
          type: object
          properties:
            paymentMethodId:
              $ref: '#/components/schemas/paymentMethodIdResponse'
            maskedAccountNumber:
              type: string
              nullable: true
              x-method: response
              description: |
                Indicates the masked ACH account number.

                This displays only the last four numbers.

                Example: ************1111
              example: '************1111'
            accountRoutingNumber:
              type: string
              nullable: true
              x-method: request
              description: |
                Specifies the ACH's account routing number.

                Example: 021000021
              example: '021000021'
            accountHolderType:
              $ref: '#/components/schemas/AccountHolderType'
            accountType:
              $ref: '#/components/schemas/AccountType'
            secCode:
              $ref: '#/components/schemas/AchSECCode'
            isSameDayProcessing:
              type: boolean
              nullable: true
              x-method: request
              description: >
                Indicates same-day ACH processing for faster settlement.


                If `true`, the transaction uses the same-day ACH processing.<br>

                If `false`, the transaction does not use the same-day ACH
                processing.<br>

                If null or omitted, the default standard ACH processing is
                used..


                Example: true
              example: true
            requesterIpAddress:
              maxLength: 45
              minLength: 0
              type: string
              x-method: request
              description: >
                Specifies the IP address of the end user.


                Valid IP address formats are:<br>

                IPv4<br>

                IPv6 format3


                This end user may be the customer, operator, or application
                responsible for submitting the transaction.

                This is required for audit and fraud-detection purposes.


                Example: 192.168.1.1
              example: 192.168.1.1
          additionalProperties: false
          description: >-
            ACH account details exposed on transaction responses (masked or
            non-sensitive fields only).
        processorDetails:
          $ref: '#/components/schemas/processorDetails'
        declineDetails:
          type: object
          description: |
            Indicates an object detailing a declined or failed transaction.
            This value is null when the transaction was approved or is pending.
          properties:
            code:
              type: string
              nullable: true
              description: >
                Indicates the decline or failure code from the processor or
                gateway.


                Example: 41
              example: 41
            message:
              type: string
              nullable: true
              description: |
                Indicates a human-readable decline or failure message.

                Example: HOLD-CALL
              example: HOLD-CALL
          additionalProperties: false
        addressVerificationServiceResponse:
          $ref: >-
            #/components/schemas/TransactionAddressVerificationServiceResponseDto
        transactionEvents:
          type: array
          items:
            type: object
            properties:
              type:
                enum:
                  - Authorization
                  - Sale
                  - Capture
                  - Void
                  - Refund
                  - TipAdjustment
                  - CardAuthentication
                  - Hold
                  - UnHold
                  - Credit
                  - Settle
                type: string
                description: >
                  Indicates the transaction types.


                  Valid values are:

                  | Value               |
                  Description                                                              
                  |

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

                  | Authorization       | The transaction reserved funds for a
                  later capture.                       |

                  | CardAuthentication  | The transaction confirmed the identity
                  of the cardholder.                 |

                  | Capture             | The transaction collected funds from
                  an earlier authorization.            |

                  | Credit              | The transaction sent funds to the
                  payment method without a prior charge.  |

                  | Hold                | The transaction placed a temporary
                  hold on funds.                         |

                  | Refund              | The transaction returned funds from an
                  earlier charge.                    |

                  | Sale                | The transaction authorized and
                  captured funds together.                   |

                  | Settle              | The transaction submitted a batch for
                  final processing.                   |

                  | TipAdjustment       | The transaction changed the tip amount
                  on a prior charge.                 |

                  | UnHold              | The transaction released a prior hold
                  on funds.                           |

                  | Void                | The transaction canceled a charge
                  before settlement.                      |


                  Example: Credit
                example: Credit
              status:
                $ref: '#/components/schemas/TransactionStatus'
              amount:
                type: number
                format: double
                minimum: 0.01
                multipleOf: 0.01
                nullable: true
                description: >
                  Specifies the base amount (in USD) to charge.


                  For payment sessions (mode of either `SaveMethod` or
                  `PaymentAndSave`), this value must be greater than zero.

                  For vault-only payment sessions (mode of `SaveMethod`), this
                  value must be zero.

                  A value of null creates a flexible-amount payment session
                  where the amount is set at checkout.


                  Examples:<br>

                  64.99<br>

                  0<br>

                  null
                example: 64.99
              dateTime:
                type: string
                format: date-time
                x-method: response
                description: >
                  Indicates the date-time (in an ISO 8601 date-time format) of
                  the event.


                  Example: 2026-05-05T14:30:42.938Z
                example: '2026-05-05T14:30:42.938Z'
              originalTransactionId:
                $ref: '#/components/schemas/originalTransactionId'
              declineDetails:
                type: object
                description: >
                  Indicates an object detailing a declined or failed
                  transaction.

                  This value is null when the transaction was approved or is
                  pending.
                properties:
                  code:
                    type: string
                    nullable: true
                    description: >
                      Indicates the decline or failure code from the processor
                      or gateway.


                      Example: 41
                    example: 41
                  message:
                    type: string
                    nullable: true
                    description: |
                      Indicates a human-readable decline or failure message.

                      Example: HOLD-CALL
                    example: HOLD-CALL
                additionalProperties: false
            additionalProperties: false
        source:
          type: object
          description: |
            Indicates an object describing the origination of the transaction.
          properties:
            sourceType:
              enum:
                - Portal
                - ApiKey
                - Terminal
                - Invoice
                - QuickPayment
                - WebComponent
                - Subscription
                - MobileApp
                - TapToPay
              type: string
              description: >
                Indicates the source of the transaction.


                Valid values are:

                | Value         |
                Description                                                       
                |

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

                | ApiKey        | An external application created the
                transaction using an API key.  |

                | Invoice       | A billed invoice created the
                transaction.                          |

                | MobileApp     | A mobile application created the
                transaction.                      |

                | Portal        | A staff member created the transaction through
                the web portal.     |

                | QuickPayment  | A one-time payment link created the
                transaction.                   |

                | Subscription  | A recurring subscription created the
                transaction.                  |

                | TapToPay      | A mobile device using tap to pay created the
                transaction.          |

                | Terminal      | A physical payment terminal created the
                transaction.               |

                | WebComponent  | An embedded web component created the
                transaction.                 |


                Example: QuickPayment
              example: QuickPayment
            sourceId:
              type: string
              format: uuid
              nullable: true
              description: |
                Indicates the Identifier of the originating entity.

                Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            sourceName:
              type: string
              nullable: true
              description: |
                Indicates a human-readable name of the originator.

                Example: API Key for ecommerce app
              example: API Key for ecommerce app
          additionalProperties: false
    CreatePosTransactionResponseDto:
      type: object
      properties:
        posTransactionId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the POS transaction identifier.

            Example: f77b4b4d-2f35-4cd2-8631-31318a4713a1
          example: f77b4b4d-2f35-4cd2-8631-31318a4713a1
        posTransactionStatus:
          $ref: '#/components/schemas/PosTransactionStatus'
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            POS transaction was created on.


            Example: 2026-01-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
        modifiedOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) when
            the POS transaction was last updated.


            Example: 2026-03-16T16:32:58.743Z
          example: '2026-03-16T16:32:58.743Z'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        customerId:
          $ref: '#/components/schemas/customerId'
        terminalId:
          type: string
          format: uuid
          x-method: response
          description: >
            Indicates the terminal identifier that handles the transaction.


            The terminal must be in semi-integrated mode and available (online
            and ready).

            A semi-integrated terminal is one that is connected to a POS system,
            typically through a network or cable.


            Example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
          example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        posDeviceId:
          $ref: '#/components/schemas/PosDeviceId'
        referenceId:
          type: string
          description: External Reference ID
          nullable: true
          example: REF-EXT-12345
        captureMethod:
          $ref: '#/components/schemas/CaptureMethod'
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        extraAmounts:
          $ref: '#/components/schemas/ExtraAmountsDto'
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        linkedTransaction:
          $ref: '#/components/schemas/linkedTransaction'
      additionalProperties: false
    GetPosTransactionResponseDto:
      type: object
      properties:
        posTransactionId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the POS transaction identifier.

            Example: 201cc2fb-d9bd-4cc6-a254-b913f9a6b358
          example: 201cc2fb-d9bd-4cc6-a254-b913f9a6b358
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            POS payment method was created on.


            Example: 2026-01-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
        modifiedOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            POS payment method was last modified on.


            Example: 2026-03-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        customerId:
          $ref: '#/components/schemas/customerId'
        terminalId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the terminal identifier handling the POS transaction.

            Example: 9e617a7e-5a7b-415f-abbb-8df16dd2e64f
          example: 9e617a7e-5a7b-415f-abbb-8df16dd2e64f
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        posDeviceId:
          $ref: '#/components/schemas/PosDeviceId'
        referenceId:
          type: string
          x-method: response
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Indicates a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        posTransactionStatus:
          $ref: '#/components/schemas/PosTransactionStatus'
        captureMethod:
          $ref: '#/components/schemas/CaptureMethod'
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        extraAmounts:
          $ref: '#/components/schemas/ExtraAmountsDto'
        linkedTransaction:
          $ref: '#/components/schemas/linkedTransaction'
      additionalProperties: false
    PrintTransactionReceiptRequestDto:
      type: object
      properties:
        terminalId:
          type: string
          format: uuid
          x-method: request
          description: >
            Specifies the terminal identifier for the terminal initiating
            transaction receipt print request.


            The terminal must be in semi-integrated mode and available (online
            and ready).

            A semi-integrated terminal is one that is connected to a POS system,
            typically through a network or cable.


            Example: 7909bab1-5d93-4262-977d-e3f6277f58ef
          example: 7909bab1-5d93-4262-977d-e3f6277f58ef
      additionalProperties: false
    ZeroCostProcessingOption:
      enum:
        - None
        - CashDiscount
        - DualPricing
        - Surcharge
      type: string
      description: >
        Indicates the zero cost processing option.


        Zero cost processing is a pricing strategy that the merchant passes the
        cost of credit card processing fees on to the customer.

        The result is that the merchant pays little to no fees.


        Valid values are:


        | Type         | Meaning |

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

        | CashDiscount | Customers paying with cash receive a discount off the
        posted price. |

        | DualPricing  | Two prices are displayed side by side. This is a cash
        price and a card price. The customer chooses which to pay. |

        | None         | The merchant absorbs the processing fees themselves. |

        | Surcharge    | A fee is added to the transaction when a customer pays
        by credit card. The surcharge amount covers the processing cost. |


        Example: DualPricing
      example: DualPricing
    Currency:
      enum:
        - USD
      type: string
      description: |
        Indicates the available currency (in ISO 4217 currency code).

        Example: USD
      example: USD
    PaymentProcessorType:
      enum:
        - Tsys
        - Ach
        - SandboxCard
        - SandboxAch
      type: string
      description: |
        Indicates the processor type.

        Example: SandboxCard
      example: SandboxCard
    PaymentConfigurationResponseDtoSettlementBatchTimeSlotDto:
      type: object
      properties:
        hours:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the hour (in 24 hour format) of the time slot.

            Examples:<br>
            9<br>
            13<br>
          example: 9
        minutes:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the minutes of the time slot.

            Examples:<br>
            0<br>
            30<br>
            45
        timezoneName:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the timezone name (in IANA Time Zone Database format)

            Examples:<br>
            America/New_York<br>
            Europe/London<br>
            Asia/Tokyo
          example: America/New_York
      additionalProperties: false
    PaymentConfigurationResponseDtoPaymentProcessorDto:
      type: object
      properties:
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        processorName:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the payment processor name.

            Example: TSYS
          example: TSYS
        isDefault:
          type: boolean
          x-method: response
          description: |
            Indicates this payment method is the default payment method.

            If `true`, this is the default payment method.<br>
            If `false`, this is not the default payment method.

            Example: true
          example: true
        type:
          $ref: '#/components/schemas/PaymentProcessorType'
        settlementBatchTimeSlots:
          type: array
          x-method: response
          items:
            $ref: >-
              #/components/schemas/PaymentConfigurationResponseDtoSettlementBatchTimeSlotDto
          description: Indicates an object for settlement batch time slots.
          nullable: true
      additionalProperties: false
    AvsMerchantProfile:
      enum:
        - Strict
        - Moderate
        - Tolerant
      type: string
      description: >
        Indicates the AVS (address verification service) tolerance levels.


        Valid values are:


        | Level    | Description |

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

        | Moderate | Either the street address or ZIP code matches but not
        necessarily both. |

        | Strict   | Both the street address and ZIP code must match exactly. |

        | Tolerant | No AVS verification is performed. The transaction is
        accepted regardless if the address matches. |


        Example: Moderate
      example: Moderate
    PaymentConfigurationResponseDtoAddressVerificationServiceOptionsDto:
      type: object
      properties:
        isEnabled:
          type: boolean
          x-method: response
          description: |
            Indicates the AVS (address verification service) is enabled.

            If `true`, AVS is enabled.<br>
            If `false`, AVS is not enabled.

            Example: true
          example: true
        profile:
          $ref: '#/components/schemas/AvsMerchantProfile'
      additionalProperties: false
    PaymentConfigurationResponseDto:
      type: object
      properties:
        zeroCostProcessingOption:
          $ref: '#/components/schemas/ZeroCostProcessingOption'
        defaultTipsOptions:
          type: array
          x-method: response
          items:
            type: number
            format: double
          description: >
            Indicates the default tip percentage suggestion options.


            This is an array of percentage values that display at the time of
            purchase.

            They offer preselected tip percentage suggestions as a convenience
            for the purchasers.


            Example: [ 15, 18, 20 ] (as 15%, 18%, and 20%)
          example:
            - 15
            - 18
            - 20
          nullable: true
        defaultSurchargeRate:
          type: number
          format: double
          x-method: response
          nullable: true
          description: |
            Indicates the default surcharge rate.

            Examples:<br>
            1.5 (as 1.5%)<br>
            5 (as 5%)<br>
            22 (as 22%)
          example: 1.5
        defaultCashDiscountRate:
          type: number
          format: double
          x-method: response
          nullable: true
          description: |
            Indicates the cash discount rate.

            Examples:<br>
            1.5 (as 1.5%)<br>
            5 (as 5%)<br>
            20 (as 20%)
          example: 1.5
        defaultDualPricingRate:
          type: number
          format: double
          x-method: response
          nullable: true
          description: |
            Indicates the default dual pricing rate.

            Examples:<br>
            1.8 (as 1.8%)<br>
            5 (as 5%)<br>
            20 (as 20%)
          example: 1.8
        availableCurrencies:
          type: array
          nullable: true
          x-method: response
          items:
            $ref: '#/components/schemas/Currency'
          description: |
            Indicates the available currencies (in ISO 4217 currency code).

            Example: USD
          example:
            - USD
        availableCardTypes:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/CardType'
          description: |
            Indicates the available card types.

            Example: [ "Visa", "MasterCard", "AmericanExpress" ]
          example:
            - Visa
            - MasterCard
            - AmericanExpress
          nullable: true
        availableTransactionTypes:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/TransactionType'
          description: |
            Indicates the available transaction types.

            Example: [ "Authorization", "Sale", "Refund" ]
          example:
            - Authorization
            - Sale
            - Refund
          nullable: true
        isTipsEnabled:
          type: boolean
          x-method: response
          description: |
            Indicates tips are enabled.

            If `true`, tips are enabled.<br>
            If `false`, tips are not enabled.

            Example: true
          example: true
        availablePaymentProcessors:
          type: array
          x-method: response
          items:
            $ref: >-
              #/components/schemas/PaymentConfigurationResponseDtoPaymentProcessorDto
          description: |
            Indicates the available payment processors.
          nullable: true
        addressVerificationServiceOptions:
          $ref: >-
            #/components/schemas/PaymentConfigurationResponseDtoAddressVerificationServiceOptionsDto
        isCustomerCardSavingByTerminalEnabled:
          type: boolean
          x-method: response
          description: >
            Indicates the terminal can save customer card after a transaction.


            If `true`, the terminal can save customer card after a
            transaction.<br>

            If `false`, the terminal cannot save customer card after a
            transaction.


            Example: true
          example: true
        companyName:
          type: string
          x-method: response
          description: >
            Indicates the name of the customer's company or organization.


            This is a free-formed name that is convenient for the merchant to
            recognize.


            Example: Peppared Street Cafe
          example: Peppared Street Cafe
          nullable: true
        mccCode:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the MCC (merchant category code).

            Example: 5411
          example: '5411'
        mccCodeDescription:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the MCC (merchant category code) description.

            Example: Grocery Stores, Supermarkets
          example: Grocery Stores, Supermarkets
        currency:
          $ref: '#/components/schemas/currencyCode'
        maxTransactionAmount:
          type: number
          format: double
          x-method: response
          nullable: true
          description: |
            Indicates the maximum transaction amount limit.

            Example: 10000
          example: 10000
        ttpIosTerminalProfileId:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the TTP (tap-to-pay terminal) profile identifier for iOS
            devices.


            Example: ttp-ios-profile-123
          example: ttp-ios-profile-123
      additionalProperties: false
      description: >-
        Indicates an object describing the payment configuration settings for
        the merchant.
    ContactInfoResponseDtoMerchantContactInfoDto:
      type: object
      properties:
        addressLine1:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the first line of the address.

            Example: 123 Main Street
          example: 123 Main Street
        addressLine2:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates an optional second line of the address.

            Example: Suite 400
          example: Suite 400
        city:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the name of the city.

            Example: Chicago
          example: Chicago
        postalCode:
          type: string
          nullable: true
          minLength: 2
          maxLength: 15
          x-method: response
          description: |
            Indicates the postal or ZIP code.

            Example: 10001
          example: '10001'
        stateCode:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the state identifier (in two-letter USPS [United States
            Postal Service] postal code).


            For regions outside the US, use the ISO 3166-2 format.


            Examples:<br>

            TX<br>

            WA<br>

            IL
          example: NY
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
          nullable: true
          x-method: response
          description: |
            Indicates the country identifier (in two letter ISO 3166-1 format).

            Examples:<br>
            US<br>
            CA<br>
            GB
          example: US
        contactInfoId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the contact information record identifier.

            Example: 91e0278b-02e8-4963-8710-fe3dfca39d51
          example: 91e0278b-02e8-4963-8710-fe3dfca39d51
        addressName:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the name or label of the address.

            Example: Main office
          example: Main office
        email:
          type: string
          x-method: response
          nullable: true
          description: |
            Indicates the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: response
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Indicates the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        isMainAddress:
          type: boolean
          x-method: response
          description: |
            Indicates this is the main address.

            If `true`, this is the main address.<br>
            If `false`, this is not the main address.

            Example: true
          example: true
        isDefaultAddress:
          type: boolean
          x-method: response
          description: |
            Indicates this is the default shipping address.

            If `true`, this is the default shipping address.<br>
            If `false`, this is not the default shipping address.

            Example: true
          example: true
      additionalProperties: false
    ContactInfoResponseDto:
      type: object
      properties:
        contactInfos:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/ContactInfoResponseDtoMerchantContactInfoDto'
          description: Indicates an object for the merchant contact information.
          nullable: true
      additionalProperties: false
    Level2SettingsDto:
      type: object
      properties:
        taxRate:
          type: number
          format: double
          minimum: 0
          maximum: 22
          x-method: request/response
          nullable: true
          description: |
            Identifies the default level 2 autoFill sales tax rate.

            Examples:<br>
            5.0 (for 5.0%)<br>
            8.5 (for 8.5%)<br>
            10.25 (for 10.25%)
          example: 8.5
      additionalProperties: false
    ProductDto:
      type: object
      properties:
        productName:
          type: string
          x-method: request
          description: |
            Specifies the name of the product.

            Example: Widget
          nullable: true
          example: Widget
        code:
          type: string
          x-method: request
          description: |
            Specifies the merchant assigned unique product identification code.

            The code may only contain letters, digits, spaces, and slashes.

            Example: SKU/12345
          nullable: true
          example: SKU/12345
        unitPrice:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Specifies the  unit price for the product.

            Example: 19.99
          example: 19.99
        measurementUnit:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the unit of measurement for the product.

            Example: EA
          example: EA
        quantity:
          type: number
          description: |
            Specifies the quantity of the product.

            Example: 1
          format: double
          x-method: request
          nullable: true
          example: 1
        discountPercentage:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Specifies the product discount percentage.

            Example: 10.5 (for 10.5%)
          example: 10
        description:
          type: string
          x-method: request
          description: |
            Specifies the product description.

            Example: Sample cologne for conference.
          example: Sample cologne for conference
          nullable: true
      additionalProperties: false
    Level3SettingsDto:
      type: object
      properties:
        product:
          $ref: '#/components/schemas/ProductDto'
        shippingChargeRate:
          type: number
          format: double
          x-method: request
          nullable: true
          description: >
            Specifies the percentage for shipping or freight charges applied to
            a product or transaction.


            Examples:<br>

            2.5 (for 2.5%)<br>

            8.5 (for 8.5%)<br>

            10.25 (for 10.25%)
          example: 2.5
        dutyChargeRate:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Examples:<br>
            2.5 (for 2.5%)<br>
            8.5 (for 8.5%)<br>
            10.25 (for 10.25%)
          example: 2.5
      additionalProperties: false
    TransactionAutofillResponseDto:
      type: object
      properties:
        level2Settings:
          $ref: '#/components/schemas/Level2SettingsDto'
        level3Settings:
          $ref: '#/components/schemas/Level3SettingsDto'
      additionalProperties: false
      description: Transaction autofill settings configured for the merchant.
    UpdateTransactionAutofillRequestDto:
      required:
        - level2Settings
        - level3Settings
      type: object
      properties:
        level2Settings:
          $ref: '#/components/schemas/Level2SettingsDto'
        level3Settings:
          $ref: '#/components/schemas/Level3SettingsDto'
      additionalProperties: false
    batchId:
      type: string
      format: uuid
      x-method: response
      nullable: true
      description: |
        Indicates the batch settlement identifier.

        Example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6
      example: 42df0a13-4bf4-48f8-929c-08a379c0a0d6
    SettlementBatchStatus:
      name: status
      in: query
      required: false
      description: >
        Identifies the batch settlement type.


        Valid values are:


        | Batch Type | Meaning |

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

        | Open       | An open batch is still active and accepting transactions.
        |

        | Settled    | A settled batch has completed processing with the
        acquirer or bank. |


        Example: Open
      schema:
        type: string
        example: Open
    ListBatchesResponseDto:
      type: object
      properties:
        batchId:
          $ref: '#/components/schemas/batchId'
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        paymentProcessorName:
          type: string
          x-method: response
          description: |
            Indicates the name of the payment processor.

            Example: TSYS
          nullable: true
          example: TSYS
        externalBatchId:
          type: string
          x-method: response
          description: |
            Indicates the external batch identifier from the payment processor.

            Example: BATCH-EXT-001
          nullable: true
          example: BATCH-EXT-001
        batchDateTime:
          type: string
          description: |
            Indicates the date and time when the batch was created or processed.

            Example: 2026-05-05T18:00:56.264Z
          format: date-time
          x-method: response
          nullable: true
          example: '2026-05-05T18:00:56.264Z'
        transactionCount:
          type: integer
          format: int32
          x-method: response
          description: |
            Indicates the total number of transactions in the batch.

            Example: 36
          example: 36
        netAmount:
          type: number
          format: double
          x-method: response
          description: >
            Indicates the net amount after all transactions (sales minus
            refunds).


            Example: 9500
          example: 9500
        salesAmount:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the total amount of sales in the batch.

            Example: 9562.18
          example: 9562.18
        refundsAmount:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the total amount of refunds in the batch.

            Example: 486.23
          example: 486.23
        status:
          $ref: '#/components/schemas/SettlementBatchStatus'
      additionalProperties: false
      description: Settlement batch details.
    PageOfListBatchesResponseDto:
      type: object
      properties:
        items:
          type: array
          x-method: response
          description: |
            Indicates an object returning found batch settlements.
          items:
            $ref: '#/components/schemas/ListBatchesResponseDto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    SettleTransactionsRequestDto:
      required:
        - paymentProcessorId
      type: object
      properties:
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
      additionalProperties: false
      description: >
        Request to settle (close) a batch of transactions for a given payment
        processor.
    ResponseCode:
      enum:
        - Approve
        - Decline
        - Error
      type: string
      description: >
        Indicates the status of the batch payment submission.


        Valid values are:


        | Value   | Meaning |

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

        | Approve | The settlement was accepted or processed successfully. |

        | Decline | The settlement was rejected by the processor or acquirer
        such as by failed validation, insufficient funds, or closed account,
        risk or fraud rule. |

        | Error   | The request could not be completed due to a system or
        processing issue such as by a timeout, malformed data, downstream
        failure. This is distinct from `Decline` that is an explicit business
        decision rejection. |


        Example: Approve
      example: Approve
    SettleTransactionsResponseDto:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ResponseCode'
        message:
          type: string
          x-method: response
          description: |
            Indicates a descriptive message about the settlement result.

            Example: Batch settled successfully
          nullable: true
          example: Batch settled successfully
        processorResponseCode:
          type: string
          x-method: response
          description: |
            Indicates a response code from the payment processor.

            Example: 00
          nullable: true
          example: '00'
      additionalProperties: false
      description: Response after settling (closing) a batch of transactions.
    TerminalManufacturer:
      enum:
        - Sunmi
        - Verifone
      type: string
      description: |
        Indicates the terminal manufacturer.

        Valid values are:

        | Manufacturer |
        |--------------|
        | Sunmi        |
        | Verifone     |

        Example: Verifone
      example: Verifone
    TerminalModel:
      enum:
        - SunmiP2
        - SunmiP2LiteSe
        - VerifoneVictaMobile
        - VerifoneVictaPortable
        - SunmiP3H
      type: string
      description: |
        Indicates the model of the terminal.

        Valid values are:

        | Model                  |
        |------------------------|
        | SunmiP2                |
        | SunmiP2LiteSe          |
        | VerifoneVictaMobile    |
        | VerifoneVictaPortable  |
        | SunmiP3H               |

        Example: SunmiP2LiteSe
      example: SunmiP2LiteSe
    TerminalMode:
      enum:
        - Standalone
        - SemiIntegrated
      type: string
      description: >
        Indicates the operating mode of the terminal.


        Valid values are:

        | Type            | Meaning |

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

        | Standalone      | The terminal operates independently of any POS
        system. The amount is entered directly on the terminal itself (no
        electronic connection to a cash register/POS software), and it runs the
        transaction on its own. |

        | SemiIntegrated  | The terminal is connected to a POS system, typically
        through a network or cable. The POS sends the transaction amount to the
        terminal electronically, rather than requiring manual entry. However,
        the POS never touches card or payment data directly. The terminal
        handles all sensitive payment processing itself. This architecture is
        commonly used to reduce PCI compliance scope on the POS side. |


        Example: Standalone
      example: Standalone
    TerminalPosStatus:
      enum:
        - Active
        - Busy
        - Offline
      type: string
      description: >
        Indicates the terminal status to process a new transaction.


        Valid values are:


        | Status  |
        Meaning                                                                                   
        |

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

        | Active  | The terminal is powered on and available.<br><br>It is ready
        to process a new transaction. |

        | Busy    | The terminal is currently processing a
        transaction.<br><br>It is not available to accept another one until that
        transaction completes. |

        | Offline | The terminal is disconnected or unreachable.<br><br>It
        cannot process transactions until connectivity is restored. |


        Example: Active
      example: Active
    TerminalConnectionStatus:
      enum:
        - Online
        - Offline
      type: string
      description: >
        Indicates the line status of the terminal.


        Valid values are:


        | Status  | Meaning |

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

        | Online  | The terminal is currently connected and reachable.<br><br>It
        has active network or internet connectivity. It is able to process
        transactions and communicate with the backend in real time. |

        | Offline | The terminal is disconnected or unreachable.<br><br>It may
        be powered off, have lost its network connection, or otherwise be unable
        to communicate. As a result, it cannot process transactions, or can only
        do so in a stored or deferred mode depending on the platform. |  


        Example: Online
      example: Online
    ListTerminalsResponseDto:
      type: object
      properties:
        terminalId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the identifier of terminal handling the POS transaction.

            Example: d0fc1606-47ea-464b-a31a-3971c9822d10
          example: d0fc1606-47ea-464b-a31a-3971c9822d10
        merchantId:
          $ref: '#/components/schemas/merchantId'
        merchantCompanyName:
          type: string
          nullable: true
          x-method: response
          description: >
            Indicates the company name of the merchant associated with the
            terminal.


            Example: Peppared Street Cafe
          example: Peppared Street Cafe
        serialNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the terminal serial number.

            Example: SN0123456789
          example: SN0123456789
        terminalManufacturer:
          $ref: '#/components/schemas/TerminalManufacturer'
        terminalModel:
          $ref: '#/components/schemas/TerminalModel'
        terminalMode:
          $ref: '#/components/schemas/TerminalMode'
        terminalStatus:
          $ref: '#/components/schemas/TerminalPosStatus'
        connectionStatus:
          $ref: '#/components/schemas/TerminalConnectionStatus'
        lastSeenOn:
          type: string
          format: date-time
          x-method: response
          nullable: true
          description: >
            Indicates the timestamp (in an ISO 8601 date-time UTC format) that
            the terminal was last seen online.


            Example: 2026-05-05T13:25:22.344Z
          example: '2026-05-05T13:25:22.344Z'
      additionalProperties: false
      description: Response DTO for a terminal in the list.
    PageOfListTerminalsResponseDto:
      type: object
      properties:
        items:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/ListTerminalsResponseDto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    TerminalDebitPinKey:
      enum:
        - Injected
        - Missing
      type: string
      description: >
        Indicates the debit PIN key.


        A debit PIN key is a cryptographic key used specifically to encrypt the
        cardholder's PIN during a debit transaction on a payment terminal.

        When a customer enters their PIN on a PIN pad or terminal, that PIN must
        be encrypted immediately within the terminal's secure hardware (never
        transmitted in plaintext) to comply with PCI PIN security standards.

        The debit PIN key is what performs that encryption.


        It is typically injected into the terminal.

        This is often as part of a DUKPT (derived unique key per transaction)
        scheme, or a fixed key-encryption-key setup.


        The terminal can encrypt the PIN block before it's sent onward for
        authorization.

        If the debitPinKey is missing, the terminal cannot securely accept
        PIN-debit transactions until that key is loaded.


        Valid values are:


        | Status   |
        Explanation                                                                                    
        |

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

        | Injected | The terminal has had its encryption or security keys
        loaded.<br><br>It is properly provisioned to process secure payment
        data. |

        | Missing  | The terminal does not have its encryption or security keys
        loaded.<br><br>It cannot securely process payment data until keys are
        injected. |


        Example: Injected
      example: Injected
    TerminalConnectionType:
      enum:
        - WiFi
        - Mobile
        - Ethernet
      type: string
      description: >
        Indicates the connection type for the terminal.


        Valid values are:


        | Type     |
        Meaning                                                                                  
        |

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

        | Ethernet | The terminal connects through a wired network
        cable.<br><br>This typically offers the most stable and reliable
        connection. |

        | Mobile   | The terminal connects using a cellular data
        connection.<br><br>This is useful when Wi-Fi or Ethernet isn't
        available, such as in the field. |

        | WiFi     | The terminal connects through a wireless local
        network.<br><br>This offers mobility within range of the wireless access
        point without a physical cable. |


        Example: Ethernet
      example: Ethernet
    TerminalPrinterStatus:
      enum:
        - Normal
        - NotNormal
        - NotSupported
      type: string
      description: |
        Indicates the printer status.

        Valid values are:

        | Status       | Meaning                                   |
        |--------------|-------------------------------------------|
        | Normal       | The device is functioning correctly.      |
        | NotNormal    | The device has an issue or fault.         |
        | NotSupported | The device does not support this feature. |

        Example: Normal
      example: Normal
    GetTerminalStatusResponseDto:
      type: object
      properties:
        terminalId:
          type: string
          format: uuid
          x-method: response
          description: >
            Indicates the terminal identifier that handles the transaction.


            This is a mirror of the path parameter.


            The terminal must be in semi-integrated mode and available (online
            and ready).

            A semi-integrated terminal is one that is connected to a POS system,
            typically through a network or cable.


            Example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
          example: 0dfac966-9dbd-4608-a65f-d6a4c961dd35
        merchantId:
          $ref: '#/components/schemas/merchantId'
        terminalStatus:
          $ref: '#/components/schemas/TerminalPosStatus'
        lastSeenOn:
          type: string
          format: date-time
          x-method: response
          nullable: true
          description: >
            Indicates the timestamp (in an ISO 8601 date-time UTC format) that
            the terminal was last seen online.


            Example: 2026-05-05T13:25:32.223Z
          example: '2026-05-05T13:25:32.223Z'
        debitPinKey:
          $ref: '#/components/schemas/TerminalDebitPinKey'
        terminalAppVersion:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the terminal version.

            Example: 1.4.2
          example: 1.4.2
        connectionStatus:
          $ref: '#/components/schemas/TerminalConnectionStatus'
        connectionType:
          $ref: '#/components/schemas/TerminalConnectionType'
        wifiConnectionStrength:
          type: integer
          format: int32
          x-method: response
          minimum: 0
          maximum: 100
          description: |
            Indicates the WiFi connection strength as a percent.

            Example: 45 (as 45%)
          example: 45
        mobileConnectionStrength:
          type: integer
          format: int32
          x-method: response
          minimum: 0
          maximum: 100
          description: |
            Indicates the mobile connection strength as a percent.

            Example: 87 (as 87%)
          example: 87
        batteryLevel:
          type: integer
          format: int32
          x-method: response
          minimum: 0
          maximum: 100
          description: |
            Indicates the battery level as a percent.

            Example: 52 (as 52%)
          example: 52
        printerStatus:
          $ref: '#/components/schemas/TerminalPrinterStatus'
      additionalProperties: false
    AmountBreakdownDto:
      type: object
      properties:
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        tipAmount:
          type: number
          format: double
          x-method: response
          multipleOf: 0.01
          description: >
            Indicates the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          x-method: response
          multipleOf: 0.01
          description: >
            Indicates a percentage of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
        discountAmount:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the absolute amount (in USD) of discount to be applied.

            If this value is provided, it must be greater than zero.

            Example: 25 (for $25)
          example: 25
        discountRate:
          type: number
          format: double
          x-method: response
          description: >
            Indicates a percentage of a discount to be applied.


            If this value is provided, it must be greater than zero.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `discountAmount` or `discountRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 5.5 (for 5.5%)
          example: 5.5
        surchargeAmount:
          type: number
          format: double
          x-method: response
          description: >
            Indicates the surcharge amount (in USD) applied.


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `discountAmount` or `discountRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 22 (for $22)
          example: 22
        surchargeRate:
          type: number
          format: double
          description: >
            Indicates the percent of transaction amount.


            This value is added to the base amount after `PercentageOffRate` has
            been applied.


            Care must be taken that a value other than zero can be provided to
            either `surchargeAmount` or `surchargeRate`.

            A non-zero value cannot be provided to both.


            Example: 2.5 (for 2.5%)
          example: 2.5
      additionalProperties: false
      description: Indicates an object detailing the amount breakdown details.
    TransactionCardDetailsDtoShort:
      type: object
      description: >
        Indicates the card details exposed on transaction responses.


        These may be masked for sensitive fields or fully displayed for
        non-sensitive fields.
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        maskedCardNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked card number.

            This displays only the last four numbers.

            Example: ************1111
          example: '************1111'
        cardBrand:
          $ref: '#/components/schemas/CardType'
        cardType:
          $ref: '#/components/schemas/CreditDebitType'
        cardProcessedAsType:
          $ref: '#/components/schemas/CreditDebitType'
        cardDataSource:
          $ref: '#/components/schemas/CardDataSourceDto'
        cardholderVerificationMethod:
          $ref: '#/components/schemas/CardholderAuthenticationMethodDto'
      additionalProperties: false
    AchDetailsDtoShort:
      type: object
      description: >
        Indicates ACH account details exposed on transaction responses.


        These may be masked for sensitive fields or fully displayed for
        non-sensitive fields.
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        maskedAccountNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked ACH account number.

            This displays only the last four numbers.

            Example: **************89
          example: '**************89'
        accountRoutingNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked ACH routing number.

            Example: 123123123
          example: '123123123'
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        accountType:
          $ref: '#/components/schemas/AccountType'
        secCode:
          $ref: '#/components/schemas/AchSECCode'
        isSameDayProcessing:
          type: boolean
          nullable: true
          x-method: request
          description: >
            Indicates same-day ACH processing for faster settlement.


            If `true`, the transaction uses the same-day ACH processing.<br>

            If `false`, the transaction does not use the same-day ACH
            processing.<br>

            If null or omitted, the default standard ACH processing is used.


            Example: true
          example: true
      additionalProperties: false
    source:
      type: object
      description: |
        Indicates an object describing the origination of the transaction.
      properties:
        sourceType:
          enum:
            - Portal
            - ApiKey
            - Terminal
            - Invoice
            - QuickPayment
            - WebComponent
            - Subscription
            - MobileApp
            - TapToPay
          type: string
          description: >
            Indicates the source of the transaction.


            Valid values are:

            | Value         |
            Description                                                        |

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

            | ApiKey        | An external application created the transaction
            using an API key.  |

            | Invoice       | A billed invoice created the
            transaction.                          |

            | MobileApp     | A mobile application created the
            transaction.                      |

            | Portal        | A staff member created the transaction through the
            web portal.     |

            | QuickPayment  | A one-time payment link created the
            transaction.                   |

            | Subscription  | A recurring subscription created the
            transaction.                  |

            | TapToPay      | A mobile device using tap to pay created the
            transaction.          |

            | Terminal      | A physical payment terminal created the
            transaction.               |

            | WebComponent  | An embedded web component created the
            transaction.                 |


            Example: QuickPayment
          example: QuickPayment
        sourceId:
          type: string
          format: uuid
          nullable: true
          description: |
            Indicates the Identifier of the originating entity.

            Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        sourceName:
          type: string
          nullable: true
          description: |
            Indicates a human-readable name of the originator.

            Example: API Key for ecommerce app
          example: API Key for ecommerce app
      additionalProperties: false
    GetTransactionResponseDtoShort:
      type: object
      properties:
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        transactionDateTime:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 date-time format) of the
            transaction.


            Example: 2026-05-05T14:30:42.938Z
          example: '2026-05-05T14:30:42.938Z'
        transactionStatus:
          $ref: '#/components/schemas/AggregatedTransactionStatus'
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
        referenceId:
          type: string
          x-method: response
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Indicates a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        pricingType:
          $ref: '#/components/schemas/PricingType'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        customerId:
          $ref: '#/components/schemas/customerId'
        batchId:
          $ref: '#/components/schemas/batchId'
        amountBreakdown:
          $ref: '#/components/schemas/AmountBreakdownDto'
        cardDetails:
          $ref: '#/components/schemas/TransactionCardDetailsDtoShort'
        achDetails:
          $ref: '#/components/schemas/AchDetailsDtoShort'
        processorDetails:
          $ref: '#/components/schemas/processorDetails'
        source:
          $ref: '#/components/schemas/source'
      additionalProperties: false
    PageOfGetTransactionResponseDto:
      type: object
      properties:
        items:
          type: array
          x-method: response
          items:
            $ref: '#/components/schemas/GetTransactionResponseDtoShort'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    TransactionProductIsvDto:
      type: object
      properties:
        productName:
          type: string
          nullable: true
          minLength: 1
          maxLength: 15
          x-method: request
          description: >
            Specifies the name of the product.


            The code may only contain letters, digits, spaces, slashes, hyphen,
            and commas.


            Example: Express Duo
          example: Express Duo
        productDescription:
          type: string
          minLength: 1
          maxLength: 200
          nullable: true
          x-method: request
          description: |
            Specifies the description of the product.

            Example: Standard office supplies
          example: Standard office supplies
        productCode:
          type: string
          nullable: true
          minLength: 1
          maxLength: 20
          x-method: request
          description: >
            Specifies the merchant's assigned unique product identification
            code.


            The code may only contain letters, digits, spaces, slashes, hyphen,
            and commas.


            Example: HLA/6372
          example: HLA/6372
        unitPrice:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Specifies the product price (in USD) for each unit. 

            Example: 3.99
          example: 3.99
        measurementUnit:
          type: string
          minLength: 1
          maxLength: 20
          nullable: true
          x-method: request
          description: |
            Specifies the unit of measurement for the product.

            The code may only contain letters, digits, and spaces.
            No special characters are allowed.

            Examples:<br>
            EA<br>
            LB<br>
            DAY
          example: EA
        quantity:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Specifies the quantity of a product.

            Example: 12
          example: 12
        taxAmount:
          type: number
          format: double
          x-method: request
          nullable: true
          description: |
            Specifies the tax amount established on a product.

            Example: 3.75 (for 3.75%)
          example: 3.75
        discountRate:
          type: number
          format: double
          minimum: 0.01
          maximum: 199
          x-method: request
          nullable: true
          description: |
            Specifies the discount percentage applied to a product.

            Examples:<br>
            10 (for 10%)<br>
            2.5 (for 2.5%)
          example: 10
      additionalProperties: false
    TransactionEnhancedDataDto:
      type: object
      properties:
        salesTaxRate:
          type: number
          format: double
          minimum: 0.01
          maximum: 100
          x-method: request
          nullable: true
          description: |
            Specifies the sales tax rate. 

            Example: 8.5 (for 8.5%)
          example: 8.5
        invoiceNumber:
          type: string
          nullable: true
          maxLength: 16
          x-method: request
          description: >
            Specifies the VAT (value added tax) invoice number associated with
            the transaction.


            The code may only contain letters, digits, and spaces.


            Example: INV-001234
          example: INV-001234
        purchaseOrder:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the value used by the customer to identify an order.

            Issued by the buyer to the seller.

            The code may only contain letters, digits, and spaces.

            Example: PO-2026-0001
          example: PO-2026-0001
        shippingCharges:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          nullable: true
          description: >
            Specifies the amount (in USD) for shipping or freight charges
            applied to a product or transaction.


            Example:  129.99
          example: 129.99
        dutyCharges:
          type: number
          format: double
          maxLength: 12
          x-method: request
          nullable: true
          description: >
            Specifies the total charges for any import or export duties included
            in the order.


            Example: 2.5 (for 2.5%)
          example: 2.5
        products:
          type: array
          x-method: request
          items:
            $ref: '#/components/schemas/TransactionProductIsvDto'
          description: Multiple products may be sent in a single request.
          nullable: true
      additionalProperties: false
      description: >
        Specifies a combined Level 2 and Level 3 enhanced data for card
        transactions.

        Used for commercial card processing with additional transaction details.
    ContactInfoDto:
      type: object
      properties:
        firstName:
          type: string
          x-method: request
          description: |
            Specifies the customer's first name.

            Example: Alexandro
          example: Alexandro
          nullable: true
        lastName:
          type: string
          x-method: request
          description: |
            Specifies the customer's last name.

            Example: Peppared
          example: Peppared
          nullable: true
        companyName:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the name of the customer's company or organization.

            Example: Peppared Street Cafe
          example: Peppared Street Cafe
        email:
          type: string
          x-method: request
          nullable: true
          description: |
            Specifies the customer's email.

            Example: peppared@example.com
          example: peppared@example.com
        mobilePhoneNumber:
          type: string
          x-method: request
          nullable: true
          format: E.164
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Specifies the customer's mobile phone number.

            Example: +14155552309
          example: '+14155552309'
        hasSmsConsent:
          type: boolean
          default: false
          x-method: request
          description: |
            Specifies the customer has consented to receiving the SMS.

            If `true`, the customer has consented to receiving the SMS.<br>
            If `false`, the customer has not consented to receiving the SMS.

            Example: true
          example: true
      additionalProperties: false
      description: Contact information.
    PaymentMethodCardDetailsDto:
      type: object
      properties:
        cardNumber:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the card number (either credit or debit) used for the
            transaction.


            Example: 4111111111111111
          example: '4111111111111111'
        securityCode:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the securityCode (sometimes also called similarly to CCV)
            for the card.


            This is a three or four digit security code on the credit card.


            Example: 483
          example: '483'
        expirationMonth:
          $ref: '#/components/schemas/expirationMonthRequest'
        expirationYear:
          $ref: '#/components/schemas/expirationYearRequest'
      additionalProperties: false
    CardDataDto:
      type: object
      properties:
        paymentMethodId:
          type: string
          format: uuid
          x-method: request
          nullable: true
          description: >
            Specifies the payment method identifier.


            This is the identifier of a previously saved ACH account to charge.

            We recommend using `paymentMethodId` instead of `accountNumber`.


            <br>

            <span class="note">

            This field is mutually exclusive with <span style="color:
            red;">`paymentMethodDetails`</span>.

            Provide exactly one.

            </span>

            <br>


            When set, the parent request's `BillingAddress` and `ContactInfo`
            are optional (the stored payment method carries this data).


            Example: 39a95e35-6d50-45ec-884b-c2417edf005d
          example: 39a95e35-6d50-45ec-884b-c2417edf005d
        paymentMethodDetails:
          $ref: '#/components/schemas/PaymentMethodCardDetailsDto'
      additionalProperties: false
    AchDataDto:
      required:
        - requesterIpAddress
      type: object
      properties:
        paymentMethodId:
          type: string
          format: uuid
          x-method: request
          nullable: true
          description: >
            Specifies the payment method identifier.


            This is the identifier of a previously saved ACH account to charge.

            We recommend using `paymentMethodId` instead of `accountNumber`.


            <br>

            <span class="note">

            This field is mutually exclusive with <span style="color:
            red;">`paymentMethodDetails`</span>.

            Provide exactly one.

            </span>

            <br>


            When set, the parent request's `BillingAddress` and `ContactInfo`
            are optional (the stored payment method carries this data).


            Example: 39a95e35-6d50-45ec-884b-c2417edf005d
          example: 39a95e35-6d50-45ec-884b-c2417edf005d
        paymentMethodDetails:
          type: object
          description: >
            Specifies an object describing the payment method details.


            <br>

            <span class="note">

            This field is mutually exclusive with <span style="color:
            red;">`paymentMethodId`</span>.

            Provide exactly one.

            </span>

            <br>
          properties:
            accountNumber:
              $ref: '#/components/schemas/accountNumberRequest'
            routingNumber:
              type: string
              nullable: true
              x-method: request
              description: |
                Specifies the ACH's account routing number.

                Example: 021000021
              example: '021000021'
            accountHolderType:
              $ref: '#/components/schemas/AccountHolderType'
            accountType:
              $ref: '#/components/schemas/AccountType'
            taxId:
              type: string
              x-method: request
              description: |
                Specifies the tax identifier.

                Example: 12-3456789
              example: 12-3456789
              nullable: true
          additionalProperties: false
        secCode:
          $ref: '#/components/schemas/AchSECCode'
        isSameDayProcessing:
          type: boolean
          nullable: true
          x-method: request
          description: >
            Specifies same-day ACH processing for faster settlement.


            If `true`, the transaction uses the same-day ACH processing.<br>

            If `false`, the transaction does not use the same-day ACH
            processing.<br>

            If null or omitted, the default standard ACH processing is used.


            Example: true
          example: true
        requesterIpAddress:
          maxLength: 45
          minLength: 0
          type: string
          x-method: request
          description: >
            Specifies the IP address (in IPv4 or IPv6 format3) of the end user.


            This end user may be the customer, operator, or application
            responsible for submitting the transaction.

            This is required for audit and fraud-detection purposes.


            Example: 192.168.1.1
          example: 192.168.1.1
      additionalProperties: false
    TransactionDetailsDto:
      type: object
      properties:
        cardData:
          $ref: '#/components/schemas/CardDataDto'
        achData:
          $ref: '#/components/schemas/AchDataDto'
      additionalProperties: false
    MobilePlatform:
      enum:
        - iOS
        - Android
      type: string
      description: |
        Specifies the platform of the mobile phone.


        Valid values are:
        | Item    | Explanation                        |
        |---------|------------------------------------|
        | Android | Mobile operating system by Google. |
        | iOS     | Mobile operating system by Apple.  |

        Example: iOS
      example: iOS
    CreateTransactionRequestDto:
      type: object
      properties:
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        baseAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          description: |
            Specifies the base transaction amount before adjustments.

            Examples:<br>
            125<br>
            125.5<br>
            125.50
          example: 125.5
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        referenceId:
          type: string
          x-method: request
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Specifies a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        isCustomerInitiatedTransaction:
          type: boolean
          x-method: request
          description: |
            Specifies a transaction is initiated by a customer or a merchant.

            If `true`, the transaction is initiated by customer.<br>
            If `false`, the transaction is initiated by a merchant.

            Example: true
          example: true
        pricingType:
          $ref: '#/components/schemas/PricingType'
        extraAmounts:
          $ref: '#/components/schemas/ExtraAmountsDto'
        transactionEnhancedData:
          $ref: '#/components/schemas/TransactionEnhancedDataDto'
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        shippingAddress:
          $ref: '#/components/schemas/AddressDto'
        contactInfo:
          $ref: '#/components/schemas/ContactInfoDto'
        transactionDetails:
          $ref: '#/components/schemas/TransactionDetailsDto'
        deviceId:
          type: string
          format: uuid
          x-method: request
          nullable: true
          description: >
            Specifies a device identifier from mobile app.


            If included and the device has a linked user profile, the
            transaction is attributed to that user.<br>

            If null or omitted, no attribution is made.


            example: 088642a8-9082-4496-be63-8120765c5ad3
          example: 088642a8-9082-4496-be63-8120765c5ad3
        platform:
          $ref: '#/components/schemas/MobilePlatform'
        appVersion:
          type: string
          nullable: true
          x-method: request
          description: >
            Specifies the version of the mobile app used to process the
            transaction.


            Example: 1.4.2
          example: 1.4.2
        sdkVersion:
          type: string
          nullable: true
          x-method: request
          description: |
            Specifies the version of the SDK used to process the transaction.

            Example: 2.0.1
          example: 2.0.1
      additionalProperties: false
    refundDetals:
      type: object
      properties:
        refundedAmount:
          type: number
          format: double
          multipleOf: 0.01
          description: >
            Indicates the total amount (in USD) already refunded against this
            transaction.


            Examples:<br>

            56.99<br>

            0
          example: 0
        availableRefundAmount:
          type: number
          format: double
          multipleOf: 0.01
          description: |
            Indicates the amount (in USD) still refundable.

            Example: 120.99
          example: 120.99
        isFullyRefunded:
          type: boolean
          description: |
            Indicates the amount has been fully refunded.

            If `true`, the amount has been fully refunded.<br>
            If `false`, the amount has not been fully refunded.

            Example: true
          example: true
      additionalProperties: false
      description: >
        Indicates an object detailing the refund posture for a transaction that
        can be refunded.


        This value is null on transactions that are themselves refunds or
        credits.

        Those cannot be refunded again.
    TransactionCardDetailsDto:
      type: object
      description: >
        Indicates the card details exposed on transaction responses.


        These may be masked for sensitive fields or fully displayed for
        non-sensitive fields.
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        maskedCardNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked card number.

            This displays only the last four numbers.

            Example: ************1111
          example: '************1111'
        cardBrand:
          $ref: '#/components/schemas/CardType'
        cardType:
          $ref: '#/components/schemas/CreditDebitType'
        cardProcessedAsType:
          $ref: '#/components/schemas/CreditDebitType'
        cardDataSource:
          $ref: '#/components/schemas/CardDataSourceDto'
        cardholderVerificationMethod:
          $ref: '#/components/schemas/CardholderAuthenticationMethodDto'
        emvTags:
          $ref: '#/components/schemas/TransactionReceiptDtoEmvTagsDto'
      additionalProperties: false
    AchDetailsDto:
      type: object
      description: >
        Indicates ACH account details exposed on transaction responses.


        These may be masked for sensitive fields or fully displayed for
        non-sensitive fields.
      properties:
        paymentMethodId:
          $ref: '#/components/schemas/paymentMethodIdResponse'
        maskedAccountNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked ACH account number.

            This displays only the last four numbers.

            Example: **************89
          example: '**************89'
        accountRoutingNumber:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the masked ACH routing number.

            Example: 123123123
          example: '123123123'
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
        accountType:
          $ref: '#/components/schemas/AccountType'
        secCode:
          $ref: '#/components/schemas/AchSECCode'
        isSameDayProcessing:
          type: boolean
          nullable: true
          x-method: request
          description: >
            Indicates same-day ACH processing for faster settlement.


            If `true`, the transaction uses the same-day ACH processing.<br>

            If `false`, the transaction does not use the same-day ACH
            processing.<br>

            If null or omitted, the default standard ACH processing is used.


            Example: true
          example: true
        requesterIpAddress:
          maxLength: 45
          minLength: 0
          type: string
          x-method: request
          description: >
            Indicates the IP address of the end user.


            Valid IP address formats are:<br>

            IPv4<br>

            IPv6 format3


            This end user may be the customer, operator, or application
            responsible for submitting the transaction.

            This is required for audit and fraud-detection purposes.


            Example: 192.168.1.1
          example: 192.168.1.1
      additionalProperties: false
    declineDetails:
      type: object
      description: |
        Indicates an object detailing a declined or failed transaction.
        This value is null when the transaction was approved or is pending.
      properties:
        code:
          type: string
          nullable: true
          description: |
            Indicates the decline or failure code from the processor or gateway.

            Example: 41
          example: 41
        message:
          type: string
          nullable: true
          description: |
            Indicates a human-readable decline or failure message.

            Example: Do Not Honor
          example: Do Not Honor
      additionalProperties: false
    TransactionDetailEventTypesArray:
      type: array
      x-method: response
      nullable: true
      description: >
        Indicates an object detailing the chronological list of events that
        occurred for this transaction.
      items:
        type: object
        additionalProperties: false
        properties:
          transactionEventType:
            type: string
            x-method: response
            enum:
              - Authorization
              - Sale
              - Capture
              - Void
              - Refund
              - TipAdjustment
              - CardAuthentication
              - Hold
              - UnHold
              - Credit
              - Settle
            description: >
              Indicates the type of the event.


              Valid values are:


              | Type               |
              Description                                        |

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

              | Authorization      | Authorizes the
              transaction.                        |

              | Capture            | Collects funds from an approved
              authorization.     |

              | CardAuthentication | Confirms cardholder identity before
              payment.       |

              | Credit             | Sends funds back to a cardholder outside a
              refund. |

              | Hold               | Pauses a transaction or account
              temporarily.       |

              | Refund             | Returns funds for a completed
              sale.                |

              | Sale               | Authorizes and captures payment in one
              step.       |

              | Settle             | Submits a batch for final
              processing.              |

              | TipAdjustment      | Adds or changes a tip after the
              sale.              |

              | UnHold             | Removes a hold and resumes normal
              activity.        |

              | Void               | Cancels a transaction before it
              settles.           |


              Example: Authorization
            example: Authorization
          transactionEventStatus:
            type: string
            x-method: response
            enum:
              - Pending
              - Approved
              - Declined
              - Failed
            description: >
              Indicates the status of the event.


              | Value     |
              Description                                               |

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

              | Approved  | The processor approved the
              event.                         |

              | Declined  | The processor declined the
              event.                         |

              | Failed    | The event ended in an error before a processor
              decision.  |

              | Pending   | The event is waiting for a
              result.                        |


              Example: Approved
            example: Approved
          transactionEventDateTime:
            type: string
            format: date-time
            x-method: response
            description: >
              Indicates the date-time (in an ISO 8601 date-time format) the
              event occurred.


              Example: 2026-06-15T14:30:00Z
            example: '2026-06-15T14:30:00Z'
          processedAmount:
            type: number
            format: double
            multipleOf: 0.01
            x-method: response
            description: |
              Indicates the amount (in USD) processed for this event.

              Example: 120.99
            example: 120.99
          originalTransactionId:
            $ref: '#/components/schemas/originalTransactionId'
          declineDetails:
            type: object
            nullable: true
            x-method: response
            description: |
              Indicates an object detailing a declined or failed event.

              This value is null when the event was approved or is pending.
            properties:
              code:
                type: string
                nullable: true
                description: >
                  Indicates the decline or failure code from the processor or
                  gateway.


                  Example: 41
                example: '41'
              message:
                type: string
                nullable: true
                description: |
                  Indicates a human-readable decline or failure message.

                  Example: HOLD-CALL
                example: HOLD-CALL
            additionalProperties: false
    GetTransactionResponseDtoFull:
      type: object
      properties:
        transactionId:
          type: string
          format: uuid
          x-method: response
          nullable: true
          description: |
            Indicates the attached transaction identifier.

            This value is available after processing.

            Example: f01339ec-8184-48c7-b58d-0780d6499ef4
          example: f01339ec-8184-48c7-b58d-0780d6499ef4
        transactionDateTime:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 date-time format) of the
            transaction.


            Example: 2026-05-05T14:30:42.938Z
          example: '2026-05-05T14:30:42.938Z'
        transactionStatus:
          $ref: '#/components/schemas/AggregatedTransactionStatus'
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        cardTokenType:
          $ref: '#/components/schemas/TokenType'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
        referenceId:
          type: string
          x-method: response
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Indicates a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        originalTransactionId:
          $ref: '#/components/schemas/originalTransactionId'
        processedAmount:
          $ref: '#/components/schemas/processedAmount'
        refundDetails:
          $ref: '#/components/schemas/refundDetals'
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        pricingType:
          $ref: '#/components/schemas/PricingType'
        merchantId:
          $ref: '#/components/schemas/merchantId'
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        customerId:
          $ref: '#/components/schemas/customerId'
        batchId:
          $ref: '#/components/schemas/batchId'
        amountBreakdown:
          $ref: '#/components/schemas/AmountBreakdownDto'
        cardDetails:
          $ref: '#/components/schemas/TransactionCardDetailsDto'
        achDetails:
          $ref: '#/components/schemas/AchDetailsDto'
        processorDetails:
          $ref: '#/components/schemas/processorDetails'
        declineDetails:
          $ref: '#/components/schemas/declineDetails'
        addressVerificationServiceResponse:
          $ref: >-
            #/components/schemas/TransactionAddressVerificationServiceResponseDto
        transactionEvents:
          $ref: '#/components/schemas/TransactionDetailEventTypesArray'
        source:
          $ref: '#/components/schemas/source'
      additionalProperties: false
    CaptureRequestDto:
      type: object
      properties:
        captureAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          nullable: true
          description: |
            Specifies the amount to capture (in USD).

            If null or omitted, the full authorized amount is captured.<br>
            If an amount is specified, a partial amount is captured.

            This value must both:
            * Be greater than zero
            * Not exceed the remaining authorized amount.

            Examples:<br>
            null<br>
            129.99
          example: 129.99
      additionalProperties: false
      description: >
        Specifies an object describing the capture request.


        Omit amount or send empty body for full capture; set `captureAmount` for
        partial capture.
    ReversalRequestDto:
      type: object
      properties:
        reversalAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          nullable: true
          description: >
            Specifies the amount (in USD) to refund.


            If a value is provided, the refund is for partial card refunds
            only.<br>

            If null or omitted, the full transaction amount is refunded.


            Do not use this value for void operations and ACH refunds.


            Example: 50.24
          example: 50.24
      additionalProperties: false
      description: >
        Request to refund, or reverse, a transaction.


        The backend automatically determines whether to void or refund based on
        the transaction's settlement status.
    CreditDetailsDto:
      type: object
      properties:
        cardData:
          $ref: '#/components/schemas/CardDataDto'
        achData:
          $ref: '#/components/schemas/AchDataDto'
      additionalProperties: false
      description: |
        Specifies credit payment method details.

        Either `cardData` or `achData` must be provided.
    CreditRequestDto:
      type: object
      description: >
        Request to create an unreferenced credit (card unreferenced refund or
        ACH credit).
      properties:
        paymentProcessorId:
          $ref: '#/components/schemas/paymentprocessorid'
        baseAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: request
          description: |
            Specifies the base transaction amount before adjustments.

            Example: 99.99
          example: 99.99
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        referenceId:
          type: string
          x-method: request
          nullable: true
          minLength: 0
          maxLength: 36
          description: >
            Specifies a reference identifier provided by the merchant.


            This is included in the duplicate-check key.

            It allows the same card and amount combination to be charged
            multiple times when the reference identifiers are different.


            Example: REF-EXT-12345
          example: REF-EXT-12345
        creditDetails:
          $ref: '#/components/schemas/CreditDetailsDto'
        billingAddress:
          $ref: '#/components/schemas/AddressDto'
        shippingAddress:
          $ref: '#/components/schemas/AddressDto'
        contactInfo:
          $ref: '#/components/schemas/ContactInfoDto'
        customerId:
          $ref: '#/components/schemas/customerId'
      additionalProperties: false
    TipAdjustmentRequestDto:
      type: object
      properties:
        tipAmount:
          type: number
          format: double
          x-method: request
          multipleOf: 0.01
          description: >
            Specifies the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          x-method: response
          multipleOf: 0.01
          description: >
            Specifies a percentage of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            <br><span class="note">

            Care must be taken that a value other than zero can be provided to
            either `tipAmount` or `tipRate`.

            A non-zero value cannot be provided to both.

            </span><br>


            Example: 18.50 (for 18.50%)
          example: 18.5
      additionalProperties: false
      description: Request to adjust the tip amount on a card transaction.
    ZeroCostProcessingOptionDto:
      enum:
        - None
        - CashDiscount
        - DualPricing
        - Surcharge
      type: string
      description: >
        Indicates the ZCP (zero cost processing) options.


        Valid values are:


        | Type          | Description                                        |

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

        | CashDiscount   | Listed price includes a discount for cash payment.   
        |

        | DualPricing    | Displays a separate price for cash and card.         
        |

        | None           | No zero cost processing program applied.             
        |

        | Surcharge      | Adds a fee to the card price at checkout.            
        |


        Example: CashDiscount
      example: CashDiscount
    CalculatedAmountDto:
      type: object
      properties:
        baseAmount:
          $ref: '#/components/schemas/baseAmount'
        discountAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: response
          description: |
            Indicates the discount amount (in USD) applied.

            Example: 22.5 (for $22.5)
          example: 22.5
        discountRate:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the discount percent applied.

            Example: 18.5 (for 18.5%)
          example: 18.5
        surchargeAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: response
          description: |
            Indicates the surcharge amount (in USD) applied.

            Example: 12.75 (for $12.75)
          example: 12.75
        surchargeRate:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the surcharge percent applied.

            Example: 8.25 (for 8.25%)
          example: 8.25
        tipAmount:
          type: number
          format: double
          x-method: response
          multipleOf: 0.01
          description: >
            Indicates the absolute amount (in USD) of the tip to be added.


            If this value is provided, it must be greater than zero.


            This amount adds to the base amount of the original transaction.

            That transaction must be authorized first (`POST
            /pay-api/v1/transactions/auth`).


            Example: 14.50 (for $14.50)
          example: 14.5
        tipRate:
          type: number
          format: double
          x-method: response
          description: |
            Indicates the tip percent applied.

            Example: 15.25 (for 15.25%)
          example: 15.25
        totalAmount:
          type: number
          format: double
          multipleOf: 0.01
          x-method: response
          description: |
            Indicates the final total amount  (in USD).

            Example: 124.99
          example: 124.99
      additionalProperties: false
      description: Amount breakdown for a specific payment method.
    CalculateAmountResponseDto:
      type: object
      properties:
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        zeroCostProcessingOption:
          $ref: '#/components/schemas/ZeroCostProcessingOptionDto'
        pricingType:
          $ref: '#/components/schemas/PricingType'
        cash:
          $ref: '#/components/schemas/CalculatedAmountDto'
        creditCard:
          $ref: '#/components/schemas/CalculatedAmountDto'
        debitCard:
          $ref: '#/components/schemas/CalculatedAmountDto'
        ach:
          $ref: '#/components/schemas/CalculatedAmountDto'
      additionalProperties: false
      description: Calculated transaction amounts for different payment methods.
    SendReceiptRequestDto:
      required:
        - hasCustomerConsent
        - recipient
        - shareBy
      type: object
      properties:
        shareBy:
          type: string
          x-method: request
          format: E.164
          minLength: 1
          maxLength: 20
          pattern: ^(null|\+\d{1,20})$
          description: |
            Specifies the method that shares this receipt.

            Valid values are:

            | Value  | Description                                         |
            | ------ | --------------------------------------------------- |
            | Email  | The system sends the notification by email.         |
            | None   | The system does not send a notification.            |
            | Sms    | The system sends the notification by text message.  |

            Example: Sms
          example: Sms
        recipient:
          type: string
          x-method: request
          format: E.164
          minLength: 1
          maxLength: 20
          pattern: ^\+[1-9][0-9]{0,14}$
          description: >
            Specifies the customer's mobile phone number.


            This value is required only for SMS messages.


            A receipt can be sent to any phone number the customer provides at
            time of receipt.


            Example: +14155552309
          example: '+14155552309'
        hasCustomerConsent:
          type: boolean
          x-method: request
          description: |
            Specifies the customer has consented to receive the SMS.

            If `true`, the customer has consented to receive the SMS.<br>
            If `false`, the customer has not consented to receive the SMS.

            Example: true
          example: true
      additionalProperties: false
      description: Request to send a transaction receipt by SMS.
    WebhookEndpointStatusResponse:
      enum:
        - Active
        - Inactive
      type: string
      nullable: true
      description: >
        Indicates the endpoint status.


        Valid values are:

        | Value     | Description                                      |

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

        | Active    | The webhook endpoint is enabled and available for
        use.       |

        | Inactive  | The webhook endpoint is disabled and not available for
        use.<br><br>It still exists but will not send event notifications. It
        may be re-activated. In contrast, a deleted webhook has been removed
        entirely and cannot be re-activated. A new webhook must be created. |


        Example: Active
      example: Active
    WebhookEventType:
      enum:
        - api_key.created
        - api_key.deleted
        - invoice.created
        - invoice.paid
        - merchant.created
        - payment_session.completed
        - payment_session.created
        - quick_payment.created
        - quick_payment.paid
        - settlement.batch.completed
        - subscription.created
        - subscription.delinquent
        - subscription.paid
        - subscription.payment_failed
        - terminal.added
        - terminal.deactivated
        - terminal.out_of_paper
        - transaction.ach.cancelled
        - transaction.ach.charged_back
        - transaction.ach.cleared
        - transaction.ach.failed
        - transaction.ach.held
        - transaction.ach.in_progress
        - transaction.ach.refunded
        - transaction.ach.scheduled
        - transaction.card.authorized
        - transaction.card.captured
        - transaction.card.declined
        - transaction.card.failed
        - transaction.card.refunded
        - transaction.card.voided
      type: string
      description: >
        <br>Identifies events that are subscribed to.


        Valid values are:


        | Wire value                    | Meaning | Group
        |                                                                                                   

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

        | api_key.created               | An API key was created | API Keys
        (affiliate only)
        |                                                                

        | api_key.deleted               | An API key was revoked or deleted |
        API Keys (affiliate only)
        |                                                     

        | invoice.created               | A new invoice was created | Invoices
        |                                                                              

        | invoice.paid                  | An invoice was marked as paid |
        Invoices
        |                                                                          

        | merchant.created              | A new merchant account was created |
        Merchants (affiliate only)
        |                                                 

        | payment_session.completed     | A payment session reached a terminal
        state (completed, failed, or cancelled) | Payment Sessions |

        | payment_session.created       | A payment session was created |
        Payment Sessions |

        | quick_payment.created         | A quick payment link was created |
        Quick Payments |

        | quick_payment.paid            | A quick payment link was paid | Quick
        Payments |

        | settlement.batch.completed    | A batch settlement was processed and
        settled | Settlement |

        | subscription.created          | A new subscription was created |
        Subscriptions |

        | subscription.delinquent       | A subscription entered a delinquent
        state after repeated payment failures | Subscriptions |

        | subscription.paid             | A subscription payment was
        successfully collected | Subscriptions |

        | subscription.payment_failed   | A subscription payment attempt failed
        | Subscriptions |

        | terminal.added                | A new terminal was registered to the
        account | Terminals |

        | terminal.deactivated          | A terminal was deactivated on the
        account | Terminals |

        | terminal.out_of_paper         | A terminal paper roll is empty |
        Terminals |

        | transaction.ach.cancelled     | An ACH transaction was cancelled
        before processing | ACH Transactions |

        | transaction.ach.charged_back  | An ACH transaction was returned or
        charged back | ACH Transactions |

        | transaction.ach.cleared       | An ACH transaction successfully
        cleared | ACH Transactions |

        | transaction.ach.failed        | An ACH transaction failed due to a
        processing error | ACH Transactions |

        | transaction.ach.held          | An ACH transaction was placed on hold
        for review | ACH Transactions |

        | transaction.ach.in_progress   | An ACH transaction was submitted to
        the network | ACH Transactions |

        | transaction.ach.refunded      | An ACH transaction was refunded to the
        originator | ACH Transactions |

        | transaction.ach.scheduled     | An ACH transaction was created and
        scheduled | ACH Transactions |

        | transaction.card.authorized   | A card payment authorization was
        approved | Card Transactions |

        | transaction.card.captured     | An authorized card payment was
        captured | Card Transactions |

        | transaction.card.declined     | A card payment was declined by the
        issuer | Card Transactions |

        | transaction.card.failed       | A card payment failed due to a
        processing error | Card Transactions |

        | transaction.card.refunded     | A card payment was refunded to the
        cardholder | Card Transactions |

        | transaction.card.voided       | A card authorization was voided before
        capture | Card Transactions |


        Examples:<br>

        null<br>

        [ "transaction.card.captured" ]<br>

        [ "transaction.card.captured", "transaction.card.authorized" ]
      example:
        - transaction.card.captured
        - transaction.card.refunded
        - settlement.batch.completed
        - null
    GetWebhookEndpointIsvResponseDto:
      type: object
      properties:
        endpointId:
          type: string
          format: uuid
          description: |
            Indicates the webhook endpoint identifier.

            Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
          example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
        endpointName:
          type: string
          nullable: true
          maxLength: 255
          description: |
            Indicates the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          nullable: true
          x-method: response
          description: |
            Indicates the HTTPS callback URL that receives webhook events.

            Examples: https://example.com/webhooks/pepparedstreetcafe<br>
          example: https://example.com/webhooks/pepparedstreetcafe
        endpointStatus:
          $ref: '#/components/schemas/WebhookEndpointStatusResponse'
        eventTypes:
          $ref: '#/components/schemas/WebhookEventType'
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was created on.


            Example: 2026-05-05T14:30:36.759Z
          example: '2026-05-05T14:30:36.759Z'
        modifiedOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was last modified.


            Example: 2026-07-10T03:22:47.918Z
          example: '2026-07-10T03:22:47.918Z'
      additionalProperties: false
      example:
        items:
          - endpointId: 633649fc-9d16-4d1b-98ec-73a3282427fc
            endpointName: Peppared Street Cafe's Reconciliation
            endpointUrl: https://example.com/webhooks/pepparedstreetcafe
            endpointStatus: Active
            eventTypes:
              - transaction.card.captured
              - settlement.batch.completed
            createdOn: '2026-05-05T14:30:36.759Z'
            modifiedOn: '2026-07-10T03:22:47.918Z'
    ListWebhookEndpointsIsvResponseDto:
      type: object
      properties:
        data:
          type: array
          nullable: true
          x-method: response
          description: Indicates an object list of webhook details.
          items:
            $ref: '#/components/schemas/GetWebhookEndpointIsvResponseDto'
      additionalProperties: false
    CreateWebhookEndpointIsvResponseDto:
      type: object
      properties:
        endpointId:
          type: string
          format: uuid
          x-method: response
          description: |
            Indicates the webhook endpoint identifier.

            Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
          example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
        endpointName:
          type: string
          nullable: true
          x-method: response
          maxLength: 255
          description: |
            Indicates the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          nullable: true
          x-method: response
          description: |
            Indicates the HTTPS callback URL that receives webhook events.

            Example: https://example.com/webhooks/pepparedstreetcafe
          example: https://example.com/webhooks/pepparedstreetcafe
        endpointStatus:
          $ref: '#/components/schemas/WebhookEndpointStatusResponse'
        hmacSecret:
          type: string
          nullable: true
          x-method: response
          description: |
            Indicates the HMAC signing secret used to verify webhook payloads.

            This value is returned only on creation and is never shown again.
        eventTypes:
          $ref: '#/components/schemas/WebhookEventType'
        createdOn:
          type: string
          format: date-time
          x-method: response
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was created on.


            Example: 2026-01-15T10:30:56.264Z
          example: '2026-01-15T10:30:56.264Z'
      additionalProperties: false
    updatewebhookendpointisvrequestdto:
      type: object
      properties:
        endpointName:
          type: string
          nullable: true
          maxLength: 255
          description: |
            Specifies the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          nullable: true
          x-method: request
          description: |
            Specifies the HTTPS callback URL that receives webhook events.

            Example: https://example.com/webhooks/pepparedstreetcafe
          example: https://example.com/webhooks/pepparedstreetcafe
        endpointStatus:
          type: string
          enum:
            - Active
            - Inactive
          description: >
            Specifies the webhook state.


            Valid values are:

            | Value     | Description                                      |

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

            | Active    | The webhook endpoint is enabled and available for
            use.       |

            | Inactive  | The webhook endpoint is disabled and not available for
            use.<br><br>It still exists but will not send event notifications.
            It may be re-activated. In contrast, a deleted webhook has been
            removed entirely and cannot be re-activated. A new webhook must be
            created.<br><br>Any delivery attempts still queued for an endpoint
            that becomes `Inactive` is force-terminated as `Failed` rather than
            retried again.<br><br>Inactive endpoints can still be pinged
            manually. |


            Example: Active
          example: Active
        eventTypes:
          $ref: '#/components/schemas/WebhookEventType'
      additionalProperties: false
    pingwebhookisvresponsedto:
      type: object
      properties:
        isDelivered:
          type: boolean
          x-method: response
          description: |
            Indicates the ping was delivered successfully.

            If `true`, the ping was delivered successfully.<br>
            If `false`, the ping was not delivered successfully.

            Example: true
          example: true
        endpointHTTPResponseCode:
          type: integer
          format: int32
          nullable: true
          description: >
            Indicates the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning            |

            |:-----------:|--------------------|

            | 200         | Delivery succeeded |

            | 400         | Bad request        |

            | 401         | Unauthorized       |

            | 404         | Endpoint not found |

            | 429         | Rate limited       |


            Example: 200
          example: 200
        roundTripDurationMs:
          type: integer
          format: int32
          description: |
            Indicates the round-trip duration (in milliseconds).

            Example: 367
          example: 367
        errorMessage:
          type: string
          nullable: true
          description: |
            Indicates an error message if the delivery failed.

            Example: Recipient not available
          example: Recipient not available
      additionalProperties: false
    webhookdeliverylogstatus:
      type: string
      enum:
        - Success
        - Failure
      description: |
        Indicates the webhook delivery log status.

        Valid values are:

        | Status  | Explanation                                   |
        |---------|-----------------------------------------------|
        | Failure | The webhook delivery attempt did not succeed. |
        | Success | The webhook delivery attempt succeeded.       |

        Example: Success
      example: Success
    webhookdeliverylogisvsummarydto:
      type: object
      properties:
        deliveryLogId:
          type: string
          format: uuid
          description: |
            Indicates the webhook delivery log identifier to retrieve.

            Example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
          example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
        endpointId:
          type: string
          format: uuid
          description: |
            Indicates the webhook endpoint identifier.

            Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
          example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
        endpointName:
          type: string
          nullable: true
          description: |
            Indicates the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          nullable: true
          x-method: response
          description: |
            Indicates the HTTPS callback URL that receives webhook events.

            Example: https://example.com/webhooks/pepparedstreetcafe
          example: https://example.com/webhooks/pepparedstreetcafe
        eventId:
          type: string
          format: uuid
          description: |
            Indicates the event identifier.

            Example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
          example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
        eventType:
          $ref: '#/components/schemas/WebhookEventType'
        attemptNumber:
          type: integer
          format: int32
          description: |
            Indicates the current delivery attempt number for the webhook.

            Example: 3
          example: 3
        status:
          $ref: '#/components/schemas/webhookdeliverylogstatus'
        endpointHTTPResponseCode:
          type: integer
          format: int32
          nullable: true
          description: >
            Indicates the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning            |

            |:-----------:|--------------------|

            | 200         | Delivery succeeded |

            | 400         | Bad request        |

            | 401         | Unauthorized       |

            | 404         | Endpoint not found |

            | 429         | Rate limited       |


            Example: 200
          example: 200
        roundTripDurationMs:
          type: integer
          format: int32
          description: |
            Indicates the round-trip duration (in milliseconds).

            Example: 367
          example: 367
        errorMessage:
          type: string
          nullable: true
          description: |
            Indicates an error message if the delivery failed.

            Example: Recipient not available
          example: Recipient not available
        createdOn:
          type: string
          format: date-time
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was created on.


            Example: 2025-01-27T12:05:54.322Z
          example: '2025-01-27T12:05:54.322Z'
      additionalProperties: false
    listwebhookdeliverylogsisvresponsedto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/webhookdeliverylogisvsummarydto'
          nullable: true
        pageInfo:
          $ref: '#/components/schemas/pageInfo'
      additionalProperties: false
    webhookdeliverylogisvdetaildto:
      type: object
      properties:
        deliveryLogId:
          type: string
          format: uuid
          description: |
            Indicates the webhook delivery log identifier to retrieve.

            Example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
          example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
        endpointId:
          type: string
          format: uuid
          description: |
            Indicates the webhook endpoint identifier.

            Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
          example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
        endpointName:
          type: string
          nullable: true
          description: |
            Indicates the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          x-method: response
          nullable: true
          description: |
            Indicates the HTTPS callback URL that receives webhook events.

            Example: https://example.com/webhooks/pepparedstreetcafe
          example: https://example.com/webhooks/pepparedstreetcafe
        eventId:
          type: string
          format: uuid
          description: |
            Indicates the event identifier.

            Example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
          example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
        eventType:
          $ref: '#/components/schemas/WebhookEventType'
        attemptNumber:
          type: integer
          format: int32
          description: |
            Indicates the current delivery attempt number for the webhook.

            Example: 3
          example: 3
        deliveryLogStatus:
          $ref: '#/components/schemas/webhookdeliverylogstatus'
        endpointHTTPResponseCode:
          type: integer
          format: int32
          nullable: true
          description: >
            Indicates the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning            |

            |:-----------:|--------------------|

            | 200         | Delivery succeeded |

            | 400         | Bad request        |

            | 401         | Unauthorized       |

            | 404         | Endpoint not found |

            | 429         | Rate limited       |


            Example: 200
          example: 200
        roundTripDurationMs:
          type: integer
          format: int32
          description: |
            Indicates the round-trip duration (in milliseconds).

            Example: 367
          example: 367
        errorMessage:
          type: string
          nullable: true
          description: |
            Indicates an error message if the delivery failed.

            Example: Recipient not available
          example: Recipient not available
        createdOn:
          type: string
          format: date-time
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was created on.


            Example: 2025-01-27T12:05:54.322Z
          example: '2025-01-27T12:05:54.322Z'
        nextRetryAt:
          type: string
          format: date-time
          nullable: true
          description: >
            Indicates the timestamp (in an ISO 8601 date-time UTC format) of the
            next retry attempt.


            This value may be null if an attempt succeeded or there is no next
            retry attempt.


            Example: 2026-02-19T20:24:52.934Z
          example: '2026-02-19T20:24:52.934Z'
        requestHeaders:
          type: object
          nullable: true
          description: |
            Indicates an object describing the request headers.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
        requestBody:
          type: string
          nullable: true
          description: |
            Indicates the request body.
        responseHeaders:
          type: object
          nullable: true
          description: |
            Indicates an object describing the response headers.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
        responseBody:
          type: string
          nullable: true
          description: |
            Indicates the response body.
      additionalProperties: false
    retrywebhookdeliveryisvresponsedto:
      type: object
      properties:
        deliveryLogId:
          type: string
          format: uuid
          description: |
            Indicates the webhook delivery log identifier to retrieve.

            Example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
          example: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25
        endpointId:
          type: string
          format: uuid
          description: |
            Indicates the webhook endpoint identifier.

            Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
          example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36
        endpointName:
          type: string
          nullable: true
          maxLength: 255
          description: |
            Indicates the display name for the webhook.

            This is a free-formed name that is convenient to recognize.

            Example: Peppared Street Cafe's Reconciliation
          example: Peppared Street Cafe's Reconciliation
        endpointUrl:
          type: string
          maxLength: 2048
          x-method: response
          description: |
            Indicates the HTTPS callback URL that receives webhook events.

            Example: https://example.com/webhooks/pepparedstreetcafe
          example: https://example.com/webhooks/pepparedstreetcafe
          nullable: true
        eventId:
          type: string
          format: uuid
          description: |
            Indicates the event identifier.

            Example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
          example: 399f9d7d-0714-453c-9b6d-dda836e1d8e6
        eventType:
          $ref: '#/components/schemas/WebhookEventType'
        deliveryLogStatus:
          $ref: '#/components/schemas/webhookdeliverylogstatus'
        attemptNumber:
          type: integer
          format: int32
          description: |
            Indicates the current delivery attempt number for the webhook.

            Example: 3
          example: 3
        endpointHTTPResponseCode:
          type: integer
          format: int32
          nullable: true
          description: >
            Indicates the HTTP response status code.


            This is the HTTP status code returned by the attempted delivery.


            The following is a list of HTTP response status codes that include
            but are not limited to:


            | HTTP Status | Meaning            |

            |:-----------:|--------------------|

            | 200         | Delivery succeeded |

            | 400         | Bad request        |

            | 401         | Unauthorized       |

            | 404         | Endpoint not found |

            | 429         | Rate limited       |


            Example: 200
          example: 200
        roundTripDurationMs:
          type: integer
          format: int32
          description: |
            Indicates the round-trip duration (in milliseconds).

            Example: 367
          example: 367
        errorMessage:
          type: string
          nullable: true
          description: |
            Indicates an error message if the delivery failed.

            Example: Recipient not available
          example: Recipient not available
        createdOn:
          type: string
          format: date-time
          description: >
            Indicates the date-time (in an ISO 8601 UTC date-time format) the
            webhook was created on.


            Example: 2025-01-27T12:05:54.322Z
          example: '2025-01-27T12:05:54.322Z'
        nextRetryAt:
          type: string
          format: date-time
          nullable: true
          description: >
            Indicates the timestamp (in an ISO 8601 date-time UTC format) of the
            next retry attempt.


            This value may be null if an attempt succeeded or there is no next
            retry attempt.


            Example: 2026-02-19T20:24:52.934Z
          example: '2026-02-19T20:24:52.934Z'
        requestHeaders:
          type: object
          nullable: true
          description: |
            Indicates an object describing the request headers.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
        requestBody:
          type: object
          nullable: true
          description: |
            Indicates an object describing the request body.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
        responseHeaders:
          type: object
          nullable: true
          description: |
            Indicates an object describing the response headers.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
        responseBody:
          type: object
          nullable: true
          description: |
            Indicates an object describing the response body.
          additionalProperties:
            type: string
            nullable: true
            description: |
              This object may not contain fields that are predefined.

              Review the actual returned fields for names and values.
      additionalProperties: false
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            errors:
              Email:
                - '''Email'' is not a valid email address.'
            details: One or more validation errors occurred.
            statusCode: 400
            source: <Service>
            exceptionType: ValidationException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: V0000
            title: Validation failed
            cause: One or more fields failed validation rules.
            resolution: Review the errors and correct the invalid fields.
            documentationUrl: https://developer.flute.com/
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            errors:
              BearerTokenError:
                - >-
                  invalid_token, error_description='The token expired at
                  '06/29/2026 21:08:02''
            details: One or more validation errors occurred.
            statusCode: 401
            source: <Service>
            exceptionType: UnauthorizedException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: V0000
            title: Validation failed
            cause: One or more fields failed validation rules.
            resolution: Review the errors and correct the invalid fields.
            documentationUrl: https://developer.flute.com/
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            details: The payment was declined by the processor.
            statusCode: 402
            source: <Service>
            exceptionType: PaymentFailedException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: P0000
            title: Payment failed
            cause: The payment was declined by the payment processor.
            resolution: >-
              Verify payment details, check available funds, or try a different
              payment method.
            documentationUrl: https://developer.flute.com/
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationExceptionExample'
          example:
            details: You do not have permission to access this resource.
            statusCode: 403
            source: <Service>
            exceptionType: ForbiddenException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: F0000
            title: Access forbidden
            cause: You do not have permission to access this resource.
            resolution: >-
              Verify your credentials and permissions or contact your
              administrator."
            documentationUrl: https://developer.flute.com/
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            details: >-
              Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist
              or has been deleted.
            statusCode: 404
            source: <Service>
            exceptionType: NotFoundException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: b31fbe9f-eebb-45ce-9cae-92265389f47f
            errorCode: N0000
            title: Resource not found
            cause: The requested resource does not exist or has been deleted.
            resolution: >-
              Verify the resource ID is correct or retrieve a list of available
              resources.
            documentationUrl: https://developer.flute.com/
    '409':
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            details: The request conflicts with the current state of the resource.
            statusCode: 409
            source: <Service>
            exceptionType: ConflictException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: C0000
            title: Resource conflict
            cause: The request conflicts with the current state of the resource.
            resolution: >-
              Refresh the resource state and retry the operation, or use a
              different idempotency key.
            documentationUrl: https://developer.flute.com/
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            details: Too many requests sent in a short period.
            statusCode: 429
            source: <Service>
            exceptionType: RateLimitExceededException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: R0000
            title: Rate limit exceeded
            cause: Too many requests sent in a short period.
            resolution: >-
              Wait before retrying the request. Check the Retry-After header for
              more information.
            documentationUrl: https://developer.flute.com/
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonExceptionExample'
          example:
            details: An unexpected error occurred while processing the request.
            statusCode: 500
            source: <Service>
            exceptionType: IntegrationException
            correlationId: aa6cfcd0-0295-4a4c-b074-8c901f114fee
            entityId: null
            errorCode: I0000
            title: Internal server error
            cause: An unexpected error occurred while processing the request
            resolution: >-
              Please contact support with the correlation ID if the issue
              persists.
            documentationUrl: https://developer.flute.com/
  parameters:
    page:
      name: pageIndex
      in: query
      description: >
        Specifies the page number of the returned search results.


        A page is considered each set of the `pageSize` values.


        The page count is zero-based.

        The maximum for `pageIndex`, or the page number, is the `pageSize`
        divided by the `total` count rounded down.

        For example, the `pageSize` is 50 and the `total` is 130.

        That means there are three pages, but the `pageIndex` value is in the
        inclusive range from zero to two.


        Value restrictions include:

        * A value less than zero is not permitted.<br>

        * Values equal to or greater than `totalPages` end successfully but will
        not return any items.


        For page size information, see `pageSize`.


        Example: 0
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
        x-method: query
    pagesize:
      name: pageSize
      in: query
      description: >
        Specifies the number of items for each page of the returned search
        results.


        A page is considered each set of the `pageSize` values.


        The page count is zero-based.

        The maximum for `pageIndex`, or the page number, is the `pageSize`
        divided by the `total` count rounded down.

        For example, the `pageSize` is 50 and the `total` is 130.

        That means there are three pages, but the `pageIndex` value is in the
        inclusive range from zero to two.


        For page numbering information, see `pageIndex`.


        Example: 50
      schema:
        type: integer
        format: int32
        default: 20
        minimum: 1
        maximum: 100
        x-method: query
    asc:
      name: asc
      in: query
      description: |
        Specifies the sort order is ascending.

        The sort field is specified by the `orderBy` value.

        If `true`, the sort order is ascending.<br>
        If `false`, the sort order is descending.

        Example: true
      schema:
        type: boolean
        default: true
        x-method: query
    sortby:
      name: sortBy
      in: query
      description: |
        Specifies the field the results get ordered or sorted by.

        The sort order is specified by the `sortOrder` value.<br>
        The field that gets sorted by is specified by the `sortBy` value.
      example: ContactName
      schema:
        type: string
        x-method: query
    createdFrom:
      name: createdFrom
      in: query
      required: false
      description: >
        Filters by the earliest inclusive created date (in an ISO 8601 date-time
        UTC format).


        If only `createdFrom` is specified, the search returns all available
        items from the `createdFrom` value to the present.

        The fields `createdFrom` and `createdTo` may be used together to create
        an inclusive range.

        We recommend creating an inclusive range to avoid a potentially
        excessive number of returns.
      schema:
        type: string
        format: date-time
        example: '2026-02-19T20:24:52.934Z'
    createdTo:
      name: createdTo
      in: query
      required: false
      description: >
        Filters by the latest inclusive created date (in an ISO 8601 date-time
        UTC format).


        If only `createdFrom` is specified, the search returns all available
        items from the `createdFrom` value to the present.

        The fields `createdFrom` and `createdTo` may be used together to create
        an inclusive range.

        We recommend creating an inclusive range to avoid a potentially
        excessive number of returns.
      schema:
        type: string
        format: date-time
        example: '2026-03-06T14:24:52.934Z'
    sortOrder:
      name: sortOrder
      in: query
      description: |
        Specifies the sort order.

        The sort order is specified by the `sortOrder` value.<br>
        The field that gets sorted by is specified by the `sortBy` value.

        Valid values are:

        | Value  | Description                                               |
        | ------ | --------------------------------------------------------- |
        | asc    | Sort results from the lowest value to the highest value.  |
        | desc   | Sort results from the highest value to the lowest value.  |
      example: desc
      schema:
        type: string
        x-method: query
        default: asc
    dateFrom:
      name: dateFrom
      in: query
      description: >
        Filters returning items on or after this date (in an ISO 8601 date-time
        format).


        If only `dateFrom` is specified, the search returns all available items
        from the `dateFrom` value to the present.

        The fields `dateFrom` and `dateTo` may be used together to create an
        inclusive range.

        We recommend creating an explicit range to avoid a potentially excessive
        number of returns.
      schema:
        type: string
        format: date-time
        example: '2025-01-27T12:05:54.322Z'
    dateTo:
      name: dateTo
      in: query
      description: >
        Filters returning items on or to this date (in an ISO 8601 date-time
        format).


        If only `dateTo` is specified, the search returns all available items
        before including the `dateTo` value.

        The fields `dateFrom` and `dateTo` may be used together to create an
        inclusive range.

        We recommend creating an explicit range to avoid a potentially excessive
        number of returns.
      schema:
        type: string
        format: date-time
        example: '2026-02-27T12:05:54.322Z'
    SettlementBatchStatus:
      name: status
      in: query
      required: false
      description: >
        Identifies the batch settlement type.


        Valid values are:


        | Batch Type | Meaning |

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

        | Open       | An open batch is still active and accepting transactions.
        |

        | Settled    | A settled batch has completed processing with the
        acquirer or bank. |


        Example: Open
      schema:
        type: string
        example: Open
    AggregatedTransactionParameterStatus:
      name: transactionStatus
      in: query
      description: >
        Specifies a filter by the aggregated transaction status.


        Valid values are:


        | Status                |
        Description                                         | Type |

        |-----------------------|-----------------------------------------------------|:----:|

        | Authorized            | Payment approved but funds not yet
        captured.        | Card |

        | Cancelled             | Transaction stopped before it
        completed.            | ACH  |

        | Captured              | Approved funds collected from the
        card.             | Card |

        | ChargedBack           | Cardholder disputed the charge with their
        bank.| ACH  |

        | Cleared               | Funds finished processing and
        settled.              | ACH  |

        | Declined              | Payment rejected by the bank or
        processor.          | Card/ACH |

        | Failed                | Transaction could not complete due to an
        error.     | Card/ACH |

        | Held                  | Transaction paused and awaiting
        release.            | ACH  |

        | HeldByProcessor       | Processor paused the transaction for
        review.        | ACH  |

        | Informational         | Record used for reference only, not a live
        charge.  | Card |

        | InProgress            | Transaction is still
        processing.                    | ACH  |

        | PartiallyAuthorized   | Only part of the requested amount was
        approved.     | Card |

        | Pending               | Transaction is waiting for a
        result.                | Card/ACH |

        | Refunded              | Funds returned to the
        cardholder.                   | Card |

        | Scheduled             | Transaction set to run at a future
        time.            | ACH  |

        | Settled               | Funds moved from issuer to the merchant
        account.    | Card |

        | Verified              | Card or account confirmed as
        valid.                 | Card |

        | Voided                | Authorization cancelled before
        capture.             | Card |
      schema:
        type: string
        example: Authorized
        enum:
          - Authorized
          - Cancelled
          - Captured
          - ChargedBack
          - Cleared
          - Declined
          - Failed
          - Held
          - HeldByProcessor
          - Informational
          - InProgress
          - PartiallyAuthorized
          - Pending
          - Refunded
          - Scheduled
          - Settled
          - Verified
          - Voided
    WebhookEventTypeQuery:
      name: eventType
      in: query
      required: false
      description: >
        Filters delivery logs to a single event type.


        Omit this parameter to include all event types.


        Valid values are:


        | Wire value                    | Meaning | Group |

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

        | api_key.created               | An API key was created | API Keys
        (affiliate only) |

        | api_key.deleted               | An API key was revoked or deleted |
        API Keys (affiliate only) |

        | invoice.created               | A new invoice was created | Invoices |

        | invoice.paid                  | An invoice was marked as paid |
        Invoices |

        | merchant.created              | A new merchant account was created |
        Merchants (affiliate only) |

        | payment_session.completed     | A payment session reached a terminal
        state (completed, failed, or cancelled) | Payment Sessions |

        | payment_session.created       | A payment session was created |
        Payment Sessions |

        | quick_payment.created         | A quick payment link was created |
        Quick Payments |

        | quick_payment.paid            | A quick payment link was paid | Quick
        Payments |

        | settlement.batch.completed    | A batch settlement was processed and
        settled | Settlement |

        | subscription.created          | A new subscription was created |
        Subscriptions |

        | subscription.delinquent       | A subscription entered a delinquent
        state after repeated payment failures | Subscriptions |

        | subscription.paid             | A subscription payment was
        successfully collected | Subscriptions |

        | subscription.payment_failed   | A subscription payment attempt failed
        | Subscriptions |

        | terminal.added                | A new terminal was registered to the
        account | Terminals |

        | terminal.deactivated          | A terminal was deactivated on the
        account | Terminals |

        | terminal.out_of_paper         | A terminal paper roll is empty |
        Terminals |

        | transaction.ach.cancelled     | An ACH transaction was cancelled
        before processing | ACH Transactions |

        | transaction.ach.charged_back  | An ACH transaction was returned or
        charged back | ACH Transactions |

        | transaction.ach.cleared       | An ACH transaction successfully
        cleared | ACH Transactions |

        | transaction.ach.failed        | An ACH transaction failed due to a
        processing error | ACH Transactions |

        | transaction.ach.held          | An ACH transaction was placed on hold
        for review | ACH Transactions |

        | transaction.ach.in_progress   | An ACH transaction was submitted to
        the network | ACH Transactions |

        | transaction.ach.refunded      | An ACH transaction was refunded to the
        originator | ACH Transactions |

        | transaction.ach.scheduled     | An ACH transaction was created and
        scheduled | ACH Transactions |

        | transaction.card.authorized   | A card payment authorization was
        approved | Card Transactions |

        | transaction.card.captured     | An authorized card payment was
        captured | Card Transactions |

        | transaction.card.declined     | A card payment was declined by the
        issuer | Card Transactions |

        | transaction.card.failed       | A card payment failed due to a
        processing error | Card Transactions |

        | transaction.card.refunded     | A card payment was refunded to the
        cardholder | Card Transactions |

        | transaction.card.voided       | A card authorization was voided before
        capture | Card Transactions |
      example: transaction.card.captured
      schema:
        type: string
        enum:
          - api_key.created
          - api_key.deleted
          - invoice.created
          - invoice.paid
          - merchant.created
          - payment_session.completed
          - payment_session.created
          - quick_payment.created
          - quick_payment.paid
          - settlement.batch.completed
          - subscription.created
          - subscription.delinquent
          - subscription.paid
          - subscription.payment_failed
          - terminal.added
          - terminal.deactivated
          - terminal.out_of_paper
          - transaction.ach.cancelled
          - transaction.ach.charged_back
          - transaction.ach.cleared
          - transaction.ach.failed
          - transaction.ach.held
          - transaction.ach.in_progress
          - transaction.ach.refunded
          - transaction.ach.scheduled
          - transaction.card.authorized
          - transaction.card.captured
          - transaction.card.declined
          - transaction.card.failed
          - transaction.card.refunded
          - transaction.card.voided
