{ "openapi": "3.0.3", "info": { "title": "Flute - API Reference Guide", "version": "V2 Beta", "description": "Build date: 8.13.2026 10:19 AM\n\n
\n⚠️ Beta Release\n\nThe v2 API is currently in active development. \n\nFunctionality, request and response formats, field names, and behavior may change before the stable release. \nReview the release notes regularly for updates.\n\nContact [Developer Support](mailto:developer@flute.com?subject=About%20Flute%20API) for further details.\n
\n" }, "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.\nGetting started has the following steps:\n* Creating a Flute Account\n* Developing in the Sandbox Environment\n* Going Live\n\n# Creating a Flute Account\n

\n\nBefore using Flute payment capabilities or the Flute API suite, you must create a Flute sandbox account.\n\nAll development and testing occurs first in a sandbox account.\nThe sandbox account is a fully isolated account that mirrors production behavior.\nAll transactions, sales, and Flute API endpoints may be made in the sandbox.\nHowever, it does not process real transactions.\nIt is used to validate your integration, applications, and workflows before going live.\n\nThe account is free, does not require approval, and is self managed.\nUse the following procedure to create the Flute sandbox account and a merchant API key.\nThe merchant API key is required to generate an API token, used to make each call.
\nSee Creating a Flute Account\n\n\n# Developing in the Sandbox Environment\nThe sandbox account is a fully isolated account that mirrors production behavior.\nIt does not process real transactions.\nUse the sandbox for all testing and app development.\nThe Flute support team is available with assistance for developing workflows and tools.\nEven after going live, it may still be used to develop and test apps.\n\n# Going Live\nWhen your product is ready to be deployed live, the Flute support team will work with you to ensure compliance.\nThis compliance follows the production readiness checklist.\nIt ensures the best and optimal developer, client, and customer experience.
\nFor more information and details about the production readiness checklist, Production Go-Live Guide.\n" }, { "name": "API Suite Fundamentals", "description": "The following sections are general information required for using the Flute API suite.\n\n# baseURL Environments\nFlute provides different environments to run endpoints.\n\n\n**Sandbox**
\nThe sandbox environment is for development and testing.\nNo payments, charges, or invoices will be enforced.\nIt is a fully isolated account that mirrors production behavior.\n\nIt is used to validate your integration before going live.\nYou will work with your Flute support team developing workflows and tools.\n\nbaseURL: `https://sandbox.api.flute.com`\n\n**Production**
\nThe production environment is for deploying the payment system live to clients.\nAll payments, charges, or invoices are live and will be enforced.\n\nWhen your product is ready to be deployed live, the Flute support team will work with you to ensure compliance.\nThis compliance follows the production readiness checklist.\nIt ensures the best and optimal developer, client, and customer experience.
\nFor more information and details about the production readiness checklist, see Production Go-Live Guide.\n\nbaseURL: `https://api.flute.com`\n\n**Using the baseURL**
\nUse the baseURL instead of the placeholder noted in each endpoint.\nFor example, an endpoint may be described in the endpoint documentation as:
\n`GET {{baseURL}}/v2/customers`\n\nTo make this call in the sandbox environment, use:
\n`POST https://sandbox.api.flute.com/v2/customers`\n\nTo make this call in the production environment, use:
\n`POST https://api.flute.com/v2/customers`\n\n# Payment Flow\n

\n The following is a generalized workflow.\n\n## Approving a Purchase Request\n1) The customer completes their shopping experience on the merchant's website by selecting the products or services.\n They navigate to the checkout page on the merchant's website.\n1) They enter their personal and payment information. This could include card details, or net banking information.\n1) The merchant's website captures these details, formatting the details as needed to conform to Flute payment gateway requirements.\n1) This sensitive data is transmitted by a secure connection (HTTPS) to the Flute payment gateway.\n 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).\n1) Upon receiving this information, the Flute payment gateway further routes this payment data to the processing center, such as TSYS.\n1) This entity communicates with the customer's bank to get authorization or denial for the payment.\n The processing center determines if the payment is approved, that is, if there are sufficient funds or credit available in the customer's account.\n\n## Acknowledging a Purchase Request\n1) After the transaction is processed, the processing center sends back a response to the Flute payment gateway.\n This response includes details of the transaction, such as whether it was approved or declined.\n1) The Flute payment gateway relays this information back to the merchant's website.\n1) The merchant's website receives this information and displays a message or signal for the customer.\n Depending on whether the transaction was approved or declined, the appropriate message is displayed to the customer.\n For instance:\n * If transaction was successful, a confirmation message is shown, usually with a transaction ID and other details.
\n * If it was declined, the customer is informed and typically asked to try another payment method.\n\n## Supported Card Types\n

\n The following credit cards and formats are supported.\n\n- Diners Club: Card numbers are typically 14 or 16 digits long.\n- Discover: Card numbers are typically 16 digits long.\n- JCB: Card numbers are typically 16 digits long.\n- MasterCard: Card numbers are typically 16 digits long.\n- VISA: Card numbers are typically 13 or 16 digits long.\n\n# Flute-Defined Enums\n

\n The following are Flute-defined enumerations and indices used in endpoint fields.\n\n
\nAccount Holder Types\n\n| id | name |\n|----|----------|\n| 1 | Business |\n| 2 | Personal |\n
\n\n
\nAccount Types\n\n| id | name |\n|----|----------|\n| 1 | Checking |\n| 2 | Savings |\n
\n\n
\nBusiness Categories\n\n| id | name |\n|----|------------------------------|\n| 1 | WebDeveloper |\n| 2 | IndependentSoftwareVendor |\n| 3 | IndependentSalesOrganization |\n
\n\n
\nCredit Card Types\n\n\n| id | name |\n|:--:|-----------------|\n| 1 | Visa |\n| 2 | MasterCard |\n| 3 | AmericanExpress |\n| 4 | DinersClub |\n| 5 | Discover |\n| 6 | JCB |\n
\n\n
\nTransaction Creator Types\n\n\n| id | name |\n|----|--------------|\n| 1 | Portal |\n| 2 | ApiToken |\n| 3 | Terminal |\n| 4 | Invoice |\n| 5 | QuickPayment |\n| 6 | WebComponent |\n| 7 | Subscription |\n| 8 | MobileApp |\n| 9 | TapToPay |\n
\n\n
\nPartner Statuses\n\n| id | name |\n|----|-----------|\n| 1 | Active |\n| 2 | Suspended |\n
\n\n
\nPartner Business Model Types\n\n| id | name |\n|----|----------------------|\n| 1 | SingleAffiliateModel |\n| 2 | SubAffiliateModel |\n
\n\n
\nPayment Method Types\n\n| id | name |\n|----|-----------------|\n| 1 | Card |\n| 2 | ElectronicCheck |\n
\n\n
\nPayment Processor Statuses\n\n| id | name |\n|----|----------|\n| 1 | Active |\n| 2 | Inactive |\n
\n\n
\nPayment Processor Types\n\n| id | name |\n|----|------|\n| 1 | TSYS |\n| 2 | EFT |\n
\n\n
\nPayment Session Statuses\n\n| id | name |\n|------|-----------|\n| 1 | Created |\n| 2 | Cancelled |\n| 3 | Completed |\n| 4 | Failed |\n
\n\n
\nTransaction Statuses\n\n\n| Status Code | Status | Description | Available actions |\n|-------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| 1 | Authorized | Transaction status after an approved `pre-authorization` request | Capture, Void |\n| 2 | Captured | Transaction status after approved `sale` or `capture` request | Void |\n| 3 | Voided | Transaction status after merchant voids an `authorized` request or refunds a `captured` (not settled) request | N/A |\n| 4 | Refunded | Transaction status after merchant refunds a `settled` request | N/A |\n| 5 | Verified | NA | N/A |\n| 6 | Settled | Transaction status after successful settlement request. All `captured` transactions should have status changed to `settled` | Refund |\n| 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 |\n| 8 | Informational | NA | N/A |\n| 21 | Scheduled | NA | N/A |\n| 24 | Pending | Transaction status while changing status. This is a temporary status | N/A |\n| 91 | Declined | Transaction status after a denied `pre-authorization`, `sale` or `capture` request | N/A |\n| 92 | Failed | Transaction status after a failure at any type of request | N/A |\n| 92 | Expired | Transaction status after 7 days in `authorized` status (merchant has not captured within this time) | N/A |\n
\n\n
\nTransaction Types\n\n\n| id | name |\n|:--:|--------------------|\n| 1 | Authorization | \n| 2 | Sale | \n| 3 | Capture | \n| 4 | Void | \n| 5 | Refund | \n| 6 | CardAuthentication |\n| 7 | RefundWORef | \n| 8 | TipAdjustment | \n| 11 | AchDebit | \n| 12 | AchRefund | \n| 13 | AchHold | \n| 14 | AchUnHold | \n| 15 | AchCancel | \n| 16 | AchCredit | \n
" }, { "name": "Payment Methods", "description": "\n\n\n\nA payment method is a stored, tokenized payment record that can be used to process transactions. \n\nA stored record is created once and may be used for all future transactions.\nThis includes submitting the raw card and account details only once, when it is first created.\n\nTokenization means the sensitive payment data, such as the raw card number or bank account number, is submitted to Flute once.\nAfter that, Flute assigns a non-sensitive value to `paymentMethodId`.\nThe `paymentMethodId` is then used as the payment reference for later transactions.\n\nPayment methods can be set to one of the following types: linked to a customer or an orphan.\n\n**Linked to a customer**
\nA customer is a defined business entity.\nInformation includes the company name, the owner's name, billing and shipping addresses, and different kinds of payment methods.\nRather than re-entering the information, it can be saved and used later as needed.\nA payment method linked to a customer can be used by referencing the customer using the `customerId` value.\n\n**An orphan**
\nAn orphan payment method is a stored payment method (card or ACH account) that belongs to the merchant directly.\nIf the customerId is omitted from the payment method, the payment method is created as an orphan.\nIt exists in the merchant's vault but has no customer record associated with it.\nA practical use case would be for a one-time transaction that uses a tokenize card but without creating a full customer profile.\n\nThere are two types of payment method: Cards and ACH.\n\n**Cards**
\nCredit or debit cards are stored as a token.\nThe raw card number is never fully displayed.\nIt always uses a masked card number, such as `************1111`.\nA 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.\n\n**ACH accounts**
\nACH accounts are electronic bank accounts transfers.\nThey are stored with routing number, account number, account type (Checking/Savings), and account holder type (Personal/Business)\nBusiness ACH accounts also carry a payment name, a name recognizable to the merchant.\n\nEither 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": "\n\nThis endpoint group lists the preset and default settings for payments, discounts, and premium charges.\n\n**Levels 2 and 3**
\n\nSome settings list information about levels, specifically Levels 2 and 3.\n\nLevels refer to data standards for credit card transactions.\nThey provide increasingly detailed standards.\nHigher data standards qualify for lower interchange rates from Visa and Mastercard.\nThat means, merchants save on processing fees.\nAdvanced level are often required by many government and large enterprise buyers.\nThis also accommodates buyers needing detailed transaction data for accounting and reconciliation.\n\n**Level 1**
\nLevel 1 is the most basic data standards for credit card transactions.\nIn general industry terms, Level 1 is simply a standard transaction with basic data.\nThis includes the amount, date, merchant name, card number.\nIt's the default when no enhanced data is provided. \n\n**Level 2**
\nThis is an enhanced data standard.\nIt is typically the standard for business to business transactions, such as corporate, and purchasing cards.\n\nLevel 2 adds:\n* Customer code and purchase order number\n* The tax amount\n* A tax indicator.\nThis is a flag indicting if tax is included in the transaction amount, and if so, what kind.\n\n**Level 3**
\nThis is the most advanced data standard.\nIt offers the most detail and accountability.\nIt is typically the standard for large business to business transactions, government transactions, and government purchase cards.\nLevel 3 can reduce interchange fees by 0.5% to 1.5% compared to Level 1.\nThis discount become significant at high transaction volumes.\n\nLevel 3 adds:\n* Line-item details, such as product codes, descriptions, quantities, unit prices\n* Ship-to and ship-from postal codes\n* Freight amount\n* Discount amount\n\n\n" }, { "name": "Settlements", "description": "\n\nSettlement is the process of actually transferring funds between parties to finalize a transaction\nThis is different from authorization, which just reserves or confirms funds are available.\nThat means funds are not instantly available for each transaction.\nMerchants may see a delay between a sale and the funds deposited in their account.\n\nThe typical lifecycle that includes settlement:\n\n* **Authorization**. An authorized transaction is one that has been approved and funds are held or reserved. \nNo money has moved yet.

\nFor example, the following call starts a transaction with the `captureMethod` of `Auto`.\nThis automatically adds the transaction in an open settlement batch when the transaction is completed.\nThe call returns `transactionId`, which may be used to reference this transaction.\n\n
\n Sample Authorization Call\n \n \n ```csharp\n POST /v2/transactions\n Authorization: Bearer {{apiKey}} \n Content-Type: application/json\n { \n \"baseAmount\": 150.00, \n \"currencyCode\": \"USD\",\n \"customerInitiatedTransaction\": true,\n \"transactionDetails\": \n {\n \"cardData\":\n {\n \"captureMethod\": \"Auto\",\n \"paymentMethodDetails\":\n {\n \"cardNumber\": \"4111111111111111\",\n \"securityCode\": \"737\",\n \"expirationMonth\": 9,\n \"expirationYear\": 2027\n }\n }\n }\n }\n ```\n \n
\n\n* **Capture or batch**. Approved transactions are grouped together, or batched, for later processing.\n\n If `captureMethod` is `Auto`, no additional processing is required at this step.\n The transaction has been added to the settlement batch automatically.\n\n If `captureMethod` is `Manual`, the transaction must be explicitly added to the settlement batch.\n In this case use `POST /v2/transactions/{{transactionId}}/capture` to capture it to the settlement batch.\n \n Care must be taken when using `Manual` because if the transaction is never captured, the authorization simply expires and no funds move.\n\n
\n Sample Capture Call\n \n\n Omit the body (or send {}) for a full capture. Once captured, it enters the open settlement batch.\n\n ```csharp\n POST /v2/transactions/{{transactionId}}/capture\n Authorization: Bearer {{apiKey}}\n Content-Type: application/json\n\n {\n \"amount\": 150.00\n }\n ```\n\n
\n\n* **Settlement**. Settlement is the step where an authorized transaction becomes a real transfer of money.\n\nThe batch is submitted to the card networks or banks.\nThis processing includes moving the money from the cardholder's bank, through the network, to the acquiring bank.\nIt eventually ends at merchant's account, minus fees.\nUse `POST /v2/settlements/settle` to initiate the settlement batch.\n\nThis batch processing usually happens on a schedule, such as daily batch settlement at the end of business.\n\n" }, { "name": "Terminals", "description": "\n\nA terminal represents a physical payment device deployed to a merchant to accept card and other electronic payments.\nEach terminal is tracked from the point it's ordered through its active use in the field, including hardware details, connectivity, and security provisioning.\n\nThe combination of all the details and attributes portrays and monitors a terminal's readiness, connectivity, and security posture throughout its deployment.\n\n" }, { "name": "POS Transactions", "description": "\n\nPOS (point of sales) transactions represent payment transactions that are initiated and driven directly on a physical terminal device.\nThis is in contrast to transactions created purely through an API, such as a card-not-present charge.\n\nA POS transaction is the record of a payment flow that runs through a physical terminal.\nThe point of service, such as a diner's table, creates it and enters at the terminal what to charge.\nThe transaction can then be polled or listed to see the resulting status and the core transaction.\nThe typical lifecycle that includes a POS transaction:\n\n**Creating one**
\nUse `POST /v2/pos/transactions`.
\nThis initiates a transaction on a specific terminal device with predefined details.\nThese include the amount, transaction type, such as sale or authorization, currency, customer, pricing type, and whether to wait for the terminal to accept it. \nThe terminal handles the actual card read (readingMethod) and cardholder interaction.\n\n**Tracking status**
\nA POS transaction has its own lifecycle status (posTransactionStatus).\nThis is such as TransactionProcessing or Completed and is separate from the underlying core transactionId it eventually links to once processed.\n\n**Listing them**
\nUse `GET /v2/pos/transactions`.
\nThis returns a paginated list of POS transactions, filterable by terminalId, showing fields like processedAmount, transactionType, and the linked transactionId.\n\n\n\n\n\n" }, { "name": "Transactions", "description": "\n\nAt the center of Flute's payments model is the *transaction*.\nA transaction is a record created every time money moves through a merchant's account.\n\nA transaction is created with a single call: \\\n`POST /v2/transactions`\n\nEvery transaction carries the same core shape regardless of payment type:\n* `paymentProcessorId` specifies the processor handling the transaction.\n* `baseAmount` and `currencyCode` specify the transaction amount.\n* `referenceId` specifies a value the merchant chooses for their own bookkeeping.\n* `transactionDetails` specifies an object holding either the `cardData` or `achData` depending on how the customer is paying.\n\nEach transaction goes through the same endpoint.\nIt comes back with the same response envelope, just populated with different `processorResponse` details.\nThis includes whether someone is charging a saved card, running a brand-new card number inline, or debiting a bank account through ACH.\n\nCard transactions carry an extra decision point that ACH doesn't: `captureMethod`.\nThis is set to either `Auto` or `Manual`.\n* `Auto` capture means the authorization and the capture happen in one step, and the transaction lands in an Approved state immediately, ready to settle.\n* `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.\n\nThis distinction matters most for merchants who need to confirm inventory or finalize an order total.\nFor example, a restaurant might close a tab with tips added before actually pulling the money.\nIt's why the API treats \"money authorized\" and \"money captured\" as two different states rather than collapsing them into one.\n\nOnce a transaction is captured or approved, several other endpoints act on it rather than creating a new one.\n* `POST /v2/transactions/{transactionId}/reversal` reverses a transaction outright.\n* `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.\n* `POST /v2/transactions/reversal` for pulling money back after settlement.\n* `POST /v2/transactions/credit` for issuing money without tying it to a prior reference.\n* `POST /v2/transactions/{transactionId}/ach-hold` for placing a hold on a pending ACH transaction.\n\nEvery transaction also comes back with a rich `amountDetails` and `processorResponse` breakdown rather than just a status code.\n* `amountDetails` separates `baseAmount` from `tipAmount`, `tipRate`, `surchargeAmount`, and `discountAmount`.\nA merchant can see exactly how a `processedAmount` was assembled instead of just the final total.\n* `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.\nFor 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.\nThis is one of the signals merchants use to judge fraud risk on a given charge.\n\nThe following is an example of a basic transaction.\nA merchant charges $100 on a saved card with auto-capture, and the customer adds a $15 tip at checkout.\n\nRequest \\\n`POST /v2/transactions`\n```json\n{\n \"paymentProcessorId\": \"a2f2c2e7-0b23-4682-8f99-ab7707205461\",\n \"baseAmount\": 100.00,\n \"currencyCode\": \"USD\",\n \"referenceId\": \"REF-CARD-SALE-001\",\n \"isCustomerInitiatedTransaction\": true,\n \"pricingType\": \"Card\",\n \"transactionDetails\": {\n \"cardData\": {\n \"captureMethod\": \"Auto\",\n \"paymentMethodId\": \"e397e367-bc4a-4b69-bd78-32e3e12327c2\"\n }\n }\n}\n```\n\nBecause the `captureMethod` is `Auto`, Flute authorizes and captures the charge in the same call.\nThe response comes back already settled from the API's perspective:\n\nResponse\n```json\n{\n \"transactionId\": \"5f6f782f-37af-44e1-bb18-2bc35e411899\",\n \"transactionStatus\": \"Approved\",\n \"processedAmount\": 115.5,\n \"currencyCode\": \"USD\",\n \"amountDetails\":\n {\n \"baseAmount\": 100.00,\n \"tipAmount\": 15,\n \"surchargeAmount\": 3,\n \"discountAmount\": 2.5\n },\n \"processorResponse\":\n {\n \"processorName\": \"TSYS\",\n \"responseCode\": \"00\",\n \"responseMessage\": \"Approved\",\n \"responseDefinition\": \"Approved and completed\"\n },\n \"addressVerificationServiceResponse\":\n {\n \"action\": \"Allow\",\n \"responseCode\": \"Y\",\n \"description\": \"Address and ZIP match\"\n }\n}\n```\nThe `processedAmount` ($115.50) reflects the base charge plus the tip and a surcharge, minus a discount.\nThis is exactly as itemized in `amountDetails`.\n\nThe transaction is done.\nThere is no separate capture call needed.\nThis merchant chose the auto-capture path rather than the authorize-then-capture flow used for something like a restaurant tab.\n\n\n" }, { "name": "API Token Authorization", "description": "\nAn API token is required for each endpoint use.\nAn API token can only be created after an account is created, registered, and at least one API key has been created.\n\nThe API token is an authorization token needed for each for endpoint.\nIt is an encrypted string that combines the client Id and client secret from an API key (created earlier).\nIt contains authentication and authorization coding.\nThis includes any privileges the user or account affords.\nBeing encrypted means the API token is safe to expose in frontend code.\nThe API token is time-sensitive and expires after an amount of time.\n\nIt may be created as needed.\nWe recommend generating a new API token before each endpoint use.\nThis ensures the API token will be valid for each call.\n\n\nThe API token is an OAuth 2.0 Client Credentials authorization flow.\nThe Client Credentials Flow is an OAuth 2.0 authorization Bearer grant.\nThis means a server-side application obtains an access token using its client credentials (client ID and client secret) to protect resources.\n\n

Base authorization URLs

\nAn API token is created for the environment it will be used in.\nThere are two available Flute environments: Sandbox and Production.\n\n**Sandbox**
\nUse the sandbox environment for development and testing.\nNo payments, charges, or invoices will be enforced.
\nEndpoint: `POST https://sandbox.oauth.api.flute.com`\n\n**Production**
\nUse the production environment for deploying the payment system live to clients.\nAll payments, charges, or invoices will be enforced.
\nEndpoint: `POST https://oauth.api.flute.com`\n\nThe sandbox and production environments API tokens use the same API key and differentiated only by the environment endpoint.\nThe two API tokens types are not interchangeable and cannot be used in an environment different than they were created for.\n\nThe API key that was created in the initial account registration is needed to create an API token.\nThe **client ID** and **client secret** are used together to create an API token.\n\nThe following is an example of obtaining an API token for the sandbox environment:\n```shell\ncurl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \\\n-u '594838709594...38697242c:9eb2c6859daa4...d8ae5da9' \\\n-H 'Content-Type: application/x-www-form-urlencoded' \\\n-d 'grant_type=client_credentials&scope=offline_access'\n```\n\nThe following is an example of refreshing an API token for the sandbox environment:\n```shell\ncurl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \\\n-u '594838709594...38697242c:9eb2c6859daa4...d8ae5da9' \\\n-H 'Content-Type: application/x-www-form-urlencoded' \\\n-d 'grant_type=refresh_token&refresh_token=def50200newrefresh123456789'\n```\n\nRegardless of either obtaining or refreshing an API token, the following example is passed back in the response body:\n```json\n{\n\"access_token\": \"u7BYwJx26U1lT...TZpKvndLCC4\",\n\"refresh_token\": \"def50200newrefresh123456789\",\n\"token_type\": \"Bearer\",\n\"expires_in\": 900\n}\n```\n\n

Using the API Token

\n\nThe token endpoint returns both an `access_token` and a `refresh_token`.\nThe lifespan of the `access_token` is indicated by the `expires_in` value.\nThe lifespan of the `refresh_token` is set by OAuth standards.\n\nClients are encouraged to use either token as needed.\nFor example, it may be easier to call for a new `access_token` before each user-initiated action.\nThe `access_token` may also be left to expire, and then use `refresh_token` procedures to continue.\nFor example, mobile phones apps may need to use the `refresh_token` to avoid consistently signing back in.\n\nIn the endpoint header, use the following `access_token` format:\n```json\n\"Authorization\": \"Bearer u7BYwJx26U1lT...TZpKvndLCC4\"\n```\n\nThe following example creates a new access token:\n```shell\ncurl 'https://sandbox.api.flute.com/v2/transactions' \\\n-H 'Authorization: Bearer u7BYwJx26U1lT...TZpKvndLCC44' \\\n-H 'Accept: application/json'\n```\nAs a reminder, always secure your client ID and especially your client secret.\nNever expose the client secret in client-side code or public repositories.\nIt should be kept private and secure.\nIf it is suspected that the client secret has been compromised, the owning API key must be deleted.\nA new API key can then be created.\n\n

Error Responses

\n\nIf authentication fails, the token endpoint returns an error.\nThe following are commonly encountered errors.\n\n| HTTP Status | Common Cause |\n|------------------|---------------------------------------------------------------------------|\n| 400 Bad Request | Missing or invalid grant_type, or malformed request body. |\n| 401 Unauthorized | The API token has likely expired. Create a new one and retry the request. |" }, { "name": "Payment Sessions", "description": "\nA payment session is an in-progress payment transaction.\nIt is a temporary, time-limited context created when a client initiates a payment flow.\n\nIt becomes a secure, stateful environment for completing a payment transaction. \nInstead of passing sensitive payment data on every request, the payment session persists transaction details. \nThis includes the amount, currency, payment method, and status.\nIt exposes only the payment session identifier to the client. \nThis reduces the risk of data exposure.\n\nThe use of a payment session is applicable only to Flute Elements and Flute Checkout.\nSome fields may include a note about their use, and specifically for Elements and Checkout.\n\nThe following is a common workflow for using a payment session.\n\n* Create the payment session.\n* Connect through Flute Elements or Flute Checkout.\nThis may include selecting a payment method, applying discounts or promotions,\nauthorizing the payment, and capturing the funds.\nMany of these individual steps will be transparent to the client when using Flute Elements or Flute Checkout.\n\nAt each step, the payment session holds the transaction state.\nThis means each step can update the session without resubmitting the full transaction data. \nIf the client navigates away but later returns or does not complete the transaction immediately, the session can be retrieved by its identifier.\nThe flow resumed from where it left off.\n\nThe payment session can end in one of the following ways:\n* The transaction is completed.\nCheck the status of the transaction for its success.\nSee `POST /v2/payment-sessions/{{paymentSessionId}}`, the field `status`.\n* The transaction is canceled.\nThe client chooses to not complete the transaction.\nIf the client cannot later resume the transaction.\nA new payment session must be started.\n* The payment session expires or times out.\nWhen creating a payment session, an expiration date and time can be assigned.\nIf the transaction is neither completed nor explicitly canceled, the payment session cancels itself.\nLike the cancel operation, the state of the transaction is saved.\nThe client may retrieve the payment session later and continue the transaction." }, { "name": "Merchant API Keys", "description": "API keys may be managed programmatically.\nThis includes creating and deleting API keys.\nThis is the same capability as through the partner and merchant dashboards.\n\nHow the API keys are managed depends on the source of the API token used for the endpoints.\nThere are two sources: Partner and merchant.\n* A partner API key used to create the API token affects only merchants associated with the partner.\nThe partner can manage the API keys for their individual merchants.\nA partner API key can be created only in the partner dashboard.\n* A merchant API key used to create an API token that affects only that one merchant.\nThis includes both a merchant associated with a partner and standalone merchants (those not associated with any partner).\n\nEach merchant API Key endpoint explains the details of using either API token source.\n\nThe API keys are specific to a single merchant.\nThey are not interchangeable from among different merchants, even if they are each associated with the same partner.\nThat is, merchants cannot use API keys from any other merchant.\nStandalone merchants (those not associated with any partner) manage their API keys through the merchant Flute dashboard.\n\nMerchant API keys are required only if the merchant application or account needs to integrate with the API suite.\nA merchant API key is required to create API tokens (also called access tokens), needed to make endpoint calls.\nExcept 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.\nPartner API keys cannot be used to create API tokens otherwise.\nTo generate an API token from an API key, see GET /oauth-token.\n\nThe number of API keys is determined by the partner or standalone merchants.\nThey may have as many or as few as required.\nFor more information about API keys, see Creating an API Key.\n\nThis Merchant API Key group consists of the following endpoints:\n* To list available keys, see `GET /v2/api-keys`\n* To create an API key, see `POST /v2/api-keys`\n* 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.\nThese include billing details, transaction history, and recurring payments.\nA customer record may contain their name, email address, phone number, billing, and shipping addresses.\nHaving a customer association is not required to pay for transactions.\n\n**Creating a customer**
\nCustomers may be created in the following ways:\n\n* Explicitly with `POST /pay-api/v1/customers`.\nThis includes full customer details and optional payment methods.\n* The Merchant Portal. Merchants and their partner can create customers through this portal.\n* Implicitly with `POST /pay-int-api/payment-sessions`.\nWhen this endpoint's `mode` is either `SaveMethod` or `PaymentAndSave`, if `customerId` is not provided, one will be created.\n* Implicitly with `POST /pay-int-api/invoices/publish`.\nIf `customerId` is not provided, one will be created.\n\nNew `customerId` values can be reviewed with `GET /v2/customers`.\n\n**Pay transactions**
\nCustomers may pay transactions in one of three ways:\n* Vaulted payments\n* Standalone tokenization, also known as orphan vaulted payment\n* Account supported\n\n**Vaulted payments**
\nCustomers can be associated with one or more vaulted payment methods.\nA vaulted payment method is a securely stored payment credential.\nThis applies to credit card or bank account payments.\nA vaulted payment method is a securely stored payment credential.\nThis is considered a more secure method rather than storing the card number directly.\nThat information has previously been tokenized and saved for future use.\nVaulted information can be safely accessed through a payment identifier.\nThis is typically used for recurring billing, subscriptions, saved checkout experiences, and card-on-file transactions.\n\nIn the transaction payment, the field `customerId` is provided.\nThe customer's vaulted payment methods are available for selection.\n\n**Standalone tokenization**
\nClients may use standalone tokenization, also known as an orphan vaulted payment.\nThis allows a payment method to be vaulted even when the payer has not been recognized as a customer entity.\nThe transaction proceeds using a previously established payment method identifier.\n\nStandalone tokenization is useful when a payment method must be vaulted before a customer profile exists.\nThis includes guest checkouts, delayed onboarding, account setup, or card-on-file collection before registration is complete.\n\nIn the transaction payment, the field `customerId` is omitted but `paymentMethodId` is provided.\nThis indicates the merchant's orphan vaulted payment method is used.\n\n**Accounts Supported**
\nClients may use accounts supporting orphan payments.\nThis is a form of a payment method that temporarily exists without a customer association.\n\nIn the transaction payment, both fields `customerId` and `paymentMethodId` are omitted.\nThe 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.\n\nWebhooks 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.\n\nThey replace polling.\nThis polling might have been:\n* Software polling for a status change either through a loop, or timed queries.\n* Manually by a user explicitly polling expecting a response or pending status to be returned.\n\nA merchant can only affect their own webhooks.\nThey cannot view or modify other merchant's webhooks.\nLikewise, a partner can only affect merchants associated to them.\nThey cannot affect merchants of other partners.\n\n**Required API Permissions**
\nRequired API Permission: Webhooks\n\n**Webhook Workflows**
\nTo create and manage Flute webhooks, use the following procedures and workflows.\n\n**Creating Webhooks**
\n1\\) Optionally, review all the valid event types.\nWebhooks can accept one or more event types.\nEach event type is evaluated independently.\nSelected events are not required to be related and may relate to different transaction types or workflows.\nFor organizational reasons, multiple webhooks can be created.\nEach webhook can then have its own set of event types.\n\nTo list all available events, see `GET /v2/webhooks/event-types`\n\n2\\) Create the webhook
\nTo create the webhook, see `POST /v2/webhooks/endpoints`\n\n3\\) Test the webhook
\nVerify the endpoint is reachable (sends a test ping).
\nTo test the webhook, see `POST /v2/webhooks/endpoints/{webhookId}/ping`\n\n**Managing Webhooks**
\nThe following set of endpoints manage webhooks.\n\n* This endpoint provides a list of all available webhook for the merchant.
\nTo list all the available webhooks, see `GET /v2/webhooks/endpoints`\n\n* This endpoint retrieves webhook details specified by its webhookId.
\nTo retrieve a specific webhook, see `GET /v2/webhooks/endpoints/{webhookId}`\n\n* This endpoint provides an ability to update or change a webhook.\nFor example, the set of event types may be changed without having to create a new webhook.
\nTo modify or update a specific webhook, see `PATCH /v2/webhooks/endpoints/{webhookId}`\n\n* This endpoint deletes the specific webhook.\nThis action can neither be undone nor can the webhook be retrieved.\nThis does not erase entries in the log file.
\nTo delete a specific webhook, see `DELETE /v2/webhooks/endpoints/{webhookId}`\n\n**Monitoring Webhooks**
\nThe following set of endpoints monitor webhooks.\nThese may be used to verify success of an attempt or assist in determining the cause of a problem.\n\n* This endpoint lists success level of delivery attempts.
\nTo view webhooks delivery attempts log file, see `GET /v2/webhooks/delivery-logs`\n\n* This endpoint lists success level of delivery attempts for a specified webhook.
\nTo view a specified webhook delivery attempts log file, see `GET /v2/webhooks/delivery-logs/{webhookId}`\nGet full request/response detail for a single attempt\n\n* This endpoint exports the delivery logs file.\nIt may be specified as either a CSV or JSON format.
\nTo export webhooks delivery attempts log file, see `GET /v2/webhooks/delivery-logs/export`\n\n* This endpoint retries a failed delivery.
\nTo retry a failed delivery, see `POST /v2/webhooks/delivery-logs/{id}/retry`\n\n**Client Handling of Messages**
\nThe webhook sends a message to the URL specified by the client.\nThis is `endpointUrl` of `POST {{baseURL}}/v2/webhooks/endpoints`.\nThe message is considered successfully sent after a send confirmation is received.\nIf that send confirmation was not successfully confirmed, the message will be sent, or retried, a number of times before failing.\n\nAfter being successfully sent to the receiving endpoint or URL, \nit is the client's responsibility to handle it after that.\nAs a best practice, we recommend that the message is first verified to be from Flute.\nFor example, use HMAC verification.\nThis step greatly increases security and reduces system vulnerabilities such as spoofing, tampering, or data injection.\nThe IP address could be blocked to prevent future intrusions.\n\nOnce the sender is verified, the client can process the message as they need.\nFor example, code or an application on the receiving server may create an email or SMS message to send to the client.\n" }, { "name": "Ping", "description": "Ping is a health check endpoint.\nIt verifies the service is currently reachable.\nThis also checks that an API token is still valid.\n\nThis is a simple endpoint call. \nIt takes no parameters and returns no response body.\nA successful call returns only a 200 OK.\nThat minimalism is intentional.\nIt is typically hit frequently and automatically rather than as part of real business logic.\n\nThis endpoint is useful as:\n* an application startup check when an integration boots.\n* a periodic keep-alive in a monitoring dashboard, \n* a quick manual test after rotating an API key.\n\nIt shares the same error-handling shape as every other endpoint, such as response codes for 400, 401, 403, 429, or 500.\nThese error response codes are diagnostically useful, too.\nFor example, a response code of 401 indicates the API token is bad or expired.\n\nSee Also:
\nTo 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": "\nPOST {{baseOAuthURL}}/oauth2/token\n\nThis endpoint obtains or refreshes an API token.\n\nEach Flute endpoint (with the exception of this authentication endpoint) requires an API token, also called an access token).\nIt is an encrypted string generated from a Flute-owned authentication server.\nThe API token is a combination of an authentication of the user and an authorization of the user's permissions.\n\nEach API token has a limited lifespan.\nThis is often 900 seconds, or 15 minutes although the actual value is returned by the authentication call. \nAfter the API token expires, it can no longer be used to make calls.\nThe API token must then be obtained anew or refreshed.\n\n### Obtaining API Tokens\nThere are two ways to get a valid API token: **Obtaining a new token** or **Refreshing an existing token**.\n\nThe endpoint for obtaining a new API token or to refresh an existing one is the same.\nOnly the request body fields are different.\nSelecting the appropriate option displays the relevant fields and information.\n\n**Obtaining a new token**
\nA new token must be obtained because:\n* No token exists.\nThis may be from the user just logging in or the previous API token expired.\n* The stored `refresh_token` expired, has been revoked, or gets rejected by the server (such as a refresh attempt failed).\n* A different API key is being used.\n\nTo obtain a new API token, see the call below, selecting **Obtain a new token**.\nThis displays the fields and details needed to make the call.\n\n**Refreshing an existing token**
\nAn existing API token may be refreshed to create a new, valid API token.\nThat existing API token may be currently valid or has expired recently.\nThe goal is to provide continuous operation.\nThis allows users to remain authenticated without repeating full credential authentication on every renewal.\n\nAn API token may be refreshed because:\n* The current `access_token` is about to or has already expired.\n* A valid `refresh_token` is currently available and valid from the most recent API token.\n\nTo refresh an API token, see the call below, selecting **Refresh an existing token**.\nThis displays the fields and details needed to make the call.\n\n### API Token Types\nAPI token types depend on the type of API keys used to create them.\nThe resulting API token type will be one of following:\n* Merchant token if it is created from a merchant API key.\n* Partner token if it is created from a partner API key.\n\nThe two API keys types are not interchangeable.\nMost Flute endpoints require a merchant token.\nThe endpoint description specifies the required API key type.\nEndpoints requiring a partner token will be explicitly marked.\nOtherwise, a merchant token is required.\n", "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.\n\nExample: 59483870959438697242c\n", "example": "59483870959438697242c" }, "client_secret": { "type": "string", "description": "Specifies the client secret from the API key for the account.\n\nExample: 9eb2c6859daa4d8ae5da02a9\n", "example": "9eb2c6859daa4d8ae5da02a9" }, "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Specifies the literal value `client_credentials`.\n\nExample: client_credentials\n", "example": "client_credentials" }, "scope": { "type": "string", "enum": [ "offline_access" ], "description": "Specifies the literal value `offline_access`.\n\nExample: offline_access\n", "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.\n\nExample: 59483870959438697242c\n", "example": "59483870959438697242c" }, "client_secret": { "type": "string", "description": "Specifies the client secret from the API key for the account.\n\nExample: 9eb2c6859daa4d8ae5da02a9\n", "example": "9eb2c6859daa4d8ae5da02a9" }, "grant_type": { "type": "string", "enum": [ "refresh_token" ], "description": "Specifies the literal value `refresh_token`.\n\nExample: refresh_token\n", "example": "refresh_token" }, "refresh_token": { "type": "string", "description": "Specifies the refresh token received from a prior token request.\n\nExample: YhjQpM...EVkVuB\n", "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.\n\nExample: 213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14\n", "example": "213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14" }, "token_type": { "type": "string", "description": "Indicates the token type.\n\nExample: Bearer\n", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Indicates the expiry, or lifetime, (in seconds) of the API token.\n\nExample: 900\n", "example": 900 }, "refresh_token": { "type": "string", "description": "Indicates the refresh token (only for authorization_code grant).\n\nExample: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25\n", "example": "324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25" }, "scope": { "type": "string", "description": "Indicates the granted scopes, space-delimited.\n\nExample: null\n", "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": "\nGET {{baseURL}}/v2/customers\n\nThis endpoint lists customers.\n\nSee Also:
\nTo create a new customer, see `POST /v2/customers`.
\nTo retrieve a customer by ID, see `GET /v2/customers/{customerId}`.
\nTo update a customer, see `PATCH /v2/customers/{customerId}`.\n\n\n [ Query parameters ]\n [ Response body ]\n\n\n\n", "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.\n", "schema": { "type": "string", "x-method": "query", "example": "pepparedstreetcafe@example.com" } }, { "name": "companyName", "in": "query", "description": "Filters by a company name.\n", "schema": { "type": "string", "x-method": "query", "example": "Peppared Street Cafe" } }, { "name": "mobilePhoneNumber", "in": "query", "description": "Filters by a mobile phone number.\n\nFree-form search input, E.164 format is not required.\nThis allows partial digits or legacy formats.\n", "schema": { "type": "string", "x-method": "query", "example": "+14155552309" } }, { "$ref": "#/components/parameters/createdFrom" }, { "$ref": "#/components/parameters/createdTo" } ], "responses": { "200": { "description": "OK ", "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": "\nPOST {{baseURL}}/v2/customers\n\nThis endpoint creates a customer.\n\nSee Also:
\nTo list customers, see `GET /v2/customers`.
\nTo retrieve a customer by ID, see `GET /v2/customers/{customerId}`.
\nTo update a customer, see `PATCH /v2/customers/{customerId}`.
\nTo delete a customer, see `DELETE /v2/customers/{customerId}`.\n", "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": "\nGET {{baseURL}}/v2/customers/{{customerId}}\n\nThis endpoint retrieves a customer by ID.\n\nSee Also:
\nTo create a new customer, see `POST /v2/customers`.
\nTo list customers, see `GET /v2/customers`.
\nTo update a customer, see `PATCH /v2/customers/{customerId}`.
\nTo delete a customer, see `DELETE /v2/customers/{customerId}`.\n", "parameters": [ { "name": "customerId", "in": "path", "x-method": "path", "required": true, "description": "Specifies a customer's identifier.\n", "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": "\nPATCH {{baseURL}}/v2/customers/{{customerId}}\n\nThis endpoint updates a customer's information.\n\nThis endpoint is a partial update.\nSend only the fields needed to be changed.\n* An omitted field is left unchanged.\n* A field marked with `null` clears a field.\n\nNested structures are also affected.\n\nSee Also:
\nTo create a new customer, see `POST /v2/customers`.
\nTo list customers, see `GET /v2/customers`.
\nTo retrieve a customer by ID, see `GET /v2/customers/{customerId}`.
\nTo delete a customer, see `DELETE /v2/customers/{customerId}`.\n", "parameters": [ { "name": "customerId", "in": "path", "x-method": "path", "required": true, "description": "Specifies a customer's identifier.\n", "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": "\nDELETE {{baseURL}}/v2/customers/{{customerId}}\n\nThis endpoint deletes a customer.\n\nSee Also:
\nTo create a new customer, see `POST /v2/customers`.
\nTo list customers, see `GET /v2/customers`.
\nTo retrieve a customer by ID, see `GET /v2/customers/{customerId}`.
\nTo update a customer, see `PATCH /v2/customers/{customerId}`.\n", "parameters": [ { "name": "customerId", "in": "path", "x-method": "path", "required": true, "description": "Specifies the identifier of the customer to delete.\n", "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": "\nGET {{baseURL}}/v2/api-keys\n\nThis endpoint lists merchant's API keys.\n\nSee Also:
\nTo create an API key, see `POST /v2/api-keys`.
\nTo revoke an API key, see `DELETE /v2/api-keys/{{clientId}}`.\n", "parameters": [ { "name": "merchantId", "in": "query", "description": "Specifies a merchant identifier to filter API keys.\n\nIf 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.\nA value for `merchantId` may be used to limit the search to a specific merchant.\n\nIf the API token used for this endpoint was created from a merchant API key, only API keys for that merchant will be returned.\nA value for `merchantId` may be omitted.\n", "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": "\nPOST {{baseURL}}/v2/api-keys\n\nCreates a new API key for a merchant.\n\nIf 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.\n\nIf the API token used for this endpoint was created from a merchant API key, an API key can be created only for that merchant.\n\nSee Also:
\nTo list available keys, see `GET /v2/api-keys`.
\nTo revoke an API key, see `DELETE /v2/api-keys/{{clientId}}`.\n", "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": "\nDELETE {{baseURL}}/v2/api-keys/{{clientId}}\n\nThis endpoint revokes a merchant API key.\n\nSee Also:
\nTo list available keys, see `GET /v2/api-keys`.
\nTo create an API key, see `POST /v2/api-keys`.\n", "parameters": [ { "name": "clientId", "in": "path", "x-method": "path", "description": "Specifies the API key's client identifier.\n\nIf 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.\n\nIf the API token used for this endpoint was created from a merchant API key, an API key can be revoked only for that merchant.\n", "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": "\nGET {{baseURL}}/v2/payment-methods\n\nThis endpoint lists a customer's payment methods for the merchant.\n\nSee Also:
\nTo add a new card payment method, see `POST /v2/payment-methods/cards`.
\nTo add a new ACH payment method, see `POST /v2/payment-methods/ach`.
\nTo retrieve a payment method, see `GET /v2/payment-methods/{{paymentMethodId}}`.
\nTo update a payment method, see `PATCH /v2/payment-methods/{{paymentMethodId}}`.\n", "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.\n\nThis performs a case-insensitive search that matches exactly or partially.\n", "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.\n\nIf null or omitted, the response includes orphan payment methods with customer-linked payment methods.\n", "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": "\nPOST {{baseURL}}/v2/payment-methods/cards\n\nThis endpoint creates a card (credit or debit) payment method.\n\nThe card information is tokenized and stored, assigning it to the merchant.\n\nTokenization means the sensitive payment data, such as the raw card number or bank account number, is submitted to Flute once.\nAfter that, Flute assigns a non-sensitive value to paymentMethodId. \nThe paymentMethodId is then used as the payment reference for later transactions.\n\nSee Also:
\nTo add a new ACH payment method, see `POST /v2/payment-methods/ach`.
\nTo list payment methods, see `GET /v2/payment-methods`.
\nTo retrieve a payment method, see `GET /v2/payment-methods/{{paymentMethodId}}`.
\nTo update a payment method, see `PATCH /v2/payment-methods/{{paymentMethodId}}`.\n", "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": "\nPOST {{baseURL}}/v2/payment-methods/ach\n\nThis endpoint creates an ACH (automated clearing house) payment method.\n\nThe ACH account information is tokenized and stored, assigning it to the merchant.\n\nTokenization means the sensitive payment data, such as the ACH account number or bank account number, is submitted to Flute once.\nAfter that, Flute assigns a non-sensitive value to paymentMethodId.\nThe paymentMethodId is then used as the payment reference for later transactions.\n\nFor Business ACH where the orphan caller will not supply ContactInfo on transactions, include `companyName` so the legal entity name is available at transaction time.\n\nSee Also:
\nTo add a new card payment method, see `POST /v2/payment-methods/cards`.
\nTo list payment methods, see `GET /v2/payment-methods`.
\nTo retrieve a payment method by ID, see `GET /v2/payment-methods/{{paymentMethodId}}`.\n", "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": "\nGET {{baseURL}}/v2/payment-methods/{{paymentMethodId}}\n\nThis endpoint retrieves a payment method by ID.\n\nSee Also:
\nTo add a new card payment method, see `POST /v2/payment-methods/cards`.
\nTo add a new ACH payment method, see `POST /v2/payment-methods/ach`.
\nTo retrieve a payment method by ID, see `GET /v2/payment-methods/{{paymentMethodId}}`.\n", "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.\n", "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).\nBusiness ACH carries the legal entity name in `companyName`.\n`IsDefault` is always `false` for orphans.\n", "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": "\nPATCH {{baseURL}}/v2/payment-methods/{{paymentMethodId}}\n\nThis endpoint updates a payment method.\n\nRenames the payment method.\n\nThis endpoint is a partial update.\nSend only the fields needed to be changed.\n* An omitted field is left unchanged.\n* A field marked with `null` clears a field.\n\nNested structures are also affected.\n\nThe payment method is identified by `paymentMethodId` within the merchant.\nThe operation works the same for orphan and customer-linked payment methods.\n\nSee Also:
\nTo list payment methods, see `GET /v2/payment-methods`.
\nTo retrieve a payment method by ID, see `GET /v2/payment-methods/{{paymentMethodId}}`.
\nTo delete a payment method, see `DELETE /v2/payment-methods/{{paymentMethodId}}`.
\nTo set a payment method as the default, see `POST /v2/payment-methods/{{paymentMethodId}}/set-default`.\n", "parameters": [ { "name": "paymentMethodId", "in": "path", "x-method": "path", "description": "Specifies the payment method identifier.\n", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c857af4c-ced9-4b79-b39b-13c077711d7e" } } ], "requestBody": { "description": "The payment method fields to update.\n", "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": "\nDELETE {{baseURL}}/v2/payment-methods/{{paymentMethodId}}\n\nThis endpoint deletes a payment method.\n\nSee Also:
\nTo list payment methods, see `GET /v2/payment-methods`.
\nTo retrieve a payment method by ID, see `GET /v2/payment-methods/{{paymentMethodId}}`.
\nTo update a payment method, see `PATCH /v2/payment-methods/{{paymentMethodId}}`.
\nTo set a payment method as the default, see `POST /v2/payment-methods/{{paymentMethodId}}/set-default`.\n", "parameters": [ { "name": "paymentMethodId", "in": "path", "x-method": "path", "description": "Specifies the payment method identifier to delete.\n", "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": "\nPOST {{baseURL}}/v2/payment-methods/{{paymentMethodId}}/set-default\n\nThis endpoint set the specified payment method as the default payment method.\n\nOnly one payment method can be set as the default.\nWhen set, the previous default payment method, if there was one, is changed to not being the default.\n\nOnly customer-linked payment methods can be made default; CustomerId is therefore required.\nOrphan PMs (no linked customer) have no concept of default and cannot reach this endpoint without a customer scope.\n\nSee Also:
\nTo list payment methods, see `GET /v2/payment-methods`.
\nTo retrieve a payment method by ID, see `GET /v2/payment-methods/{{paymentMethodId}}`.
\nTo update a payment method, see `PATCH /v2/payment-methods/{{paymentMethodId}}`.
\nTo delete a payment method, see `DELETE /v2/payment-methods/{{paymentMethodId}}`.\n", "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.\n", "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": "\nPOST {{baseURL}}/v2/payment-sessions\n\nThis endpoint creates a new payment session.\n\nSee Also:
\nTo retrieve a payment session by Id, see `GET /v2/payment-sessions/{{paymentSessionId}}`.
\nTo cancel a payment session, see `POST /v2/payment-sessions/{{paymentSessionId}}/cancel`.\n", "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": "\nGET {{baseURL}}/v2/payment-sessions/{{paymentSessionId}}\n\nThis endpoint retrieves the details of the specified payment session by ID.\n\nSee Also:
\nTo create a new payment session, see `POST /v2/payment-sessions`.
\nTo cancel a payment session, see `POST /v2/payment-sessions/{{paymentSessionId}}/cancel`.\n", "parameters": [ { "name": "paymentSessionId", "in": "path", "x-method": "path", "description": "Specifies the payment session identifier.\n", "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": "\nPOST {{baseURL}}/v2/payment-sessions/{{paymentSessionId}}/cancel\n\nThis endpoint cancels a payment session.\n\nA payment session can only be canceled successfully if:\n* The payment session must belong to the requesting merchant.\nThe `merchantId` from the API token must match the session's merchant.\nIt returns 403 Forbidden if it does not. \n* The session is in `Created` status.\nAny other status, such as `Completed`, `Failed`, or `Cancelled`, fails with the validation error: \"Payment Session can be canceled only in Created status\".\n\nSee Also:
\nTo create a new payment session, see `POST /v2/payment-sessions`.
\nTo retrieve a payment session by Id, see `GET /v2/payment-sessions/{{paymentSessionId}}`.\n", "parameters": [ { "name": "paymentSessionId", "in": "path", "x-method": "path", "description": "Specifies the payment session identifier.\n", "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": "\nGET {{baseURL}}/v2/ping\n\nThis endpoint pings an endpoint to validate the API token is active and valid.\n\nReturns 200 OK if the service is reachable.\nThere is no response body.\n", "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": "\nGET {{baseURL}}/v2/pos/transactions\n\nThis endpoint lists POS transactions.\n\nEach item in the response contains a reduced transaction object.\nFields are limited to the most relevant transaction information.\nThis is often sufficient for rendering transaction lists, dashboards, and reconciliation views.\nSituations requiring full detail context, such as for decline details, AVS response, or transaction events, are \navailable with `GET /v2/pos/transactions/{{posTransactionId}}`.\n\nSee Also:
\nTo retrieve a POS transaction by ID, see `GET /v2/pos/transactions/{posTransactionId}`.
\nTo create a new POS transaction, see `POST /v2/pos/transactions`.
\nTo cancel a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/cancel`.\n", "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.\n", "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,.\n\nIf only `fromDate` is specified, the search returns all available items from the `fromDate` value to the present.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an exclusive range to avoid a potentially excessive number of returns.\n", "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,.\n\nIf only `toDate` is specified, the search returns all available items up to the `toDate` value.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "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,\n\nValid values are:\n\n| Value | Description |\n| ----------- | ---------------------------------------------------------- |\n| Cancelled | The POS transaction was canceled before it completed. |\n| Completed | The POS transaction finished processing successfully. |\n| Failed | The POS transaction did not complete because of an error. |\n| InProgress | The POS transaction is still being processed. |\n" }, "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": "\nPOST {{baseURL}}/v2/pos/transactions\n\nThis endpoint creates a new card present payment transaction on a semi-Integrated terminal.\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nWhen called, the gateway connects to the specified terminal and starts the payment flow.\nThis includes screens for:\n* Card type selection\n* Tip entry\n* Card reading, such as for tap, insert, or swipe, depending on the merchant's settings.\n\nThe terminal flow is asynchronous.\nUse `GET /pos/transactions/{{posTransactionId}}` until `posTransactionStatus` reaches a terminal state, such as `Completed`, `Failed`, or `Cancelled`.\nWhen it is `Completed`, check the linked transaction for the payment outcome, which may have been declined.\n\nSee Also:
\nTo list POS transactions, see `GET /v2/pos/transactions`.
\nTo retrieve a POS transaction by ID, see `GET /v2/pos/transactions/{posTransactionId}`.
\nTo cancel a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/cancel`.\n", "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": "\nGET {{baseURL}}/v2/pos/transactions/{{posTransactionId}}\n\nThis endpoint retrieves a POS transaction by ID.\n\nSee Also:
\nTo list POS transactions, see `GET /v2/pos/transactions`.
\nTo create a new POS transaction, see `POST /v2/pos/transactions`.
\nTo cancel a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/cancel`.\n", "parameters": [ { "name": "posTransactionId", "in": "path", "x-method": "path", "description": "Specifies the POS transaction identifier.\n", "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.\n\nThis could be success, failure, or cancellation.\n\nIf `true`, the response is held until completion or timeout.
\nIf `false`, the response returns immediately.\nThe endpoint `GET /pos/transactions/{{posTransactionId}}` must be called for updates.\n", "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": "\nPOST {{baseURL}}/v2/pos/transactions/{{posTransactionId}}/cancel\n\nThis endpoint cancels a POS transaction by ID.\n\nThis sends a cancellation signal to the gateway to abort an in-progress POS transaction.\n\nIt can only be called while the transaction is in a cancellable state.\nThis is typically before the customer has presented their card on the terminal.\n\nA cancellation request is not guaranteed if the terminal has already begun processing the payment.\nIn that case the `posTransactionStatus` reflects the actual terminal outcome.\n\nSee Also:
\nTo list POS transactions, see `GET /v2/pos/transactions`.
\nTo retrieve a POS transaction by ID, see `GET /v2/pos/transactions/{posTransactionId}`.
\nTo create a POS transaction reversal, see `POST /v2/pos/transactions/reversal`.
\nTo print a receipt for a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/print-receipt`.\n", "parameters": [ { "name": "posTransactionId", "in": "path", "x-method": "path", "description": "Specifies the POS transaction identifier to cancel.\n", "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": "\nPOST {{baseURL}}/v2/pos/transactions/{{posTransactionId}}/print-receipt\n\nThis endpoint prints a POS transaction receipt.\n\nThe terminal must be in semi-integrated mode and available (online and ready).\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nSee Also:
\nTo list POS transactions, see `GET /v2/pos/transactions`.
\nTo retrieve a POS transaction by ID, see `GET /v2/pos/transactions/{posTransactionId}`.
\nTo create a new POS transaction, see `POST /v2/pos/transactions`.
\nTo cancel a POS transaction, see `POST /v2/pos/transactions/{posTransactionId}/cancel`.\n", "parameters": [ { "name": "posTransactionId", "in": "path", "x-method": "path", "description": "Specifies the POS transaction identifier whose receipt should be printed.\n", "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": "\nGET {{baseURL}}/v2/settings/payment-config\n\nThis endpoint lists the payment configuration settings.\n\nSee Also:
\nTo retrieve the contact information, see `GET /v2/settings/contact-information`.
\nTo retrieve the transaction autofill settings, see `GET /v2/settings/transaction-autofill`.
\nTo update the transaction autofill settings, see `PATCH /v2/settings/transaction-autofill`.\n", "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": "\nGET {{baseURL}}/v2/settings/contact-information\n\nThis endpoint lists contact information for the merchant.\n\nSee Also:
\nTo retrieve the payment configuration, see `GET /v2/settings/payment-config`.
\nTo retrieve the transaction autofill settings, see `GET /v2/settings/transaction-autofill`.
\nTo update the transaction autofill settings, see `PATCH /v2/settings/transaction-autofill`.\n", "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": "\nGET {{baseURL}}/v2/settings/transaction-autofill\n\nThis endpoint lists levels 2 and 3 autofill settings.\n\nThe additional levels 2 and 3 information must be included in transactions requiring that level.\nThis information can be pre-configured at the merchant settings level.\nThis allows merchants to automatically include the information instead of manually entering each time.\nThis automatic inclusion is called autofill.\n\nWith autofill, a merchant configures defaults once.\nTo set the defaults and values, see `PATCH /v2/settings/transaction-autofill`.\nThereafter, Flute automatically appends those values to every transaction even if not included in the transaction request.\nFor example, a merchant selling the same product, such as a subscription service could set the following:\n* taxRate: 8.5 for Level 2\n* product.code: SUB-001, product.unitPrice: 29.99 for Level 3\n\nEvery transaction then automatically includes that data, qualifying for lower interchange rates without any extra work per transaction.\n\nSee Also:
\nTo retrieve the payment configuration, see `GET /v2/settings/payment-config`.
\nTo retrieve the contact information, see `GET /v2/settings/contact-information`.
\nTo update the transaction autofill settings, see `PATCH /v2/settings/transaction-autofill`.\n", "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": "\nPATCH {{baseURL}}/v2/settings/transaction-autofill\n\nThis endpoint updates or sets levels 2 and 3 autofill settings.\n\nThis endpoint is a partial update.\nSend only the fields needed to be changed.\n* An omitted field is left unchanged.\n* A field marked with `null` clears a field.\n\nNested structures are also affected.\n\nThe additional levels 2 and 3 information must be included in transactions requiring that level.\nThis information can be pre-configured at the merchant settings level.\nThis allows merchants to automatically include the information instead of manually entering each time.\nThis automatic inclusion is called autofill.\n\nWith autofill, a merchant configures defaults once.\nFor the existing set of defaults and values, see `GET /v2/settings/transaction-autofill`.\nThereafter, Flute automatically appends those values to every transaction even if not included in the transaction request.\nFor example, a merchant selling the same product, such as a subscription service could set the following:\n* taxRate: 8.5 for Level 2\n* product.code: SUB-001, product.unitPrice: 29.99 for Level 3\n\nEvery transaction then automatically includes that data, qualifying for lower interchange rates without any extra work per transaction.\n\nSee Also:
\nTo retrieve the payment configuration, see `GET /v2/settings/payment-config`.
\nTo retrieve the contact information, see `GET /v2/settings/contact-information`.
\nTo retrieve the transaction autofill settings, see `GET /v2/settings/transaction-autofill`.\n", "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": "\nGET {{baseURL}}/v2/settlements/batches\n\nThis endpoint lists transaction batch settlements.\n\nSee Also:
\nTo settle transactions, see `POST /v2/settlements/settle`.\n", "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.\n", "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.\n", "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": "\nPOST {{baseURL}}/v2/settlements/settle\n\nThis endpoint explicitly settles batched transactions.\n\nSee Also:
\nTo list settlement batches, see `GET /v2/settlements/batches`.\n", "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": "\nGET {{baseURL}}/v2/terminals\n\nThis endpoint lists all available terminals for the authenticated merchant.\n\nOnly active terminals are returned.\nTerminals in the following conditions are excluded:\n* Pre-activation states, such as pending shipment or in transit\n* Deactivated terminals\n\nSee Also:
\nTo retrieve a terminal's status by ID, see `GET /v2/terminals/{terminalId}/status`.\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pagesize" }, { "name": "sortBy", "in": "query", "description": "Specifies a field name to sort the results by.\n\nIf null or omitted, results come back newest first.\n\nValid values are:
\nterminalManufacturer
\nmerchantCompanyName\n", "schema": { "type": "string", "example": "terminalManufacturer" } }, { "$ref": "#/components/parameters/sortOrder" }, { "name": "terminalStatus", "in": "query", "description": "Indicates the availability status of the terminal.\n\nValid values are:\n\n| Status | Meaning |\n|---------|----------------------------------------------------|\n| Busy | The terminal is processing a transaction. |\n| Ready | The terminal is available for a new transaction. |\n| Offline | The terminal is unavailable for a new transaction. |\n", "schema": { "enum": [ "Ready", "Busy", "Offline" ], "type": "string" }, "example": "Ready" }, { "name": "terminalMode", "in": "query", "description": "Indicates the operating mode of the terminal.\n\nValid values are:\n| Mode | Meaning |\n|-----------------|---------|\n| 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. |\n| 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. |\n", "schema": { "enum": [ "Standalone", "SemiIntegrated" ], "type": "string", "example": "SemiIntegrated" } }, { "name": "connectionStatus", "in": "query", "description": "Indicates the line status of the terminal.\n\nValid values are:\n\n| Status | Meaning |\n|---------|---------|\n| Online | The terminal is currently connected and reachable.

It has active network or internet connectivity. It is able to process transactions and communicate with the backend in real time. |\n| Offline | The terminal is disconnected or unreachable.

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. |\n", "schema": { "enum": [ "Online", "Offline" ], "type": "string" }, "example": "Online" }, { "name": "serialNumber", "in": "query", "description": "Filters by the serial number.\n\nThis is an exact match search.\n", "schema": { "type": "string", "example": "SN100001" }, "example": "SN100001" }, { "name": "search", "in": "query", "description": "Filters using a search string.\n\nThis performs a case-insensitive search that matches exactly or partially.\n\nThe field does not have to be specified.\nIf the results are to be sorted, use the `sortBy` field to specify the sort field.\n\nThe search includes the following fields:
\nserialNumber
\nterminalModel
\nterminalManufacturer
\nterminalId
\nmerchantCompanyName\n\nExample:
\nPeppared Street Cafe
\nStreet
\nree\n", "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": "\nGET {{baseURL}}/v2/terminals/{{terminalId}}/status\n\nThis endpoint Retrieves a merchant's terminal POS status by ID.\n\ninformation includes the connection and network state, hardware info and software version. \nThis provides the latest available information about a terminal, updated in near real-time.\nUse this endpoint before initiating a POS transaction.\nIt verifies the terminal is reachable and ready to accept a payment.\n\nBefore creating a POS transaction, check the `terminalStatus`.\nIt must be `Ready` and not `Busy` or `Offline`. \nThe fields `batteryLevel` and p`rinterStatus` can be used to warn merchants of low battery or printer issues before starting a transaction.\n\nDepending on the terminal's internet connectivity and operational status, the response may include limited terminal data.\n", "parameters": [ { "name": "terminalId", "in": "path", "x-method": "path", "description": "Specifies the terminal identifier.\n", "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": "\nGET {{baseURL}}/v2/transactions\n\nThis endpoint lists transactions.\n\nItems returned here present a limited amount of details.\nThese are intended to be a brief summary of the transactions.\nFor complete details of a specific transaction, see `GET /v2/transactions/{transactionId}`.\n\nSee Also:
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pagesize" }, { "name": "sortBy", "in": "query", "description": "Specifies a field name to sort the results by.\n\nIf null or omitted, results come back newest first.\n\nValid values are:
\ncardTokenType
\ncustomerCompanyName
\ncustomerName
\nmaskedCardNumber
\nmerchantCompanyName
\npaymentMethodType
\nprocessedAmount
\ntransactionDateTime
\ntransactionId
\ntransactionStatus\n", "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).\n\nIf only `fromDate` is specified, the search returns all available items from the `fromDate` value to the present.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an exclusive range to avoid a potentially excessive number of returns.\n", "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).\n\nIf only `toDate` is specified, the search returns all available items up to the `toDate` value.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "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.\n\nValid values are:\n| Value | Description |\n| ------------- | ------------------------------------------------------------------ |\n| ApiKey | An external application created the transaction using an API key. |\n| Invoice | A billed invoice created the transaction. |\n| MobileApp | A mobile application created the transaction. |\n| Portal | A staff member created the transaction through the web portal. |\n| QuickPayment | A one-time payment link created the transaction. |\n| Subscription | A recurring subscription created the transaction. |\n| TapToPay | A mobile device using tap to pay created the transaction. |\n| Terminal | A physical payment terminal created the transaction. |\n| WebComponent | An embedded web component created the transaction. |\n", "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.\n", "schema": { "type": "string", "format": "uuid", "example": "81915d04-1f2a-4b3c-4d5e-6f7a8b9c0d36" } }, { "name": "batchId", "in": "query", "description": "Specifies a filter by the settlement batch identifier.\n\nUse `null` to return transactions not yet settled into a batch.
\nOmit this value to not filter by batch identifier.\n", "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.\n\nValid values are:\n\n| Type | Description |\n|-------|--------------------------------------------|\n| ACH | Payment made through an ACH bank transfer. |\n| Card | Payment made with a credit or debit card. |\n| Cash | Payment made with physical currency. |\n", "schema": { "type": "string", "example": "Cash" }, "example": "Card" }, { "name": "customerId", "in": "query", "description": "Specifies a filter by the customer identifier.\n", "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.\n", "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.\n\nOnly transactions with this amount or more are returned.\n\nIf only `minAmount` is specified, the search returns all transactions with at least this amount.\nThe fields `minAmount` and `maxAmount` may be used together to create an exclusive range. \nWe recommend creating an inclusive range to avoid a potentially excessive number of returns.\n", "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.\n\nOnly transactions with this amount or less are returned.\n\nIf only `maxAmount` is specified, the search returns all transactions with no more than this amount.\nThe fields `minAmount` and `maxAmount` may be used together to create an exclusive range. \nWe recommend creating an inclusive range to avoid a potentially excessive number of returns.\n", "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.\n\nA referenceId is a duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n", "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": "\nPOST {{baseURL}}/v2/transactions\n\nThis endpoint creates a transaction.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.
\nTo calculate a transaction amount, see `POST /v2/transactions/calculate-amount`.`\n", "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.\n\n`billingAddress` and `contactInfo` are optional because the stored payment method already carries that data.\n", "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.\n\nPopulating `billingAddress` and `contactInfo` is recommended to improve processor acceptance.\n", "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.\n\nPopulating `billingAddress` and `contactInfo` is recommended to improve processor acceptance.\n", "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.\n\nPopulating `billingAddress` and `contactInfo` is recommended to improve processor acceptance.\n", "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).\n\nCapture the transaction later with `POST /transactions/{{transactionId}}/capture`.\n", "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": "\nGET {{baseURL}}/v2/transactions/{{transactionId}}\n\nThis endpoint retrieves a transaction by ID.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier.\n", "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.\n", "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.\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/capture\n\nThis endpoint captures a transaction.\n\nThis captures a previously authorized transaction and settling it for the specified amount. \nIt is used when a transaction was created with `captureMethod` of `Manual`.\nThis allows merchants to delay settlement until fulfillment is confirmed. \nThe `captureAmount` can be less than or equal to the original authorized amount to support partial captures.\n\nIf successful, this returns the full transaction object reflecting the updated status. \nA processor declining the transaction returns a 402 error.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier.\n", "required": true, "schema": { "type": "string", "format": "uuid", "example": "487471b7-0149-44ed-840b-97d920e06829" } } ], "requestBody": { "description": "Specifies an object defining the transaction.\n\nIf the request body is null or omitted, a full capture is included.
\nIf `baseAmount` is included, a partial capture is made.\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/reversal\n\nThis endpoint reverses, or refunds, a transaction.\n\nPayment method (card vs ACH) is auto-detected.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.
\nTo create an unreferenced credit, see `POST /v2/transactions/credit`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier to refund.\n", "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": "\nPOST {{baseURL}}/v2/transactions/credit\n\nThis endpoint refunds or returns funds without a reference.\n\nThis includes refunding to a credit card or provides an ACH credit.\n\nWithout a reference means the customer does not have the link to the original transaction identifier.\nThis creates a refund transaction that is not linked to a specific previous transaction.\nInstead of refunding a known transaction identifier, the system processes a standalone credit back to the cardholder's payment method.\n\nAs a warning, these are considered high-risk transaction types.\nFunds are returned directly from the merchant's account even if the original sale was not processed through Flute.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditRequestDto" }, "examples": { "Card unreferenced refund": { "description": "Unreferenced card refund using raw card data.\nSaved payment methods are not supported for unreferenced credits.\n", "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).\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/tip-adjustment\n\nThis endpoint adjusts, or adds, for tips to transaction.\n\nThis may only be used with card-present transactions.\nSpecifically, this is for either:\n* Authorized transaction, that is, a pre-authorized transaction that hasn't been captured yet.\n* Captured transactions that have not yet settled or not fully refunded.\n\nThe following is a typical workflow:\n1) For authorization: `POST /v2/transactions`\n1) For the tip adjustment: `POST /v2/transactions/tip-adjustment`\n1) For the capture: `POST /v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/capture`.
\nThe transactionId, the UUID in the path, is returned from `POST /v2/transactions`.\n1) For the transaction settlement: `POST /v2/settlements/settle`\n\nNotes for the workflow:\n* Tip adjustment requires both `merchant.IsTipsEnabled` and `merchant.IsTipAdjustmentEnabled`.\n* Tip adjustment is only allowed on credit card transactions (`CreditDebitType.Credit`), not debit cards.\n* Settlement closes the entire batch for that processor, not just this one transaction.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo calculate a transaction amount, see `POST /v2/transactions/calculate-amount`.
\nTo share a transaction receipt by SMS, see `POST /v2/transactions/{transactionId}/share-receipt`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier.\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/ach-hold\n\nThis endpoint holds an ACH transaction.\n\nSee Also:
\nTo release a held ACH transaction, see `POST /v2/transactions/{{transactionId}}/ach-release`\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo calculate a transaction amount, see `POST /v2/transactions/calculate-amount`.
\nTo share a transaction receipt by SMS, see `POST /v2/transactions/{transactionId}/share-receipt`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier.\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/ach-release\n\nThis endpoint releases a held ACH transaction.\n\nSee Also:
\nTo hold an ACH transaction, see `POST /v2/transactions/ach-hold`\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.
\nTo share a transaction receipt by SMS, see `POST /v2/transactions/{transactionId}/share-receipt`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier.\n", "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": "\nPOST {{baseURL}}/v2/transactions/calculate-amount\n\nThis endpoint calculates transaction amounts.\n\nThe amounts are based on the merchant's ZCP (zero cost processing) mode.\nThis includes dual pricing, cash discounts, or credit card surcharges.\nApplications, such as payment terminals or point of service devices, can then display the appropriate amounts.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo share a transaction receipt by SMS, see `POST /v2/transactions/{transactionId}/share-receipt`.\n", "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.\n\nExamples:
\n125
\n125.5
\n125.50\n", "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.\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 10.5 (as $10.5)\n", "example": 10.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "request", "description": "Specifies the tip rate to apply.\n\nEncoded as raw percentage.\nFor example: 18.5 for 18.5%.\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.5 (as 18.5%)\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 25 (for $25)\n", "example": 25 }, "discountRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates a percentage of a discount to be applied.\n\nIf this value is provided, it must be greater than zero.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 5.5 (for 5.5%)\n", "example": 5.5 }, "surchargeRate": { "type": "number", "format": "double", "x-method": "request", "description": "Specifies the credit Card surcharge rate override.\n\nExample: 2.5 (for 2.5%)\n", "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": "\nPOST {{baseURL}}/v2/transactions/{{transactionId}}/share-receipt\n\nThis endpoint shares a transaction receipt by SMS.\n\nThe following is a typical workflow:\n1) For authorization: `POST /v2/transactions`\n1) For sharing the receipt: `/v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/share-receipt`.
\nThe transactionId, the UUID in the path, is returned from `POST /v2/transactions`.\n1) A successful response is 200 OK with no response body.\n\nNotes for the workflow:\n* The `hasCustomerConsent` is required and must be `true`.\nThe endpoint will reject the request if the customer has not explicitly consented to receive an SMS.\n* The `mobileNumber` does not have to match the one on the original transaction.\nA receipt can be sent to any phone number the customer provides at time of receipt.\n\nSee Also:
\nTo list transactions, see `GET /v2/transactions`.
\nTo retrieve a transaction by ID, see `GET /v2/transactions/{transactionId}`.
\nTo create a new transaction, see `POST /v2/transactions`.
\nTo capture a transaction, see `POST /v2/transactions/{transactionId}/capture`.
\nTo reverse a transaction, see `POST /v2/transactions/{transactionId}/reversal`.\n", "parameters": [ { "name": "transactionId", "in": "path", "x-method": "path", "description": "Specifies the transaction identifier to send a receipt for.\n", "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": "\nGET {{baseURL}}/v2/webhooks/endpoints\n\nThis endpoint lists all webhook endpoints.\n\nThe endpoints are for both active and inactive webhooks.\n\nSee Also:
\nTo create a webhook, see `POST /v2/webhooks/endpoints`.
\nTo retrieve a specified webhook, see `GET /v2/webhooks/endpoints/{{endpointId}}`.
\nTo update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.\n", "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,.\n\nIf only `fromDate` is specified, the search returns all available items from the `fromDate` value to the present.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an exclusive range to avoid a potentially excessive number of returns.\n", "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,.\n\nIf only `toDate` is specified, the search returns all available items up to the `toDate` value.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "schema": { "type": "string", "format": "date-time", "example": "2026-02-27T12:05:54.322Z" } }, { "name": "endpointStatus", "in": "query", "description": "Filters by the endpoint status.\n\nValid values are:\n| Value | Description |\n| --------- | ------------------------------------------------ |\n| Active | The webhook endpoint is enabled and available for use. |\n| Inactive | The webhook endpoint is disabled and not available for use.

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. |\n", "schema": { "enum": [ "Active", "Inactive" ], "type": "string", "example": "Active" } }, { "name": "search", "in": "query", "description": "Filters using a search string.\n\nThis is a partial, case-insensitive text search.\n\nThe following fields are searched:
\nendpointName
\nendpointUrl\n", "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": "\nPOST {{baseURL}}/v2/webhooks/endpoints\n\nThis endpoint creates a new webhook endpoint.\n\nNew endpoints default to `Active` on creation.\nOnly `Active` endpoints are eligible for real event dispatch.\n\nSee Also:
\nTo list all of available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo retrieve a specified webhook, see `GET /v2/webhooks/endpoints/{{endpointId}}`.
\nTo update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.
\nTo delete a webhook, see `DELETE /v2/webhooks/endpoints/{{endpointId}}`\n", "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.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "example": "Peppared Street Cafe's Reconciliation" }, "endpointUrl": { "type": "string", "maxLength": 2048, "x-method": "request", "description": "Specifies the HTTPS callback URL that receives webhook events.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "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": "\nGET {{baseURL}}/v2/webhooks/endpoints/{{endpointId}}\n\nThis endpoint retrieves a webhook endpoint by ID.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.
\nTo test a webhook, see `POST /v2/webhooks/endpoints/{{endpointId}}/ping`.\n", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "
Specifies the webhook identifier to retrieve.\n", "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": "\nPATCH {{baseURL}}/v2/webhooks/endpoints/{{endpointId}}\n\nThis endpoint updates a webhook endpoint.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo retrieve a specified webhook, see `GET /v2/webhooks/endpoints/{{endpointId}}`.
\nTo delete a webhook, see `DELETE /v2/webhooks/endpoints/{{endpointId}}`.\n\n\n [ Query parameters ]\n [ Response fields ]\n\n", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "
Specifies the webhook identifier to retrieve.\n", "schema": { "type": "string", "format": "uuid", "required": true, "example": "76804cf3-4a5b-4c6d-7e8f-9a0b1c2d3e69" } } ], "requestBody": { "description": "\n\nThis endpoint is a partial update.\nSend only the fields needed to be changed.\n* An omitted field is left unchanged.\n* A field marked with `null` clears a field.\n", "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 ", "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": "\nDELETE {{baseURL}}/v2/webhooks/endpoints/{{endpointId}}\n\nThis endpoint deletes a webhook endpoint.\n\nAll outstanding pending and scheduled retries for this specified webhook are cancelled.\nReferences in log files are not erased.\n\nSee Also:
\nTo create a webhook, see `POST /v2/webhooks/endpoints`.
\nTo update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.
\nTo test a webhook, see `POST /v2/webhooks/endpoints/{{endpointId}}/ping`\n", "parameters": [ { "name": "endpointId", "in": "path", "required": true, "description": "Specifies the webhook identifier to delete.\n", "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": "\nGET {{baseURL}}/v2/webhooks/endpoints/{{endpointId}}/ping\n\nThis endpoint validates connectivity to the registered endpoint URL.\n", "parameters": [ { "name": "endpointId", "in": "path", "x-method": "path", "description": "Specifies the webhook endpoint identifier to ping.\n", "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": "\nGET {{baseURL}}/v2/webhooks/event-types\n\nThis endpoint lists available webhook event types.\n\nThe list of available webhook event types are provided by Flute.\nThese are the only events types available to be selected from.\nOperating system or other company's events cannot be used.\n\nEach webhook must include at least one.\nMultiple events types may be included in a specific webhook but duplicates are not allowed.\nEach webhook is independent from other webhooks.\nThe same events type may be included in different webhooks.\n\nThe set of events types do not have to relate to each other.\nIt is the set of all event types of interest for the client.\nClients may create multiple webhooks to provide granularity for their processes.\nIn that case, the set of events types would likely be related for the client's intent.\n\nSee Also:
\nTo create a webhook, see `POST /v2/webhooks/endpoints`.
\nTo update a webhook, see `PATCH /v2/webhooks/endpoints/{{endpointId}}`.\n", "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": "\nGET {{baseURL}}/v2/webhooks/delivery-logs\n\nThis endpoint lists webhook delivery logs for the merchant account.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo retrieve a specified delivery log, see `GET /v2/webhooks/delivery-logs/{{endpointId}}`.
\nTo export delivery log, see `GET /v2/webhooks/delivery-logs/export`.\n\nQuery parameters may be combined to filter the exported results.\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pagesize" }, { "$ref": "#/components/parameters/sortby" }, { "$ref": "#/components/parameters/sortOrder" }, { "name": "endpointId", "in": "query", "description": "
Specifies the webhook identifier to filter by.\n", "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.\n\n| HTTP Status | Meaning |\n|-------------|---------|\n| Success | Delivery succeeded |\n| Failure | Delivery failed |\n", "schema": { "$ref": "#/components/schemas/webhookdeliverylogstatus" } }, { "name": "endpointHTTPResponseCode", "in": "query", "description": "Filters by the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|---------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n", "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).\n\nIf only `fromDate` is specified, the search returns all available items from the `fromDate` value to the present.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an exclusive range to avoid a potentially excessive number of returns.\n", "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).\n\nIf only `toDate` is specified, the search returns all available items up to the `toDate` value.\nThe fields `fromDate` and `toDate` may be used together to create an exclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "schema": { "type": "string", "format": "date-time", "example": "2026-02-27T12:05:54.322Z" } }, { "name": "search", "in": "query", "description": "Filters using a search string.\n\nThis performs a case-insensitive search that matches exactly or partially.\n\nThe field does not have to be specified.\nIf the results are to be sorted, use the `orderby` field to specify the sort field.\n\nThe search includes the following fields:
\nEventId (Exact match and complete UUID only. Otherwise, this value is ignored.)
\nWebhookName
\nEndpointUrl\n", "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": "\nGET {{baseURL}}/v2/webhooks/delivery-logs/{{deliveryLogId}}\n\nThis endpoint retrieves a delivery log by ID.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo test a webhook, see `POST /v2/webhooks/endpoints/{{endpointId}}/ping`.
\nTo manually retry a webhook delivery attempt, see `POST /v2/webhooks/delivery-logs/{{deliveryLogId}}/retry`.\n", "parameters": [ { "name": "deliveryLogId", "in": "query", "description": "
Specifies the delivery log identifier to retrieve.\n", "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": "\nGET {{baseURL}}/v2/webhooks/delivery-logs/export\n\nThis endpoint exports webhook delivery logs as a CSV or JSON file.\n\nQuery parameters may be combined to filter the exported results.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo list all delivery logs, see `GET /v2/webhooks/delivery-logs`.
\nTo retrieve a specified delivery log, see `GET /v2/webhooks/delivery-logs/{{endpointId}}`.\n", "parameters": [ { "name": "endpointId", "in": "query", "description": "
Specifies the webhook identifier to retrieve.\n", "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.\n\n| HTTP Status | Meaning |\n|:-----------:|---------|\n| Success | Delivery succeeded |\n| Failure | Delivery failed |\n", "schema": { "$ref": "#/components/schemas/webhookdeliverylogstatus" } }, { "name": "endpointHTTPResponseCode", "in": "query", "description": "Specifies the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|---------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n", "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.\n\nValid values are:\n\n| Value | Description |\n| ------ | ---------------------------------- |\n| Csv | Returns the export as a CSV file. |\n| Json | Returns the export as a JSON file. |\n", "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.\n" } }, "application/json": { "schema": { "type": "string", "format": "byte", "description": "Indicates the returned file in the specified format.\n" } } } }, "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": "\nPOST {{baseURL}}/v2/webhooks/delivery-logs/{{endpointId}}/retry\n\nThis endpoint manually retries a failed webhook delivery.\n\nThis is a single try each time.\nIt does not automatically retry multiple times.\nIt does not interfere with or interrupt the normal retry procedures.\n\nSee Also:
\nTo list all available webhooks, see `GET /v2/webhooks/endpoints`.
\nTo test a webhook, see `POST /v2/webhooks/endpoints/{{endpointId}}/ping`.
\nTo list all available delivery logs, see `GET /v2/webhooks/delivery-logs`\n", "parameters": [ { "name": "deliveryLogId", "in": "path", "required": true, "description": "
Specifies the delivery log identifier to retry.\n", "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.\n\nExample: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error\n", "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.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|---------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 401\n", "example": 401 }, "source": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the source of the error.\n\nExample: <Service>\n", "example": "" }, "exceptionType": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the error's exception type.\n\nExample: FluentValidation.ValidationException\n", "example": "FluentValidation.ValidationException" }, "correlationId": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the correlation identifier.\n\nExample: aa6cfcd0-0295-4a4c-b074-8c901f114fef\n", "example": "aa6cfcd0-0295-4a4c-b074-8c901f114fef" }, "entityId": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the entity identifier.\n\nExample:
\nnull\n" }, "errorCode": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the error code.\n\nExample:
\nnull\n" }, "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.\n\nThis value may be null when this payment method is an orphan owned by the merchant directly.\nAn orphan payment method is a payment method in the merchant's vault but has no customer record associated with it.\n\nExample: 8fa8e727-73c6-436e-b56f-6f55aabf3b1c\n", "example": "8fa8e727-73c6-436e-b56f-6f55aabf3b1c" }, "AddressDto": { "type": "object", "required": [ "countryCode" ], "description": "Identifies the address information.\n", "properties": { "addressLine1": { "type": "string", "nullable": true, "x-method": "request", "description": "Identifies the street address.\n\nExample: 21 E. Main Street\n", "example": "21 E. Main Street" }, "addressLine2": { "type": "string", "nullable": true, "x-method": "request", "description": "Identifies additional street address information.\n\nExample: Office 3\n", "example": "Office 3" }, "city": { "type": "string", "x-method": "request", "nullable": true, "description": "Identifies the name of the city.\n\nExamples:
\nChicago
\nNew York
\nSalt Lake City\n", "example": "Chicago" }, "postalCode": { "type": "string", "x-method": "request", "minLength": 2, "maxLength": 15, "nullable": true, "description": "Identifies the postal or ZIP code.\n\nExamples:
\n60601
\n60601-0001\n", "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).\n\nFor regions outside the US, use the ISO 3166-2 format.\n\nExamples:
\nTX
\nWA
\nIL\n", "example": "NY" }, "countryCode": { "type": "string", "nullable": true, "x-method": "request", "description": "Identifies the country identifier (in two letter ISO 3166-1 format).\n\nExamples:
\nUS
\nCA
\nGB\n", "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.\n\nThis value is used to detect duplicate transactions.\nFor example, a duplicate pending record is marked as `Skipped`.\n\nExample: CUST-EXT-001\n", "example": "CUST-EXT-001" }, "firstName": { "type": "string", "x-method": "response", "description": "Indicates the customer's first name.\n\nExample: Alexandro\n", "example": "Alexandro", "nullable": true }, "lastName": { "type": "string", "x-method": "response", "description": "Indicates the customer's last name.\n\nExample: Peppared\n", "example": "Peppared", "nullable": true }, "companyName": { "type": "string", "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "email": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "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.\n\nExample: 2026-05-01T12:00:56.264Z\n", "example": "2026-05-01T12:00:56.264Z" }, "paymentMethodsCount": { "type": "integer", "format": "int32", "x-method": "response", "description": "Indicates the number of payment methods.\n\nExample: 3\n", "example": 3 } }, "additionalProperties": false }, "pageInfo": { "type": "object", "description": "Indicates an object describing the pagination status.\n\nIf additional pages to review are needed, repeat the exact same search but include a new pageIndex value.\nTypically, this will increment the current `pageIndex` by one.\nHowever, any valid value may be used.\nValue restrictions include:\n* A value less than zero is not permitted.
\n* Values equal to or greater than `totalPages` end successfully but will not return any items.\n", "properties": { "pageIndex": { "type": "integer", "format": "int32", "minimum": 0, "x-method": "response", "description": "Indicates the page number from the search results.\n\nThe pageIndex value is zero-based.\nValid values range from zero to `totalPages` less one.
\nFor example, if `totalPages` = 10, then the valid range is zero to nine. \n\nExample: 0\n", "example": 0 }, "pageSize": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 200, "x-method": "response", "description": "Indicates the number of items returned per page.\n\nExample: 20\n", "example": 20 }, "totalItems": { "type": "integer", "format": "int32", "x-method": "response", "description": "Indicates the total number of items across all pages.\n\nExample: 1012\n", "example": 1012 }, "totalPages": { "type": "integer", "format": "int32", "x-method": "response", "description": "Indicates the total number of pages available.\n\nExample: 51\n", "example": 51 }, "hasMore": { "type": "boolean", "description": "Indicates additional pages are available after the current one.\n\nIf `true`, additional pages are available after the current one.
\nIf `false`, additional pages are not available after the current one.\n\nExample: true\n", "example": true } } }, "PageOfListCustomersResponseDto": { "type": "object", "description": "", "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.\n\nExample: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error\n", "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.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|---------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 401\n", "example": 401 }, "source": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the source of the error.\n\nExample: <Service>\n", "example": "" }, "exceptionType": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the error's exception type.\n\nExample: FluentValidation.ValidationException\n", "example": "FluentValidation.ValidationException" }, "correlationId": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the correlation identifier.\n\nExample: aa6cfcd0-0295-4a4c-b074-8c901f114fef\n", "example": "aa6cfcd0-0295-4a4c-b074-8c901f114fef" }, "entityId": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the entity identifier.\n\nExample:
\nnull\n" }, "errorCode": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the error code.\n\nExample:
\nnull\n" }, "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.\n\nExample:\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize. \n\nExample: Peppared Street Cafe's Preferred Payment\n", "example": "Peppared Street Cafe's Preferred Payment" }, "cardNumber": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the card number.\n\nThis is the PAN (primary account number) for the transaction.\n\nExample: 411235455213655\n", "example": "411235455213655" }, "securityCode": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the securityCode (sometimes also called similarly to CCV) for the card.\n\nThis is a three or four digit security code on the credit card.\n\nExample: 483\n", "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).\n\nExamples:
\n02
\n10
\n12\n", "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).\n\nExample: 2032\n", "example": 2032 } }, "additionalProperties": false }, "accountNumberRequest": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the bank account number for the ACH transaction.\n\nWe recommend avoiding the use of an account number.\nInstead, use `paymentMethodId` when possible.\n\nExample: 1234567890\n", "example": "1234567890" }, "AccountHolderType": { "enum": [ "Business", "Personal" ], "type": "string", "description": "Identifies the holder type of the account.\n\nValid values are:\n\n| Type | Description |\n|----------|------------------------------------------------|\n| Business | Card issued to a business or company account. |\n| Personal | Card issued to an individual for personal use. |\n\nExample: Business\n", "example": "Business" }, "AccountType": { "enum": [ "Checking", "Savings" ], "type": "string", "description": "Identifies the type of the account.\n\nValid values are:\n\n| Type | Description |\n|----------|------------------------------------------------|\n| Checking | Account used for regular daily transactions. |\n| Savings | Account used to hold and grow funds over time. | \n\nExample: Checking\n", "example": "Checking" }, "CustomerPaymentMethodAchDto": { "type": "object", "properties": { "paymentName": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the name for the payment method.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "example": "Peppared Street Cafe's Preferred Payment" }, "routingNumber": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the ACH's account routing number.\n\nExample: 021000021\n", "example": "021000021" }, "accountNumber": { "$ref": "#/components/schemas/accountNumberRequest" }, "taxId": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the tax identifier.\n\nExample: 12-3456789\n", "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.\n\nExample: Alexandro\n", "example": "Alexandro" }, "lastName": { "minLength": 1, "type": "string", "x-method": "request", "description": "Specifies the customer's last name.\n\nExample: Peppared\n", "example": "Peppared" }, "companyName": { "type": "string", "x-method": "request", "description": "Specifies the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "email": { "type": "string", "x-method": "request", "nullable": true, "description": "Specifies the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "hasSmsConsent": { "type": "boolean", "nullable": true, "default": false, "x-method": "request", "description": "Specifies the customer has consented to receiving the SMS.\n\nIf `true`, the customer has consented to receiving the SMS.
\nIf `false`, the customer has not consented to receiving the SMS.\n\nExample: true\n", "example": true }, "shouldUseBillingAsShippingAddress": { "type": "boolean", "x-method": "request", "description": "Specifies to use the billing address as shipping address.\n\nIf `true`, use the billing address as shipping address.
\nIf `false`, do not use the billing address as shipping address.\n\nExample: true\n", "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.\n" }, "paymentMethodsAchAccounts": { "type": "array", "nullable": true, "x-method": "request", "items": { "$ref": "#/components/schemas/CustomerPaymentMethodAchDto" }, "description": "Specifies accepted ACH accounts payment methods.\n" } }, "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.\n\nThis is the identifier of a previously saved ACH account to charge.\n\nExample: 39a95e35-6d50-45ec-884b-c2417edf005d\n", "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.\n\nExamples:
\n07
\n12
\n", "example": 12 }, "expirationYearRequest": { "type": "integer", "format": "int32", "nullable": true, "description": "Identifies the expiration year (in a four-digit number) of the card.\n\nExample: 2032\n", "example": 2032 }, "TokenType": { "enum": [ "Local", "Network" ], "type": "string", "description": "Indicates the type of the token.\n\nValid values are:\n\n| Type | Meaning |\n|---------| ------- |\n| Local | Tokenized and stored within Flute's own vault |\n| Network | Tokenized through a card network, such as Visa or Mastercard, using their network tokenization services |\n\nExample: Local\n", "example": "Local" }, "CardType": { "enum": [ "Unknown", "Visa", "MasterCard", "AmericanExpress", "DinersClub", "Discover", "JCB" ], "type": "string", "description": "Indicates the type of the card.\n\nValid values are:\n\n| Type | Description |\n|-------------------|---------------------------------------------------|\n| AmericanExpress | Card issued by American Express network. |\n| DinersClub | Card issued by the Diners Club network. |\n| Discover | Card issued by the Discover network. |\n| JCB | Card issued by the Japan Credit Bureau network. |\n| MasterCard | Card issued by the MasterCard network. |\n| Unknown | Card type could not be determined. |\n| Visa | Card issued by the Visa network. |\n\nExample: Visa\n", "example": "Visa" }, "CreditDebitType": { "enum": [ "Credit", "Debit", "Unknown" ], "type": "string", "description": "Indicates the card is either credit or debit.\n\nValid values are:\n\n| Type | Description |\n|---------|--------------------------------------------|\n| Credit | Card draws funds from a credit line. |\n| Debit | Card draws funds from a bank account. |\n| Unknown | Card funding type could not be determined. |\n\nExample: Credit\n", "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.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Personal Visa\n", "nullable": true, "example": "Personal Visa" }, "isDefault": { "type": "boolean", "x-method": "response", "description": "Indicates this payment method is the default payment method.\n\nIf `true`, the card is the default payment method.
\nIf `false`, the card is not the default payment method.\n\nExample: true\n", "example": true }, "cardMask": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the PAN (primary account number).\n\nThis value may be partially obscured as additional security.\nThis value can be safely displayed to clients without revealing the actual or full account number.\n\nExample: ************3655\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "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.\n\nIf `true`, this ACH account is the default payment method.
\nIf `false`, this ACH account is not the default payment method.\n\nExample: true\n", "example": true }, "accountNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the bank account number for the ACH transaction.\n\nThis value may be partially obscured as additional security.\nIt can then be safely displayed to clients without revealing the actual or full account number.\n\nExamples:
\n1234567890
\n******7890\n", "example": "******7890" }, "routingNumber": { "type": "string", "x-method": "response", "description": "Indicates the ACH's account routing number.\n\nExample: 021000021\n", "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.\n\nExample: 12-3456789\n", "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.\n\nThis value is used to detect duplicate transactions.\nFor example, a duplicate pending record is marked as `Skipped`.\n\nExample: CUST-EXT-12345\n", "nullable": true, "example": "CUST-EXT-12345" }, "firstName": { "type": "string", "x-method": "response", "description": "Indicates the customer's first name.\n\nExample: Alexandro\n", "example": "Alexandro", "nullable": true }, "lastName": { "type": "string", "x-method": "response", "description": "Indicates the customer's last name.\n\nExample: Peppared\n", "example": "Peppared", "nullable": true }, "companyName": { "type": "string", "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "email": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "hasSmsConsent": { "type": "boolean", "x-method": "response", "description": "Specifies the customer has consented to receiving the SMS.\n\nIf `true`, the customer has consented to receiving the SMS.
\nIf `false`, the customer has not consented to receiving the SMS.\n\nExample: true\n", "example": true }, "shouldUseBillingAsShippingAddress": { "type": "boolean", "x-method": "response", "description": "Indicates to use the billing address as shipping address.\n\nIf `true`, use the billing address as shipping address.
\nIf `false`, do not use the billing address as shipping address.\n\nExample: true\n", "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.\n\nExample: 31\n", "example": 31 }, "transactionsVolume": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the sum of the transactions.\n\nExample: 1234.56\n", "example": 1234.56 }, "lastTransactionAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "response", "nullable": true, "description": "Indicates the amount of the last transaction.\n\nExample: 99.99\n", "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.\n\nExample: 2026-05-01T12:00:56.264Z\n", "example": "2026-05-01T12:00:56.264Z" }, "numberOfSubscriptions": { "type": "integer", "format": "int32", "x-method": "response", "description": "Indicates the number of active subscriptions.\n\nExample: 6\n", "example": 6 }, "cards": { "type": "array", "x-method": "response", "items": { "$ref": "#/components/schemas/GetCustomerResponseDtoCardDto" }, "description": "Indicates the card payment methods.\n", "nullable": true }, "achAccounts": { "type": "array", "x-method": "response", "items": { "$ref": "#/components/schemas/GetCustomerResponseDtoAchAccountDto" }, "description": "Indicates the ACH (automated clearing house) payment methods.\n", "nullable": true } }, "additionalProperties": false }, "UpdateCustomerRequestDto": { "type": "object", "properties": { "firstName": { "type": "string", "x-method": "request", "description": "Specifies the customer's first name.\n\nExample: Alexandro\n", "example": "Alexandro", "nullable": true }, "lastName": { "type": "string", "x-method": "request", "description": "Specifies the customer's last name.\n\nExample: Peppared\n", "example": "Peppared", "nullable": true }, "companyName": { "type": "string", "x-method": "request", "description": "Specifies the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "email": { "type": "string", "x-method": "request", "nullable": true, "description": "Specifies the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "hasSmsConsent": { "type": "boolean", "nullable": true, "default": false, "x-method": "request", "description": "Specifies the customer has consented to receiving the SMS.\n\nIf `true`, the customer has consented to receiving the SMS.
\nIf `false`, the customer has not consented to receiving the SMS.\n\nExample: true\n", "example": true }, "shouldUseBillingAsShippingAddress": { "type": "boolean", "x-method": "request", "description": "Specifies to use the billing address as shipping address.\n\nIf `true`, use the billing address as shipping address.
\nIf `false`, do not use the billing address as shipping address.\n\nExample: true\n", "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.\n\nExample: 5611f824-48ef-4255-978d-91ce13953bbd\n", "example": "5611f824-48ef-4255-978d-91ce13953bbd" }, "GetApiKeysResponseDtoApiKeyDto": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Indicates the client identifier.\n\nExample: 5c0f39f6-02a8-4053-9e72-56d9d5947c1c\n", "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.\n\nExample: Production integration key\n", "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.\n\nExample: Production integration key\n", "example": "Production integration key" } }, "additionalProperties": false }, "CreateApiKeyResponseDto": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Indicates the client identifier.\n\nExample: 919c19ac-09cf-40c1-b093-413b9cabde43\n", "format": "uuid", "x-method": "response", "example": "919c19ac-09cf-40c1-b093-413b9cabde43" }, "clientSecret": { "type": "string", "format": "UUID", "x-method": "response", "description": "Indicates the client secret.\n\nThe client secret is returned once and only during its creation here.\nStore it securely.\nProtect the `clientSecret` as if it were a password.\n\nExample: bcaa0840-2872-44ea-9122-552a804a054a\n", "nullable": true, "example": "bcaa0840-2872-44ea-9122-552a804a054a" } }, "additionalProperties": false }, "PaymentMethodType": { "enum": [ "Card", "ACH", "Cash" ], "type": "string", "description": "Identifies the payment method type.\n\nValid values are:\n\n| Type | Description |\n|-------|--------------------------------------------|\n| ACH | Payment made through an ACH bank transfer. |\n| Card | Payment made with a credit or debit card. |\n| Cash | Payment made with physical currency. |\n\nExample: Card\n", "example": "Card" }, "PaymentMethodResponseDtoCardDetails": { "type": "object", "properties": { "cardMask": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the PAN (primary account number).\n\nThis value may be partially obscured as additional security.\nThis value can be safely displayed to clients without revealing the actual or full account number.\n\nExample: ************3655\n", "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.\n\nThis value may be partially obscured as additional security.\nIt can then be safely displayed to clients without revealing the actual or full account number.\n\nExamples:
\n1234567890
\n******7890\n", "example": "******7890" }, "routingNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the ACH (automated clearing house) account routing number.\n\nExample: 021000021\n", "example": "021000021" }, "accountType": { "$ref": "#/components/schemas/AccountType" }, "accountHolderType": { "$ref": "#/components/schemas/AccountHolderType" }, "taxId": { "type": "string", "x-method": "response", "description": "Indicates the tax identifier.\n\nThis value may be partially obscured as additional security.\nThis value can be safely displayed to clients without revealing the actual or full value.\n\nExample: **-***6789\n", "example": "**-***6789", "nullable": true }, "companyName": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nThis is the ACH legal-entity name.\nSet on business orphan payment methods at create time so it is available at transaction time when `ContactInfo.CompanyName` is omitted on the request.\n\nExample: Peppared Street Cafe\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "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.\n\nIf `true`, this is the default payment method.
\nIf `false`, this is not the default payment method.\n\nExample: true\n", "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.\n\nExample: 2026-01-15T10:30:56.264Z\n", "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.\n\nExample: 4111111111111111\n", "example": "4111111111111111" }, "securityCode": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the securityCode (sometimes also called similarly to CCV) for the card.\n\nThis is a three or four digit security code on the credit card.\n\nExample: 483\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "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.\n\nExample: 021000021\n", "example": "021000021", "nullable": true }, "accountNumber": { "$ref": "#/components/schemas/accountNumberRequest" }, "taxId": { "type": "string", "x-method": "request", "description": "Specifies the tax identifier.\n\nExample: 12-3456789\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "example": "Peppared Street Cafe's Preferred Payment" }, "companyName": { "type": "string", "x-method": "request", "description": "Specifies the name of the customer's company or organization.\n\nThis is the legal entity name.\nRequired for orphan Business ACH transactions when the request does not supply it on the transaction's ContactInfo.\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe's Preferred Payment\n", "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.\n\n| Name | Description |\n| -------------- | --------------------------------------------- |\n| Payment | Standard payment session. |\n| SaveMethod | Vault-only session to store a payment method. The amount must be zero.

No payment is processed. This stores the customer's card details for future use. `vaultedPaymentMethodId` is returned on the session once confirmed. |\n| PaymentAndSave | Charge the payment and store the customer's card details for future use.

`vaultedPaymentMethodId` is returned on the session once confirmed. |\n\nExample: Payment\n", "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.\n\nFor payment sessions (mode of either `SaveMethod` or `PaymentAndSave`), this value must be greater than zero.\n\nFor vault-only payment sessions (mode of `SaveMethod`), this value must be zero.\n\nA value of null creates a flexible-amount payment session where the amount is set at checkout.\n\nExamples:
\n64.99
\n0
\nnull\n", "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.\n\nThis value is applicable only to `Payment` and `PaymentAndSave` from `mode`.\n\nIf `true`, bypasses AVS in the payment gateway.
\nIf `false`, does not bypass AVS in the payment gateway.\n\nExample: true\n", "example": true }, "referenceId": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies a reference identifier provided by the merchant.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: 10001\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\nExample: 14.50 (for $14.50)\n", "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.\n\nThis value is not needed if using Flute Elements and Flute Checkout.\n\nExample: https://api.payments.flute.com/xOut/sessions/session-complete.html\n", "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.\n\nValid values are:\n\n| Payment method | Type |\n|----------------|------|\n| Card | Credit or debit card payment |\n| ACH | ACH (automated clearing house) payment |\n\nExample: Card\n", "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.\n\nThese values are used to store supplemental information.\nThey are not functionally used in this endpoint.\nInstead, they are included while retrieving the payment session.\nThis allows additional notes to be passed along to the operator.\n\nPass null to clear all metadata.\n\nExamples:
\n[ {\"orderId\": \"9921\"} ]
\n[ {\"Guest notes\": \"Member of The World of Hyatt Credit Card.\"} ]
\n[{\"orderId\": \"9921\"}, {\"Guest notes\": \"Member of The World of Hyatt Credit Card.}]\n", "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.\n\nThis value is not needed if using Flute Elements and Flute Checkout.\n\nExample: Thank you for shopping with us.\n", "example": "Thank you for shopping with us." }, "isMultiUse": { "type": "boolean", "nullable": true, "description": "Specifies the checkout URL can be used for multiple payments.\n\nThis value is applied only if using Flute Elements or Flute Checkout.\n\nIf `true`, the checkout URL can be used for multiple payments.
\nIf `false`, the checkout URL cannot be used for multiple payments.\n\nExample: true\n", "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.\n\nThe time must be in the future.\n\nIf this value is null or omitted, there is no expiration date.\n\nExample: 2027-02-19T20:24:52.934Z\n", "example": "2027-02-19T20:24:52.934Z" }, "pageName": { "type": "string", "nullable": true, "description": "Specifies the display name shown on the checkout page.\n\nThis is a free-formed name that is convenient for the merchant to recognize. \n\nExample: Peppared Street Cafe's Preferred Payment\n", "example": "Peppared Street Cafe's Preferred Payment" }, "paymentNotes": { "type": "string", "nullable": true, "description": "Specifies additional notes shown to the payer on the checkout page.\n\nExample: The client's server is being repaired.\n", "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.\n\nThis is also called the `paymentSessionId`.\n\nIf `mode` was `SaveMethod`, a payment session was successfully created but with an automatic `Completed` status.\nThat payment session is not available for additional processing.\nThe paymentSessionId may be used to retrieve the payment session information.\nFor those details, see `GET /v2/payment-sessions/{{paymentSessionId}}`.\n\nIf the mode was `PaymentAndSave`, a payment session was successfully created. \nThat payment session is available for additional processing.\n\nExample: dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25\n", "example": "dce6a259-0a1b-4c2d-3e4f-5a6b7c8d9e25" }, "checkoutUrl": { "type": "string", "nullable": true, "description": "Indicates full URL of the hosted checkout page for this payment session.\n\nExample: https://api.payments.flute.com/xOut/sessions/session-complete.html\n", "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.\n\nExample: https://smallurl.com/4kxm9p2\n", "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.\n\nThis is a free-formed type name that is convenient for the merchant to recognize.\n\nExample: Front Counter Terminal\n", "example": "Front Counter Terminal" }, "type": { "type": "string", "nullable": true, "description": "Indicates the description of the source.\n\nThis is a free-formed type name that is convenient for the merchant to recognize.\n\nExample: Terminal\n", "example": "Terminal" }, "id": { "type": "string", "format": "uuid", "nullable": true, "description": "Indicates an identifier specifying the instance of the source.\n\nExample: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03\n", "example": "5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03" }, "typeId": { "type": "integer", "format": "int32", "nullable": true, "description": "Reserved for internal use only.\n\nDo not use.\n" }, "version": { "type": "string", "nullable": true, "x-method": "request", "description": "Indicates the version.\n\nExample: 1.4.2\n", "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.\n\nExample: 99.99\n", "example": 99.99 }, "percentageOffAmount": { "type": "number", "format": "double", "description": "Specifies the discount amount (in USD) taken off.\n\nThis discount was calculated using the preset percentage from `percentageOffRate`.\n\nExample: 12.50\n", "example": 12.5 }, "percentageOffRate": { "type": "number", "format": "double", "description": "Identifies the discount percentage.\n\nThis value is percentage rate for the discount.\nThis discount percentage calculates the discount amount for `percentageOffAmount`.\n\nExample: 3.5 (as 3.5%)\n", "example": 3.5 }, "cashDiscountAmount": { "type": "number", "format": "double", "description": "Identifies the cash discount amount (in USD) taken off.\n\nExample: 12.50 (for $12.50)\n", "example": 12.5 }, "cashDiscountRate": { "type": "number", "format": "double", "description": "Identifies the discount percentage for a cash (or cash-equivalent) discount.\n\nExample: 1.5 (for 1.5%)\n", "example": 1.5 }, "surchargeAmount": { "type": "number", "format": "double", "x-method": "request", "description": "Specifies the surcharge amount (in USD) applied.\n\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n\nExample: 22 (for $22)\n", "example": 22 }, "surchargeRate": { "type": "number", "format": "double", "description": "Indicates the percent of transaction surcharge amount.\n\nThis value is added to the base amount after `PercentageOffRate` has been applied.\n\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n\nExample: 2.5 (for 2.5%)\n", "example": 2.5 }, "tipAmount": { "type": "number", "multipleOf": 0.01, "format": "double", "description": "Indicates the absolute amount (in USD) of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "description": "Indicates a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "example": 18.5 }, "taxAmount": { "type": "number", "format": "double", "x-method": "response", "nullable": true, "description": "Indicates the tax amount established on a product.\n\nExample: 3.75 (for 3.75%)\n", "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.\n\nExamples:
\n5.0 (for 5.0%)
\n8.5 (for 8.5%)
\n10.25 (for 10.25%)\n", "example": 8.5 }, "totalAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "request", "description": "Indicates the final total amount (in USD).\n\nExample: 124.99\n", "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).\n\nExample: USD\n", "example": "USD" }, "paymentprocessorid": { "type": "string", "format": "uuid", "nullable": true, "x-method": "request/response", "description": "Identifies the payment processor.\n\nExample: 76215e54-a85b-4d42-9553-163fe393cb02\n", "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.\n\nValid values are:\n\n| Type | Explanation |\n|--------------------|----------------------------------------------|\n| AchCancel | Cancels a pending ACH transaction. |\n| AchCredit | Sends funds to a bank account. |\n| AchDebit | Pulls funds from a bank account. |\n| AchHold | Holds an ACH transaction temporarily. |\n| AchRefund | Returns funds from an ACH payment. |\n| AchUnHold | Releases a held ACH transaction. |\n| Authorization | Reserves funds for later capture. |\n| Capture | Collects funds from an authorization. |\n| CardAuthentication | Confirms cardholder identity before payment. |\n| Refund | Returns funds from a transaction. |\n| RefundWORef | Refunds a transaction without a reference. |\n| Sale | Authorizes and captures funds together. |\n| Settle | Submits a batch for final processing. |\n| TipAdjustment | Changes the tip amount on a transaction. |\n| Void | Cancels a transaction before settlement. |\n\nExample: AchDebit\n", "example": "AchDebit" }, "TransactionReceiptDtoTransactionReceiptSourceResponseDto": { "type": "object", "description": "Indicates an object describing the source of the transaction.\n", "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true, "description": "Indicates the name of that specific instance.\n\nThis is a free-formed type name that is convenient for the merchant to recognize.\n\nExample: Front Counter Terminal\n", "example": "Front Counter Terminal" }, "type": { "type": "string", "nullable": true, "description": "Indicates the description of the source.\n\nThis is a free-formed type name that is convenient for the merchant to recognize.\n\nExample: Terminal\n", "example": "Terminal" }, "id": { "type": "string", "format": "uuid", "nullable": true, "description": "Indicates an identifier specifying the instance of the source.\n\nExample: 5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03\n", "example": "5e6e2ad1-8c9d-4e0f-1a2b-3c4d5e6f7a03" }, "typeId": { "type": "integer", "format": "int32", "nullable": true, "description": "Reserved for internal use only.\n\nDo not use.\n" } } }, "CardholderAuthenticationMethodDto": { "type": "string", "enum": [ "NotAuthenticated", "PIN", "ElectronicSignatureAnalysis", "ManualSignature", "ManualOther", "Unknown", "SystematicOther", "ETicketEnvAmex", "OfflinePin" ], "description": "Indicates the method the cardholder was authenticated with.\n\nValid values are:\n\n| Item | Explanation |\n|------------------------------|----------------------------------------------------|\n| ElectronicSignatureAnalysis | Electronic signature captured and analyzed. |\n| ETicketEnvAmex | E-ticket environment specific to American Express. |\n| ManualOther | Other manual verification method. |\n| ManualSignature | Paper or screen signature obtained. |\n| NotAuthenticated | No cardholder verification performed. |\n| OfflinePin | Offline PIN verified by card chip, no network. |\n| PIN | Online PIN verified by issuer. |\n| SystematicOther | Systematic or automated method not listed. |\n| Unknown | Verification method is unknown. |\n\nExample: PIN\n", "example": "PIN" }, "CardDataSourceDto": { "type": "string", "enum": [ "Internet", "Swipe", "NFC", "EMV", "EMVContactless", "FallbackSwipe", "Manual" ], "description": "Indicates the source of the card (credit or debit).\n\nValid values are:\n\n| Item | Explanation |\n|----------------|------------------------------------------------|\n| EMV | Chip read using EMV tags. |\n| EMVContactless | Tap chip read using EMV tags. |\n| FallbackSwipe | Swipe used after failed chip read. |\n| Internet | Virtual terminal or API entry. |\n| Manual | Card present, keyed entry. |\n| NFC | Contactless tap using EMV tags and track data. |\n| Swipe | Magnetic stripe track data read. |\n\nExample: Swipe\n", "example": "Swipe" }, "TransactionReceiptDtoCardDetailsDto": { "type": "object", "additionalProperties": false, "properties": { "authCode": { "type": "string", "nullable": true, "description": "Indicates the authorization code from the card processor.\n\nThis authorization does not apply to tip adjustments.\nThe code explicitly falls back to the original.\n\nExample: ABC123\n", "example": "ABC123" }, "mid": { "type": "string", "nullable": true, "description": "Indicates the MID (merchant identifier).\n\nThis is an identifier the acquirer or processor assigns to a specific merchant account. \n\nExample: 700123456789\n", "example": "700123456789" }, "tid": { "type": "string", "nullable": true, "description": "Indicates the TID (terminal identifier).\n\nThis is an identifier of the specific physical terminal or device used in the transaction.\n\nExample: 00012345\n", "example": "00012345" }, "rrn": { "type": "string", "nullable": true, "description": "Indicates the RRN (retrieval reference number).\n\nThis is a card-network, such as for Visa or Mastercard, reference number assigned to every card transaction.\nIt is used to trace or retrieve the transaction later, such as for chargebacks or disputes.\n\nExample: 625031412345\n", "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.\n\nThis displays only the last four numbers.\n\nExample: 4111111111111111\n", "example": "4111111111111111" }, "customerRoutingNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the ACH routing number.\n\nExample: 867320021\n", "example": "867320021" }, "accountHolderType": { "$ref": "#/components/schemas/AccountHolderType" }, "accountType": { "$ref": "#/components/schemas/AccountType" }, "taxId": { "type": "string", "nullable": true, "description": "Specifies the tax identifier.\n\nExample: 12-3456789\n", "example": "12-3456789" } } }, "SuggestedTipsDto": { "type": "object", "properties": { "tipPercent": { "type": "number", "format": "double", "description": "Indicates a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "example": 18.5 }, "tipAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "description": "Indicates the absolute amount (in USD) of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "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.\n\nSee the field `type`.\n\nExample: 49.99 (for $49.99)\n", "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.\n\nValid values are:\n\n| Status | Explanation |\n|--------|---------------------------------------|\n| Allow | If address verification passes, the payment proceeds. |\n| Deny | If address verification does not pass, the payment is denied. |\n\nExample: Allow\n", "example": "Allow" }, "AvsCodeGroupTypeDto": { "enum": [ "NoMatch", "PartialMatch", "Incompatible", "Unavailable", "ValidGroup" ], "type": "string", "description": "Indicates the AVS (address verification service) group type.\n\nValid values are:\n\n| Status | Explanation |\n|---------------|------------------------------------------------------|\n| Incompatible | The card issuer does not support this address check. |\n| NoMatch | The billing address and postal code did not match. |\n| PartialMatch | One part of the billing address matched, not both. |\n| Unavailable | The address check result was not available. |\n| ValidGroup | The billing address and postal code matched. |\n" }, "AvsResponseResultDto": { "enum": [ "Passed", "Failed" ], "type": "string", "description": "Indicates the AVS (address verification service) result.\n\nValid values are:\n\n| Status | Explanation |\n|--------|---------------------------|\n| Failed | The address check failed. |\n| Passed | The address check passed. |\n" }, "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.\n\nFor a simplified explanation of the result, see the field `codeDescription`.\n\nExample: Y\n", "example": "Y" }, "codeDescription": { "type": "string", "nullable": true, "description": "Indicates a simplified explanation of the result.\n\nFor the actual AVS (address verification service) result, see the field `responseCode`.\n\nExample: Address and ZIP code match\n", "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.\n\nExample: ac\n", "example": "ac" }, "value": { "type": "string", "nullable": true, "description": "Indicates the value of the pair.\n\nExample: 9F26\n", "example": "9F26" } }, "additionalProperties": false }, "TransactionReceiptDtoEmvTagsDto": { "type": "object", "additionalProperties": false, "properties": { "ac": { "type": "string", "nullable": true, "description": "Indicates the AC (application cryptogram).\n\nThis is the cryptographic value generated by the card chip so the issuer can authenticate the transaction.\n\nExample: A123456789ABCDEF\n", "example": "A123456789ABCDEF" }, "tvr": { "type": "string", "nullable": true, "description": "Indicates the TVR (terminal verification results).\n\nThis is a bitmask showing which checks the terminal ran and the success status of each one.\nThe individual checks include data authentication, cardholder verification, and risk management.\n\nExample: 0000008000\n", "example": "0000008000" }, "tsi": { "type": "string", "nullable": true, "description": "Indicates the TSI (transaction status information).\n\nThis is a bitmask showing which processes were actually performed during the transaction.\n\nExample: E800\n", "example": "E800" }, "aid": { "type": "string", "nullable": true, "description": "Indicates the AID (application identifier).\n\nThis identifies the specific card payment application on the chip, such as Visa Credit or Mastercard Debit.\n\nExample: A0000000031010\n", "example": "A0000000031010" }, "applicationLabel": { "type": "string", "nullable": true, "description": "Indicates the application Label.\n\nThis is the human-readable name of that application, often shown on the terminal display.\n\nExample: VISA CREDIT\n", "example": "VISA CREDIT" }, "rawTags": { "description": "Indicates the EMV chip transaction data elements, or tags. \n\nEach data element is identified by its own hex tag number according to the EMV specifications.\nFor example, the five most commonly needed ones are: ac (9F26), tvr (95), tsi (9B), aid (4F), and applicationLabel (50).\nAn actual EMV transaction can return many more tags than that, sometimes with dozens of possible values.\n\nThis tag array object contains all the returned pairings.\n", "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.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nExample: 2026-05-05T14:30:42.938Z\n", "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.\n\nExample: TSYS\n", "example": "TSYS" }, "operationTypeId": { "type": "integer", "format": "int32", "description": "For internal use only.\n\nDo not use.\n" }, "operationType": { "type": "string", "default": "PayNow", "enum": [ "PayNow", "Subscription" ], "description": "Identifies the type of the operation.\n\nValid values are:\n\n| Item | Explanation |\n|--------------|---------------------------------------|\n| PayNow | One-time charge for a service. |\n| Subscription | Recurring charge for ongoing service. |\n\nExample: PayNow\n", "example": "PayNow" }, "paymentMethodTypeId": { "type": "integer", "format": "int32", "description": "For internal use only.\n\nDo not use.\n" }, "paymentMethodType": { "$ref": "#/components/schemas/PaymentMethodType" }, "transactionTypeId": { "type": "integer", "format": "int32", "description": "For internal use only.\n\nDo not use.\n" }, "transactionType": { "$ref": "#/components/schemas/TransactionType" }, "customerId": { "$ref": "#/components/schemas/customerId" }, "customerPan": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked card number.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "example": "************1111" }, "cardTokenType": { "$ref": "#/components/schemas/TokenType" }, "statusId": { "type": "integer", "format": "int32", "description": "For internal use only.\n\nDo not use.\n" }, "status": { "type": "string", "nullable": true, "enum": [ "Cancelled", "Completed", "Created", "Failed" ], "description": "Indicates the status of the transaction.\n\nValid values are:\n\n| Status | Explanation |\n|-----------|-------------------------------------------------------------------------|\n| Cancelled | The transaction was cancelled before completion. |\n| 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. |\n| Created | The transaction was initialized but not yet processed. |\n| Failed | The payment was attempted but did not succeed. A new session is needed. |\n\nExample: Completed\n", "example": "Completed" }, "merchantName": { "type": "string", "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "merchantAddress": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the customer's company address.\n\nExample: 123 Main St, Suite 100, New York\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "merchantEmailAddress": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the customer's email.\n\nExample: peppared@example.com\n", "example": "peppared@example.com" }, "merchantWebsite": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the customer's URL.\n\nExample: PepparedStreetCafe.example.com\n", "example": "PepparedStreetCafe.example.com" }, "authCode": { "type": "string", "nullable": true, "description": "Indicates the authorization code from the card processor.\n\nThis authorization does not apply to tip adjustments.\nThe code explicitly falls back to the original.\n\nExample: ABC123\n", "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.\n\nIt also indicates whether the verification succeeded or failed.\n\nExamples:
\nCVM Failed
\nSignature Verified\n", "example": "Signature Verified" }, "cardDataSourceId": { "type": "string", "description": "For internal use only.\n\nDo not use.\n" }, "cardDataSource": { "$ref": "#/components/schemas/CardDataSourceDto" }, "responseCode": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the response code from processor.\n\nExamples:
\n00
\n051\n", "example": "00" }, "responseDescription": { "type": "string", "nullable": true, "description": "Indicates a human-readable message that explains the response and response code.\n\nExamples:
\nApproved or completed successfully
\nDeclined - Do Not Honor\n", "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.\n\nExample: ORD-4521\n", "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.\n \nExamples:
\n125
\n125.5
\n125.50\n", "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.\n\nThis discount was calculated using the preset percentage from `percentageOffRate`.\n\nExample: 12.50\n", "example": 12.5 }, "percentageOffRate": { "type": "number", "format": "double", "description": "Identifies the discount percentage.\n\nThis value is percentage rate for the discount.\nThis discount percentage calculates the discount amount for `percentageOffAmount`.\n\nExample: 3.5 (as 3.5%)\n", "example": 3.5 }, "cashDiscountAmount": { "type": "number", "format": "double", "description": "Identifies the cash discount amount (in USD) taken off.\n\nExample: 12.50 (for $12.50)\n", "example": 12.5 }, "cashDiscountRate": { "type": "number", "format": "double", "description": "Identifies the discount percentage for a cash (or cash-equivalent) discount.\n\nExample: 1.5 (for 1.5%)\n", "example": 1.5 }, "surchargeAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Specifies the surcharge amount (in USD) applied.\n\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n\nExample: 22 (for $22)\n", "example": 22 }, "surchargeRate": { "type": "number", "format": "double", "description": "Indicates the percent of transaction amount.\n\nThis value is added to the base amount after `PercentageOffRate` has been applied.\n\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n\nExample: 2.5 (for 2.5%)\n", "example": 2.5 }, "tipAmount": { "type": "number", "multipleOf": 0.01, "format": "double", "description": "Indicates the absolute amount (in USD) of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "description": "Indicates a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "example": 18.5 }, "taxAmount": { "type": "number", "format": "double", "x-method": "request/response", "nullable": true, "description": "Indicates the tax amount established on a product.\n\nExample: 3.75 (for 3.75%)\n", "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.\n\nExamples:
\n5.0 (for 5.0%)
\n8.5 (for 8.5%)
\n10.25 (for 10.25%)\n", "example": 8.5 }, "totalAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "request", "description": "Indicates the final total amount (in USD).\n\nExample: 124.99\n", "example": 124.99 } } }, "GetPaymentSessionTransactionDetailsDto": { "type": "object", "properties": { "transactionReceiptUrl": { "type": "string", "nullable": true, "description": "Indicates the direct URL link to the transaction receipt.\n\nExample: https://receipts.flute.com/r/90d084d6-55b8-4fb8-b658-861534d07f9a\n", "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.\n\nExample: \"https://s.flute.com/745iZYxF83t\"\n", "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.\n\nThis is the identifier of a previously saved ACH account to charge.\n\nExample: 39a95e35-6d50-45ec-884b-c2417edf005d\n", "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.\n\nExample: 2025-02-19T20:24:52.934Z\n", "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.\n\nExample: Alexandro Peppared\n", "example": "Alexandro Peppared" }, "merchant": { "type": "string", "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "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.\n\nExample: TSYS\n", "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.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Cafe Peppared Payments\n", "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.\n\nExample: Alexandro Peppared\n", "example": "Alexandro Peppared" }, "customerCompany": { "type": "string", "nullable": true, "description": "Indicates the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe" }, "customerPan": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked card number.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "example": "************1111" }, "customerEmail": { "type": "string", "nullable": true, "description": "Indicates the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nValid values:\n\n| Status | Description |\n|-----------| ------------|\n| Created | Payment session was initialized but not yet processed. |\n| Completed | Payment session was completed. Check transaction details to verify if the payment was approved or not. |\n| Cancelled | Payment session was cancelled before completion. |\n| Expired | Payment session expired before being completed. |\n| Failed | Payment was attempted but did not succeed. A new session must be created for a new payment attempt. |\n\nExample: Created\n", "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.\n\nThis value is applicable only to `Payment` and `PaymentAndSave` from `mode`.\n\nIf `true`, bypasses AVS in the payment gateway.
\nIf `false`, does not bypass AVS in the payment gateway.\n\nExample: true\n", "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.\n\nExample: 990a65f4-519c-44f9-a615-fc9c7781190c\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "checkoutUrl": { "type": "string", "nullable": true, "description": "Indicates full URL of the hosted checkout page for this payment session.\n\nExample: https://api.payments.flute.com/xOut/sessions/session-complete.html\n", "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.\n\nExample: https://smallurl.com/4kxm9p2\n", "example": "https://smallurl.com/4kxm9p2" }, "successUrl": { "type": "string", "nullable": true, "description": "Indicates the URL to redirect the payer to after a successful payment.\n\nThis value is not needed if using Flute Elements and Flute Checkout.\n\nExample: https://api.payments.flute.com/xOut/sessions/session-complete.html\n", "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.\n\nValid values are:\n\n| Payment method | Type |\n|----------------|------|\n| Card | Credit or debit card payment |\n| ACH | ACH (automated clearing house) payment |\n\nExample: Card\n", "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.\n\nThese values are used to store supplemental information.\nThey are not functionally used in this endpoint.\nInstead, they are included while retrieving the payment session.\nThis allows additional notes to be passed along to the operator.\n\nPass null to clear all metadata.\n\nExamples:
\n[ {\"orderId\": \"9921\"} ]
\n[ {\"Guest notes\": \"Member of The World of Hyatt Credit Card.\"} ]
\n[{\"orderId\": \"9921\"}, {\"Guest notes\": \"Member of The World of Hyatt Credit Card.\"}]\n", "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.\n\nThis value is not needed if using Flute Elements and Flute Checkout.\n\nExample: Thank you for shopping with us.\n", "example": "Thank you for shopping with us." }, "pageName": { "type": "string", "nullable": true, "description": "Specifies the display name shown on the checkout page.\n\nThis is a free-formed name that is convenient for the merchant to recognize. \n\nExample: Peppared Street Cafe's Preferred Payment\n", "example": "Peppared Street Cafe's Preferred Payment" }, "isMultiUse": { "type": "boolean", "description": "Specifies the checkout URL can be used for multiple payments.\n\nThis value is applied only if using Flute Elements or Flute Checkout.\n\nIf `true`, the checkout URL can be used for multiple payments.
\nIf `false`, the checkout URL cannot be used for multiple payments.\n\nExample: true\n", "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.\n\nThe time must be in the future.\n\nExample: 2026-02-19T20:24:52.934Z\n", "example": "2026-02-19T20:24:52.934Z" }, "paymentNotes": { "type": "string", "nullable": true, "description": "Specifies additional notes shown to the payer on the checkout page.\n\nExample: The client's server is being repaired.\n", "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.\n\nExample: 84\n", "example": "84" }, "achRoutingLast2": { "type": "string", "nullable": true, "description": "Indicates the last two digits of an ACH (automated clearing house) bank routing number.\n\nExample: 62\n", "example": "62" }, "surchargeAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Specifies the surcharge amount (in USD) applied.\n\nExample: 18.45 (for $18.45)\n", "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.\n\nExample: POS-DEVICE-001\n", "example": "POS-DEVICE-001" }, "PosTransactionStatus": { "enum": [ "Cancelled", "Completed", "Failed", "InProgress" ], "type": "string", "x-method": "response", "description": "Indicates the status of the transaction.\n\nValid values are:\n| Value | Description |\n| ----------- | ---------------------------------------------------------- |\n| Cancelled | The POS transaction was canceled before it completed. |\n| Completed | The POS transaction finished processing successfully. |\n| Failed | The POS transaction did not complete because of an error. |\n| InProgress | The POS transaction is still being processed. |\n\nExample: Completed\n", "example": "Completed" }, "CaptureMethod": { "enum": [ "Auto", "Manual" ], "type": "string", "x-method": "request/response", "description": "Identifies the capture method.\n\nCapture is the step that converts an authorization, funds reserved before a transaction, into an actual charge or funds captured for settlement.\n\nPossible values:\n\n| Value | Description |\n|--------|-------------|\n| Auto | The transaction is captured automatically at the same time as authorization or immediately after, with no separate action required. |\n| Manual | The transaction has been authorized. However, an explicit capture request must be made later to actually allocate the money.

Care must be taken because if the transaction is never captured, the authorization simply expires and no funds move. |\n\nExample: Auto\n", "example": "Auto" }, "processedAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "response", "nullable": true, "description": "Indicates the transaction amount (in USD).\n\nThe value will be null until the transaction is completed.\n\nExample: 87.39\n", "example": 87.39 }, "ExtraAmountsDto": { "type": "object", "description": "Identifies the extra amounts for the transaction.\n\nTo accept tips, the merchant is required to have tips enabled and tip-adjustment disabled.\nIf tip collection is enabled and committed at creation time, the tip gets prompted to the customer directly on the device.\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\nIf 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.\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "request/response", "description": "Identifies a tip percentage to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first.\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 25 (for $25)\n", "example": 25 }, "discountRate": { "type": "number", "format": "double", "x-method": "response", "description": "Identifies a percentage of a discount to be applied.\n\nIf this value is provided, it must be greater than zero.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 5.5 (for 5.5%)\n", "example": 5.5 }, "surchargeRate": { "type": "number", "format": "double", "description": "Identifies the percent of transaction amount.\n\nExample: 2.5 (for 2.5%)\n", "example": 2.5 } }, "additionalProperties": false }, "ListPosTransactionsResponseDto": { "type": "object", "properties": { "posTransactionId": { "type": "string", "format": "uuid", "x-method": "response", "description": "Indicates the POS transaction identifier.\n\nExample: 8be0aa51-eae6-4c30-a558-8579f3832f98\n", "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.\n\nExample: 2026-01-15T10:30:56.264Z\n", "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.\n\nExample: d0fc1606-47ea-464b-a31a-3971c9822d10\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nThis value is available after processing.\n\nExample: a62fa6a1-8a2a-44f9-983d-c757017d4b66\n", "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.\n\nThis value is only relevant when Dual Pricing is enabled.\n\nValid values are:\n\n| Status | Explanation |\n|--------|-------------------------------------------------------------------------|\n| Card | The transaction uses the card price, which may include a surcharge. |\n| Cash | The transaction uses the cash price, which may include a cash discount. |\n\nExample: Card\n", "example": "Card" }, "PosTransactionReadingMethod": { "enum": [ "KeyedEntry", "Regular" ], "type": "string", "description": "Specifies the POS terminal reading type.\n\nValid Values are:\n\n| Method | Explanation |\n|------------|-------------------------------------------|\n| KeyedEntry | Card details are entered manually on the terminal. |\n| Regular | Card details are read by the device, such as by tap, insert, or swipe. |\n\nExample: Regular\n", "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.\n\nExample: POS-DEVICE-001\n", "example": "POS-DEVICE-001" }, "baseAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "request", "nullable": true, "description": "Specifies the transaction amount (in USD).\n\n\nRequired when the `TransactionType` is any of the following:\n\n| Transaction Type | Notes |\n|------------------|-------|\n| Authorization | |\n| Capture | |\n| Refund | |\n| RefundWORef | Refund without reference |\n| Sale | |\n| TipAdjustment | |\n\n\n\nExamples:
\n125
\n125.5
\n125.50\n", "example": 125.5 }, "currencyCode": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the transaction's currency code (in ISO 4217 currency code).\n\n\nRequired when the TransactionType is any of the following:\n\n| Transaction Type | Description |\n|------------------|---|\n| Authorization | |\n| Capture | |\n| Refund | |\n| RefundWORef | Refund without reference |\n| Sale | |\n| TipAdjustment | |\n\n \n\nExample: USD\n", "example": "USD" }, "terminalId": { "type": "string", "format": "uuid", "x-method": "request", "description": "Specifies the terminal identifier that handles the transaction.\n\nThe terminal must be in semi-integrated mode and available (online and ready).\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nExample: 0dfac966-9dbd-4608-a65f-d6a4c961dd35\n", "example": "0dfac966-9dbd-4608-a65f-d6a4c961dd35" }, "waitForAcceptanceByTerminal": { "type": "boolean", "x-method": "request", "description": "Specifies the response mode is either short or long polling.\n\nIf `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).
\nIf `false`, specifies short polling. HTTP response will be returned immediately, while the terminal is still receiving the transaction request.\n\nAfter either case, use `GET /v2/pos/transactions/{{posTransactionId}}` to retrieve the latest information of the transaction submission.\n\nPolling refers to how the POS application checks Flute for the status or result of a payment after initiating it.\nThe choice is mainly about how quickly the final transaction status is needed and how much repeated traffic can be tolerated.\n\n**Short polling**
\nThe POS application repeatedly sends separate status requests at short intervals.\nThis checks for the completion status of the transaction.\nEach request gets an immediate response, and the POS application keeps asking until the transaction reaches a final state or times out.\nShort polling is useful when the POS application can itself periodically check status instead of maintaining an open request.\nExamples include checking whether an earlier transaction eventually completed, recovering after a connection interruption, or reconciling a transaction whose final state is uncertain.\n\n**Long polling**
\nThe POS application sends a status request, and Flute holds that request open while waiting for the transaction state to change.\nOnce there’s a result or the request times out, Flute responds.\nThe POS application can then open another long-poll request if necessary.\nLong polling is useful when the POS application is actively waiting for a transaction to complete.\nFor example, the customer has tapped their card and the POS application is waiting to show whether the payment was approved or declined.\nThe request stays open until there’s a status change or timeout, so customers get a quick result without the application constantly making new requests.\n\nExample: true\n", "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.\n\nIf `true`, display a message confirming saving the customer payment method.
\nIf `false`, does not display a message confirming saving the customer payment method.\n\nExample: true\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nValid values are:\n\n| Status | Description |\n|-----------------------|------------------------------------------------------|\n| Authorized | Payment approved but funds not yet captured. |\n| Cancelled | Transaction stopped before it completed. |\n| Captured | Approved funds collected from the card. |\n| ChargedBack | Cardholder disputed the charge with their bank. |\n| Cleared | Funds finished processing and settled. |\n| Declined | Payment rejected by the bank or processor. |\n| Failed | Transaction could not complete due to an error. |\n| Held | Transaction paused and awaiting release. |\n| HeldByProcessor | Processor paused the transaction for review. |\n| Informational | Record used for reference only, not a live charge. |\n| InProgress | Transaction is still processing. |\n| PartiallyAuthorized | Only part of the requested amount was approved. |\n| Pending | Transaction is waiting for a result. |\n| Refunded | Funds returned to the cardholder. |\n| Scheduled | Transaction set to run at a future time. |\n| Settled | Funds moved from issuer to the merchant account. |\n| Verified | Card or account confirmed as valid. |\n| Voided | Authorization cancelled before capture. |\n\nExample: Authorized\n", "example": "Authorized" }, "TransactionDetailEventType": { "enum": [ "Authorization", "Sale", "Capture", "Void", "Refund", "TipAdjustment", "CardAuthentication", "Hold", "UnHold", "Credit", "Settle" ], "type": "string", "description": "Indicates the possible event types.\n\nValid values are:\n| Type | Description |\n|--------------------|----------------------------------------------------|\n| Authorization | Authorizes the transaction. |\n| Capture | Collects funds from an approved authorization. |\n| CardAuthentication | Confirms cardholder identity before payment. |\n| Credit | Sends funds back to a cardholder outside a refund. |\n| Hold | Pauses a transaction or account temporarily. |\n| Refund | Returns funds for a completed sale. |\n| Sale | Authorizes and captures payment in one step. |\n| Settle | Submits a batch for final processing. |\n| TipAdjustment | Adds or changes a tip after the sale. |\n| UnHold | Removes a hold and resumes normal activity. |\n| Void | Cancels a transaction before it settles. |\n\nExample: Capture\n", "example": "Capture" }, "referenceId": { "type": "string", "x-method": "response", "nullable": true, "minLength": 0, "maxLength": 36, "description": "Indicates a reference identifier provided by the merchant.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "example": "REF-EXT-12345" }, "originalTransactionId": { "type": "string", "format": "uuid", "x-method": "response", "description": "Indicates the original transaction identifier.\n\nThis value will be provided if the current transaction is a card refund.
\nOtherwise, it will be null or omitted.\n\nExample: 4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92\n", "example": "4d5d19c0-7b8c-4d9e-0f1a-2b3c4d5e6f92" }, "AchSECCode": { "enum": [ "Web", "PPD", "CCD" ], "type": "string", "description": "Indicates the ACH SEC (standard entry class) code.\n\nValid values are:\n\n| Code | Description |\n|-----------|------------------------------------------------------|\n| CCD | Used for business to business payments. |\n| PPD | Used for consumer payments like payroll or bill pay. |\n| Web | Used for a payment authorized on a website. |\n\nExample: CCD\n", "example": "CCD" }, "processorDetails": { "type": "object", "properties": { "mid": { "type": "string", "nullable": true, "description": "Indicates the MID (merchant identifier) assigned by the processor.\n\nExample: 932129304958123\n", "example": 932129304958123 }, "tid": { "type": "string", "nullable": true, "description": "Indicates the TID (terminal identifier) assigned by the processor.\n\nexample: 6095275263\n", "example": 6095275263 }, "authCode": { "type": "string", "nullable": true, "description": "Indicates the authorization code returned by the processor.\n\nExample: VTLMC1\n", "example": "VTLMC1" }, "rrn": { "type": "string", "nullable": true, "description": "Indicates the RRN (retrieval reference number) returned by the processor.\n\nExample: 59d5df1aa58d4de3969175eeece571c1\n", "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.\n\nExample: A\n", "example": "Y" }, "description": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the description of the AVS (address verification service) result code description.\n\nExample: Address and ZIP match\n", "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.\n\nValid values are:\n\n| Status | Description |\n|-----------|-----------------------------------------|\n| Approved | Payment passed checks. Funds will move. |\n| Declined | Bank or card issuer rejected payment. |\n| Failed | Payment attempt ended in error. |\n| Pending | Payment is waiting for a result. |\n\nExample: Approved\n", "example": "Approved" }, "linkedTransaction": { "type": "object", "description": "Indicates an object detailing the related POS transaction.\n\nThis value will be null until the transaction is completed.\n", "properties": { "transactionId": { "type": "string", "format": "uuid", "x-method": "response", "nullable": true, "description": "Indicates the attached transaction identifier.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nExample: 2026-05-05T14:30:42.938Z\n", "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.\n\nExamples:
\n56.99
\n0\n", "example": 0 }, "availableRefundAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "description": "Indicates the amount (in USD) still refundable.\n\nExample: 120.99\n", "example": 120.99 }, "isFullyRefunded": { "type": "boolean", "description": "Indicates the amount has been fully refunded.\n\nIf `true`, the amount has been fully refunded.
\nIf `false`, the amount has not been fully refunded.\n\nExample: true\n", "example": true } }, "additionalProperties": false, "description": "Indicates an object detailing the refund posture for a transaction that can be refunded.\n\nThis value is null on transactions that are themselves refunds or credits.\nThose cannot be refunded again.\n" }, "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.\n\nExample: 42df0a13-4bf4-48f8-929c-08a379c0a0d6\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "example": 18.5 }, "surchargeAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "response", "description": "Indicates the surcharge amount (in USD) applied.\n\n
\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 22 (for $22)\n", "example": 22 }, "surchargeRate": { "type": "number", "format": "double", "description": "Indicates the percent of transaction amount.\n\nThis value is added to the base amount after `PercentageOffRate` has been applied.\n\n
\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 2.5 (for 2.5%)\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis does not include ZCP (zero cost processing) cash-discount amounts.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 25 (for $25)\n", "example": 25 }, "discountRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates a percentage of a discount to be applied.\n\nIf this value is provided, it must be greater than zero.\n\nThis does not include ZCP (zero cost processing) cash-discount amounts.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 5.5 (for 5.5%)\n", "example": 5.5 } }, "additionalProperties": false, "description": "Indicates an object detailing the amount breakdown details.\n" }, "cardDetails": { "type": "object", "description": "Indicates an object detailing card details exposed on transaction responses (masked or non-sensitive fields only).\n", "properties": { "paymentMethodId": { "$ref": "#/components/schemas/paymentMethodIdResponse" }, "maskedCardNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked card number.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "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.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "example": "************1111" }, "accountRoutingNumber": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the ACH's account routing number.\n\nExample: 021000021\n", "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.\n\nIf `true`, the transaction uses the same-day ACH processing.
\nIf `false`, the transaction does not use the same-day ACH processing.
\nIf null or omitted, the default standard ACH processing is used..\n\nExample: true\n", "example": true }, "requesterIpAddress": { "maxLength": 45, "minLength": 0, "type": "string", "x-method": "request", "description": "Specifies the IP address of the end user.\n\nValid IP address formats are:
\nIPv4
\nIPv6 format3\n\nThis end user may be the customer, operator, or application responsible for submitting the transaction.\nThis is required for audit and fraud-detection purposes.\n\nExample: 192.168.1.1\n", "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.\nThis value is null when the transaction was approved or is pending.\n", "properties": { "code": { "type": "string", "nullable": true, "description": "Indicates the decline or failure code from the processor or gateway.\n\nExample: 41\n", "example": 41 }, "message": { "type": "string", "nullable": true, "description": "Indicates a human-readable decline or failure message.\n\nExample: HOLD-CALL\n", "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.\n\nValid values are:\n| Value | Description |\n| ------------------- | ------------------------------------------------------------------------- |\n| Authorization | The transaction reserved funds for a later capture. |\n| CardAuthentication | The transaction confirmed the identity of the cardholder. |\n| Capture | The transaction collected funds from an earlier authorization. |\n| Credit | The transaction sent funds to the payment method without a prior charge. |\n| Hold | The transaction placed a temporary hold on funds. |\n| Refund | The transaction returned funds from an earlier charge. |\n| Sale | The transaction authorized and captured funds together. |\n| Settle | The transaction submitted a batch for final processing. |\n| TipAdjustment | The transaction changed the tip amount on a prior charge. |\n| UnHold | The transaction released a prior hold on funds. |\n| Void | The transaction canceled a charge before settlement. |\n\nExample: Credit\n", "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.\n\nFor payment sessions (mode of either `SaveMethod` or `PaymentAndSave`), this value must be greater than zero.\nFor vault-only payment sessions (mode of `SaveMethod`), this value must be zero.\nA value of null creates a flexible-amount payment session where the amount is set at checkout.\n\nExamples:
\n64.99
\n0
\nnull\n", "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.\n\nExample: 2026-05-05T14:30:42.938Z\n", "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.\nThis value is null when the transaction was approved or is pending.\n", "properties": { "code": { "type": "string", "nullable": true, "description": "Indicates the decline or failure code from the processor or gateway.\n\nExample: 41\n", "example": 41 }, "message": { "type": "string", "nullable": true, "description": "Indicates a human-readable decline or failure message.\n\nExample: HOLD-CALL\n", "example": "HOLD-CALL" } }, "additionalProperties": false } }, "additionalProperties": false } }, "source": { "type": "object", "description": "Indicates an object describing the origination of the transaction.\n", "properties": { "sourceType": { "enum": [ "Portal", "ApiKey", "Terminal", "Invoice", "QuickPayment", "WebComponent", "Subscription", "MobileApp", "TapToPay" ], "type": "string", "description": "Indicates the source of the transaction.\n\nValid values are:\n| Value | Description |\n| ------------- | ------------------------------------------------------------------ |\n| ApiKey | An external application created the transaction using an API key. |\n| Invoice | A billed invoice created the transaction. |\n| MobileApp | A mobile application created the transaction. |\n| Portal | A staff member created the transaction through the web portal. |\n| QuickPayment | A one-time payment link created the transaction. |\n| Subscription | A recurring subscription created the transaction. |\n| TapToPay | A mobile device using tap to pay created the transaction. |\n| Terminal | A physical payment terminal created the transaction. |\n| WebComponent | An embedded web component created the transaction. |\n\nExample: QuickPayment\n", "example": "QuickPayment" }, "sourceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Indicates the Identifier of the originating entity.\n\nExample: 3fa85f64-5717-4562-b3fc-2c963f66afa6\n", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "sourceName": { "type": "string", "nullable": true, "description": "Indicates a human-readable name of the originator.\n\nExample: API Key for ecommerce app\n", "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.\n\nExample: f77b4b4d-2f35-4cd2-8631-31318a4713a1\n", "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.\n\nExample: 2026-01-15T10:30:56.264Z\n", "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.\n\nExample: 2026-03-16T16:32:58.743Z\n", "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.\n\nThe terminal must be in semi-integrated mode and available (online and ready).\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nExample: 0dfac966-9dbd-4608-a65f-d6a4c961dd35\n", "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.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nExample: 201cc2fb-d9bd-4cc6-a254-b913f9a6b358\n", "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.\n\nExample: 2026-01-15T10:30:56.264Z\n", "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.\n\nExample: 2026-03-15T10:30:56.264Z\n", "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.\n\nExample: 9e617a7e-5a7b-415f-abbb-8df16dd2e64f\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nThe terminal must be in semi-integrated mode and available (online and ready).\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nExample: 7909bab1-5d93-4262-977d-e3f6277f58ef\n", "example": "7909bab1-5d93-4262-977d-e3f6277f58ef" } }, "additionalProperties": false }, "ZeroCostProcessingOption": { "enum": [ "None", "CashDiscount", "DualPricing", "Surcharge" ], "type": "string", "description": "Indicates the zero cost processing option.\n\nZero cost processing is a pricing strategy that the merchant passes the cost of credit card processing fees on to the customer.\nThe result is that the merchant pays little to no fees.\n\nValid values are:\n\n| Type | Meaning |\n|--------------| ------- |\n| CashDiscount | Customers paying with cash receive a discount off the posted price. |\n| DualPricing | Two prices are displayed side by side. This is a cash price and a card price. The customer chooses which to pay. |\n| None | The merchant absorbs the processing fees themselves. |\n| Surcharge | A fee is added to the transaction when a customer pays by credit card. The surcharge amount covers the processing cost. |\n\nExample: DualPricing\n", "example": "DualPricing" }, "Currency": { "enum": [ "USD" ], "type": "string", "description": "Indicates the available currency (in ISO 4217 currency code).\n\nExample: USD\n", "example": "USD" }, "PaymentProcessorType": { "enum": [ "Tsys", "Ach", "SandboxCard", "SandboxAch" ], "type": "string", "description": "Indicates the processor type.\n\nExample: SandboxCard\n", "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.\n\nExamples:
\n9
\n13
\n", "example": 9 }, "minutes": { "type": "integer", "format": "int32", "x-method": "response", "description": "Indicates the minutes of the time slot.\n\nExamples:
\n0
\n30
\n45\n" }, "timezoneName": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the timezone name (in IANA Time Zone Database format)\n\nExamples:
\nAmerica/New_York
\nEurope/London
\nAsia/Tokyo\n", "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.\n\nExample: TSYS\n", "example": "TSYS" }, "isDefault": { "type": "boolean", "x-method": "response", "description": "Indicates this payment method is the default payment method.\n\nIf `true`, this is the default payment method.
\nIf `false`, this is not the default payment method.\n\nExample: true\n", "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.\n\nValid values are:\n\n| Level | Description |\n|----------|-------------|\n| Moderate | Either the street address or ZIP code matches but not necessarily both. |\n| Strict | Both the street address and ZIP code must match exactly. |\n| Tolerant | No AVS verification is performed. The transaction is accepted regardless if the address matches. |\n\nExample: Moderate\n", "example": "Moderate" }, "PaymentConfigurationResponseDtoAddressVerificationServiceOptionsDto": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "x-method": "response", "description": "Indicates the AVS (address verification service) is enabled.\n\nIf `true`, AVS is enabled.
\nIf `false`, AVS is not enabled.\n\nExample: true\n", "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.\n\nThis is an array of percentage values that display at the time of purchase.\nThey offer preselected tip percentage suggestions as a convenience for the purchasers.\n\nExample: [ 15, 18, 20 ] (as 15%, 18%, and 20%)\n", "example": [ 15, 18, 20 ], "nullable": true }, "defaultSurchargeRate": { "type": "number", "format": "double", "x-method": "response", "nullable": true, "description": "Indicates the default surcharge rate.\n\nExamples:
\n1.5 (as 1.5%)
\n5 (as 5%)
\n22 (as 22%)\n", "example": 1.5 }, "defaultCashDiscountRate": { "type": "number", "format": "double", "x-method": "response", "nullable": true, "description": "Indicates the cash discount rate.\n\nExamples:
\n1.5 (as 1.5%)
\n5 (as 5%)
\n20 (as 20%)\n", "example": 1.5 }, "defaultDualPricingRate": { "type": "number", "format": "double", "x-method": "response", "nullable": true, "description": "Indicates the default dual pricing rate.\n\nExamples:
\n1.8 (as 1.8%)
\n5 (as 5%)
\n20 (as 20%)\n", "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).\n\nExample: USD\n", "example": [ "USD" ] }, "availableCardTypes": { "type": "array", "x-method": "response", "items": { "$ref": "#/components/schemas/CardType" }, "description": "Indicates the available card types.\n\nExample: [ \"Visa\", \"MasterCard\", \"AmericanExpress\" ]\n", "example": [ "Visa", "MasterCard", "AmericanExpress" ], "nullable": true }, "availableTransactionTypes": { "type": "array", "x-method": "response", "items": { "$ref": "#/components/schemas/TransactionType" }, "description": "Indicates the available transaction types.\n\nExample: [ \"Authorization\", \"Sale\", \"Refund\" ]\n", "example": [ "Authorization", "Sale", "Refund" ], "nullable": true }, "isTipsEnabled": { "type": "boolean", "x-method": "response", "description": "Indicates tips are enabled.\n\nIf `true`, tips are enabled.
\nIf `false`, tips are not enabled.\n\nExample: true\n", "example": true }, "availablePaymentProcessors": { "type": "array", "x-method": "response", "items": { "$ref": "#/components/schemas/PaymentConfigurationResponseDtoPaymentProcessorDto" }, "description": "Indicates the available payment processors.\n", "nullable": true }, "addressVerificationServiceOptions": { "$ref": "#/components/schemas/PaymentConfigurationResponseDtoAddressVerificationServiceOptionsDto" }, "isCustomerCardSavingByTerminalEnabled": { "type": "boolean", "x-method": "response", "description": "Indicates the terminal can save customer card after a transaction.\n\nIf `true`, the terminal can save customer card after a transaction.
\nIf `false`, the terminal cannot save customer card after a transaction.\n\nExample: true\n", "example": true }, "companyName": { "type": "string", "x-method": "response", "description": "Indicates the name of the customer's company or organization.\n\nThis is a free-formed name that is convenient for the merchant to recognize.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe", "nullable": true }, "mccCode": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the MCC (merchant category code).\n\nExample: 5411\n", "example": "5411" }, "mccCodeDescription": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the MCC (merchant category code) description.\n\nExample: Grocery Stores, Supermarkets\n", "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.\n\nExample: 10000\n", "example": 10000 }, "ttpIosTerminalProfileId": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the TTP (tap-to-pay terminal) profile identifier for iOS devices.\n\nExample: ttp-ios-profile-123\n", "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.\n\nExample: 123 Main Street\n", "example": "123 Main Street" }, "addressLine2": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates an optional second line of the address.\n\nExample: Suite 400\n", "example": "Suite 400" }, "city": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the name of the city.\n\nExample: Chicago\n", "example": "Chicago" }, "postalCode": { "type": "string", "nullable": true, "minLength": 2, "maxLength": 15, "x-method": "response", "description": "Indicates the postal or ZIP code.\n\nExample: 10001\n", "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).\n\nFor regions outside the US, use the ISO 3166-2 format.\n\nExamples:
\nTX
\nWA
\nIL\n", "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).\n\nExamples:
\nUS
\nCA
\nGB\n", "example": "US" }, "contactInfoId": { "type": "string", "format": "uuid", "x-method": "response", "description": "Indicates the contact information record identifier.\n\nExample: 91e0278b-02e8-4963-8710-fe3dfca39d51\n", "example": "91e0278b-02e8-4963-8710-fe3dfca39d51" }, "addressName": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the name or label of the address.\n\nExample: Main office\n", "example": "Main office" }, "email": { "type": "string", "x-method": "response", "nullable": true, "description": "Indicates the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "isMainAddress": { "type": "boolean", "x-method": "response", "description": "Indicates this is the main address.\n\nIf `true`, this is the main address.
\nIf `false`, this is not the main address.\n\nExample: true\n", "example": true }, "isDefaultAddress": { "type": "boolean", "x-method": "response", "description": "Indicates this is the default shipping address.\n\nIf `true`, this is the default shipping address.
\nIf `false`, this is not the default shipping address.\n\nExample: true\n", "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.\n\nExamples:
\n5.0 (for 5.0%)
\n8.5 (for 8.5%)
\n10.25 (for 10.25%)\n", "example": 8.5 } }, "additionalProperties": false }, "ProductDto": { "type": "object", "properties": { "productName": { "type": "string", "x-method": "request", "description": "Specifies the name of the product.\n\nExample: Widget\n", "nullable": true, "example": "Widget" }, "code": { "type": "string", "x-method": "request", "description": "Specifies the merchant assigned unique product identification code.\n\nThe code may only contain letters, digits, spaces, and slashes.\n\nExample: SKU/12345\n", "nullable": true, "example": "SKU/12345" }, "unitPrice": { "type": "number", "format": "double", "x-method": "request", "nullable": true, "description": "Specifies the unit price for the product.\n\nExample: 19.99\n", "example": 19.99 }, "measurementUnit": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the unit of measurement for the product.\n\nExample: EA\n", "example": "EA" }, "quantity": { "type": "number", "description": "Specifies the quantity of the product.\n\nExample: 1\n", "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.\n\nExample: 10.5 (for 10.5%)\n", "example": 10 }, "description": { "type": "string", "x-method": "request", "description": "Specifies the product description.\n\nExample: Sample cologne for conference.\n", "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.\n\nExamples:
\n2.5 (for 2.5%)
\n8.5 (for 8.5%)
\n10.25 (for 10.25%)\n", "example": 2.5 }, "dutyChargeRate": { "type": "number", "format": "double", "x-method": "request", "nullable": true, "description": "Examples:
\n2.5 (for 2.5%)
\n8.5 (for 8.5%)
\n10.25 (for 10.25%)\n", "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.\n\nExample: 42df0a13-4bf4-48f8-929c-08a379c0a0d6\n", "example": "42df0a13-4bf4-48f8-929c-08a379c0a0d6" }, "SettlementBatchStatus": { "name": "status", "in": "query", "required": false, "description": "Identifies the batch settlement type.\n\nValid values are:\n\n| Batch Type | Meaning |\n|------------|---------|\n| Open | An open batch is still active and accepting transactions. |\n| Settled | A settled batch has completed processing with the acquirer or bank. |\n\nExample: Open\n", "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.\n\nExample: TSYS\n", "nullable": true, "example": "TSYS" }, "externalBatchId": { "type": "string", "x-method": "response", "description": "Indicates the external batch identifier from the payment processor.\n\nExample: BATCH-EXT-001\n", "nullable": true, "example": "BATCH-EXT-001" }, "batchDateTime": { "type": "string", "description": "Indicates the date and time when the batch was created or processed.\n\nExample: 2026-05-05T18:00:56.264Z\n", "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.\n\nExample: 36\n", "example": 36 }, "netAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the net amount after all transactions (sales minus refunds).\n\nExample: 9500\n", "example": 9500 }, "salesAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the total amount of sales in the batch.\n\nExample: 9562.18\n", "example": 9562.18 }, "refundsAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the total amount of refunds in the batch.\n\nExample: 486.23\n", "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.\n", "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.\n" }, "ResponseCode": { "enum": [ "Approve", "Decline", "Error" ], "type": "string", "description": "Indicates the status of the batch payment submission.\n\nValid values are:\n\n| Value | Meaning |\n|---------| ------- |\n| Approve | The settlement was accepted or processed successfully. |\n| Decline | The settlement was rejected by the processor or acquirer such as by failed validation, insufficient funds, or closed account, risk or fraud rule. |\n| 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. |\n\nExample: Approve\n", "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.\n\nExample: Batch settled successfully\n", "nullable": true, "example": "Batch settled successfully" }, "processorResponseCode": { "type": "string", "x-method": "response", "description": "Indicates a response code from the payment processor.\n\nExample: 00\n", "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.\n\nValid values are:\n\n| Manufacturer |\n|--------------|\n| Sunmi |\n| Verifone |\n\nExample: Verifone\n", "example": "Verifone" }, "TerminalModel": { "enum": [ "SunmiP2", "SunmiP2LiteSe", "VerifoneVictaMobile", "VerifoneVictaPortable", "SunmiP3H" ], "type": "string", "description": "Indicates the model of the terminal.\n\nValid values are:\n\n| Model |\n|------------------------|\n| SunmiP2 |\n| SunmiP2LiteSe |\n| VerifoneVictaMobile |\n| VerifoneVictaPortable |\n| SunmiP3H |\n\nExample: SunmiP2LiteSe\n", "example": "SunmiP2LiteSe" }, "TerminalMode": { "enum": [ "Standalone", "SemiIntegrated" ], "type": "string", "description": "Indicates the operating mode of the terminal.\n\nValid values are:\n| Type | Meaning |\n|-----------------|---------|\n| 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. |\n| 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. |\n\nExample: Standalone\n", "example": "Standalone" }, "TerminalPosStatus": { "enum": [ "Active", "Busy", "Offline" ], "type": "string", "description": "Indicates the terminal status to process a new transaction.\n\nValid values are:\n\n| Status | Meaning |\n|---------|--------------------------------------------------------------------------------------------|\n| Active | The terminal is powered on and available.

It is ready to process a new transaction. |\n| Busy | The terminal is currently processing a transaction.

It is not available to accept another one until that transaction completes. |\n| Offline | The terminal is disconnected or unreachable.

It cannot process transactions until connectivity is restored. |\n\nExample: Active\n", "example": "Active" }, "TerminalConnectionStatus": { "enum": [ "Online", "Offline" ], "type": "string", "description": "Indicates the line status of the terminal.\n\nValid values are:\n\n| Status | Meaning |\n|---------|---------|\n| Online | The terminal is currently connected and reachable.

It has active network or internet connectivity. It is able to process transactions and communicate with the backend in real time. |\n| Offline | The terminal is disconnected or unreachable.

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. | \n\nExample: Online\n", "example": "Online" }, "ListTerminalsResponseDto": { "type": "object", "properties": { "terminalId": { "type": "string", "format": "uuid", "x-method": "response", "description": "Indicates the identifier of terminal handling the POS transaction.\n\nExample: d0fc1606-47ea-464b-a31a-3971c9822d10\n", "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.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe" }, "serialNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the terminal serial number.\n\nExample: SN0123456789\n", "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.\n\nExample: 2026-05-05T13:25:22.344Z\n", "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.\n\nA debit PIN key is a cryptographic key used specifically to encrypt the cardholder's PIN during a debit transaction on a payment terminal.\nWhen 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.\nThe debit PIN key is what performs that encryption.\n\nIt is typically injected into the terminal.\nThis is often as part of a DUKPT (derived unique key per transaction) scheme, or a fixed key-encryption-key setup.\n\nThe terminal can encrypt the PIN block before it's sent onward for authorization.\nIf the debitPinKey is missing, the terminal cannot securely accept PIN-debit transactions until that key is loaded.\n\nValid values are:\n\n| Status | Explanation |\n|----------|---------------------------------------------------------------------------------------------------|\n| Injected | The terminal has had its encryption or security keys loaded.

It is properly provisioned to process secure payment data. |\n| Missing | The terminal does not have its encryption or security keys loaded.

It cannot securely process payment data until keys are injected. |\n\nExample: Injected\n", "example": "Injected" }, "TerminalConnectionType": { "enum": [ "WiFi", "Mobile", "Ethernet" ], "type": "string", "description": "Indicates the connection type for the terminal.\n\nValid values are:\n\n| Type | Meaning |\n|----------|------------------------------------------------------------------------------------------------|\n| Ethernet | The terminal connects through a wired network cable.

This typically offers the most stable and reliable connection. |\n| Mobile | The terminal connects using a cellular data connection.

This is useful when Wi-Fi or Ethernet isn't available, such as in the field. |\n| WiFi | The terminal connects through a wireless local network.

This offers mobility within range of the wireless access point without a physical cable. |\n\nExample: Ethernet\n", "example": "Ethernet" }, "TerminalPrinterStatus": { "enum": [ "Normal", "NotNormal", "NotSupported" ], "type": "string", "description": "Indicates the printer status.\n\nValid values are:\n\n| Status | Meaning |\n|--------------|-------------------------------------------|\n| Normal | The device is functioning correctly. |\n| NotNormal | The device has an issue or fault. |\n| NotSupported | The device does not support this feature. |\n\nExample: Normal\n", "example": "Normal" }, "GetTerminalStatusResponseDto": { "type": "object", "properties": { "terminalId": { "type": "string", "format": "uuid", "x-method": "response", "description": "Indicates the terminal identifier that handles the transaction.\n\nThis is a mirror of the path parameter.\n\nThe terminal must be in semi-integrated mode and available (online and ready).\nA semi-integrated terminal is one that is connected to a POS system, typically through a network or cable.\n\nExample: 0dfac966-9dbd-4608-a65f-d6a4c961dd35\n", "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.\n\nExample: 2026-05-05T13:25:32.223Z\n", "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.\n\nExample: 1.4.2\n", "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.\n\nExample: 45 (as 45%)\n", "example": 45 }, "mobileConnectionStrength": { "type": "integer", "format": "int32", "x-method": "response", "minimum": 0, "maximum": 100, "description": "Indicates the mobile connection strength as a percent.\n\nExample: 87 (as 87%)\n", "example": 87 }, "batteryLevel": { "type": "integer", "format": "int32", "x-method": "response", "minimum": 0, "maximum": 100, "description": "Indicates the battery level as a percent.\n\nExample: 52 (as 52%)\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "response", "multipleOf": 0.01, "description": "Indicates a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "example": 18.5 }, "discountAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the absolute amount (in USD) of discount to be applied.\n\nIf this value is provided, it must be greater than zero.\n\nExample: 25 (for $25)\n", "example": 25 }, "discountRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates a percentage of a discount to be applied.\n\nIf this value is provided, it must be greater than zero.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 5.5 (for 5.5%)\n", "example": 5.5 }, "surchargeAmount": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the surcharge amount (in USD) applied.\n\n
\nCare must be taken that a value other than zero can be provided to either `discountAmount` or `discountRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 22 (for $22)\n", "example": 22 }, "surchargeRate": { "type": "number", "format": "double", "description": "Indicates the percent of transaction amount.\n\nThis value is added to the base amount after `PercentageOffRate` has been applied.\n\nCare must be taken that a value other than zero can be provided to either `surchargeAmount` or `surchargeRate`.\nA non-zero value cannot be provided to both.\n\nExample: 2.5 (for 2.5%)\n", "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.\n\nThese may be masked for sensitive fields or fully displayed for non-sensitive fields.\n", "properties": { "paymentMethodId": { "$ref": "#/components/schemas/paymentMethodIdResponse" }, "maskedCardNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked card number.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "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.\n\nThese may be masked for sensitive fields or fully displayed for non-sensitive fields.\n", "properties": { "paymentMethodId": { "$ref": "#/components/schemas/paymentMethodIdResponse" }, "maskedAccountNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked ACH account number.\n\nThis displays only the last four numbers.\n\nExample: **************89\n", "example": "**************89" }, "accountRoutingNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked ACH routing number.\n\nExample: 123123123\n", "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.\n\nIf `true`, the transaction uses the same-day ACH processing.
\nIf `false`, the transaction does not use the same-day ACH processing.
\nIf null or omitted, the default standard ACH processing is used.\n\nExample: true\n", "example": true } }, "additionalProperties": false }, "source": { "type": "object", "description": "Indicates an object describing the origination of the transaction.\n", "properties": { "sourceType": { "enum": [ "Portal", "ApiKey", "Terminal", "Invoice", "QuickPayment", "WebComponent", "Subscription", "MobileApp", "TapToPay" ], "type": "string", "description": "Indicates the source of the transaction.\n\nValid values are:\n| Value | Description |\n| ------------- | ------------------------------------------------------------------ |\n| ApiKey | An external application created the transaction using an API key. |\n| Invoice | A billed invoice created the transaction. |\n| MobileApp | A mobile application created the transaction. |\n| Portal | A staff member created the transaction through the web portal. |\n| QuickPayment | A one-time payment link created the transaction. |\n| Subscription | A recurring subscription created the transaction. |\n| TapToPay | A mobile device using tap to pay created the transaction. |\n| Terminal | A physical payment terminal created the transaction. |\n| WebComponent | An embedded web component created the transaction. |\n\nExample: QuickPayment\n", "example": "QuickPayment" }, "sourceId": { "type": "string", "format": "uuid", "nullable": true, "description": "Indicates the Identifier of the originating entity.\n\nExample: 3fa85f64-5717-4562-b3fc-2c963f66afa6\n", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "sourceName": { "type": "string", "nullable": true, "description": "Indicates a human-readable name of the originator.\n\nExample: API Key for ecommerce app\n", "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.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nExample: 2026-05-05T14:30:42.938Z\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nThe code may only contain letters, digits, spaces, slashes, hyphen, and commas.\n\nExample: Express Duo\n", "example": "Express Duo" }, "productDescription": { "type": "string", "minLength": 1, "maxLength": 200, "nullable": true, "x-method": "request", "description": "Specifies the description of the product.\n\nExample: Standard office supplies\n", "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.\n\nThe code may only contain letters, digits, spaces, slashes, hyphen, and commas.\n\nExample: HLA/6372\n", "example": "HLA/6372" }, "unitPrice": { "type": "number", "format": "double", "x-method": "request", "nullable": true, "description": "Specifies the product price (in USD) for each unit. \n\nExample: 3.99\n", "example": 3.99 }, "measurementUnit": { "type": "string", "minLength": 1, "maxLength": 20, "nullable": true, "x-method": "request", "description": "Specifies the unit of measurement for the product.\n\nThe code may only contain letters, digits, and spaces.\nNo special characters are allowed.\n\nExamples:
\nEA
\nLB
\nDAY\n", "example": "EA" }, "quantity": { "type": "number", "format": "double", "x-method": "request", "nullable": true, "description": "Specifies the quantity of a product.\n\nExample: 12\n", "example": 12 }, "taxAmount": { "type": "number", "format": "double", "x-method": "request", "nullable": true, "description": "Specifies the tax amount established on a product.\n\nExample: 3.75 (for 3.75%)\n", "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.\n\nExamples:
\n10 (for 10%)
\n2.5 (for 2.5%)\n", "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. \n\nExample: 8.5 (for 8.5%)\n", "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.\n\nThe code may only contain letters, digits, and spaces.\n\nExample: INV-001234\n", "example": "INV-001234" }, "purchaseOrder": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the value used by the customer to identify an order.\n\nIssued by the buyer to the seller.\n\nThe code may only contain letters, digits, and spaces.\n\nExample: PO-2026-0001\n", "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.\n\nExample: 129.99\n", "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.\n\nExample: 2.5 (for 2.5%)\n", "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.\nUsed for commercial card processing with additional transaction details.\n" }, "ContactInfoDto": { "type": "object", "properties": { "firstName": { "type": "string", "x-method": "request", "description": "Specifies the customer's first name.\n\nExample: Alexandro\n", "example": "Alexandro", "nullable": true }, "lastName": { "type": "string", "x-method": "request", "description": "Specifies the customer's last name.\n\nExample: Peppared\n", "example": "Peppared", "nullable": true }, "companyName": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the name of the customer's company or organization.\n\nExample: Peppared Street Cafe\n", "example": "Peppared Street Cafe" }, "email": { "type": "string", "x-method": "request", "nullable": true, "description": "Specifies the customer's email.\n\nExample: peppared@example.com\n", "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.\n\nExample: +14155552309\n", "example": "+14155552309" }, "hasSmsConsent": { "type": "boolean", "default": false, "x-method": "request", "description": "Specifies the customer has consented to receiving the SMS.\n\nIf `true`, the customer has consented to receiving the SMS.
\nIf `false`, the customer has not consented to receiving the SMS.\n\nExample: true\n", "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.\n\nExample: 4111111111111111\n", "example": "4111111111111111" }, "securityCode": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the securityCode (sometimes also called similarly to CCV) for the card.\n\nThis is a three or four digit security code on the credit card.\n\nExample: 483\n", "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.\n\nThis is the identifier of a previously saved ACH account to charge.\nWe recommend using `paymentMethodId` instead of `accountNumber`.\n\n
\n\nThis field is mutually exclusive with `paymentMethodDetails`.\nProvide exactly one.\n\n
\n\nWhen set, the parent request's `BillingAddress` and `ContactInfo` are optional (the stored payment method carries this data).\n\nExample: 39a95e35-6d50-45ec-884b-c2417edf005d\n", "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.\n\nThis is the identifier of a previously saved ACH account to charge.\nWe recommend using `paymentMethodId` instead of `accountNumber`.\n\n
\n\nThis field is mutually exclusive with `paymentMethodDetails`.\nProvide exactly one.\n\n
\n\nWhen set, the parent request's `BillingAddress` and `ContactInfo` are optional (the stored payment method carries this data).\n\nExample: 39a95e35-6d50-45ec-884b-c2417edf005d\n", "example": "39a95e35-6d50-45ec-884b-c2417edf005d" }, "paymentMethodDetails": { "type": "object", "description": "Specifies an object describing the payment method details.\n\n
\n\nThis field is mutually exclusive with `paymentMethodId`.\nProvide exactly one.\n\n
\n", "properties": { "accountNumber": { "$ref": "#/components/schemas/accountNumberRequest" }, "routingNumber": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the ACH's account routing number.\n\nExample: 021000021\n", "example": "021000021" }, "accountHolderType": { "$ref": "#/components/schemas/AccountHolderType" }, "accountType": { "$ref": "#/components/schemas/AccountType" }, "taxId": { "type": "string", "x-method": "request", "description": "Specifies the tax identifier.\n\nExample: 12-3456789\n", "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.\n\nIf `true`, the transaction uses the same-day ACH processing.
\nIf `false`, the transaction does not use the same-day ACH processing.
\nIf null or omitted, the default standard ACH processing is used.\n\nExample: true\n", "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.\n\nThis end user may be the customer, operator, or application responsible for submitting the transaction.\nThis is required for audit and fraud-detection purposes.\n\nExample: 192.168.1.1\n", "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.\n\n\nValid values are:\n| Item | Explanation |\n|---------|------------------------------------|\n| Android | Mobile operating system by Google. |\n| iOS | Mobile operating system by Apple. |\n\nExample: iOS\n", "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.\n\nExamples:
\n125
\n125.5
\n125.50\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "example": "REF-EXT-12345" }, "isCustomerInitiatedTransaction": { "type": "boolean", "x-method": "request", "description": "Specifies a transaction is initiated by a customer or a merchant.\n\nIf `true`, the transaction is initiated by customer.
\nIf `false`, the transaction is initiated by a merchant.\n\nExample: true\n", "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.\n\nIf included and the device has a linked user profile, the transaction is attributed to that user.
\nIf null or omitted, no attribution is made.\n\nexample: 088642a8-9082-4496-be63-8120765c5ad3\n", "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.\n\nExample: 1.4.2\n", "example": "1.4.2" }, "sdkVersion": { "type": "string", "nullable": true, "x-method": "request", "description": "Specifies the version of the SDK used to process the transaction.\n\nExample: 2.0.1\n", "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.\n\nExamples:
\n56.99
\n0\n", "example": 0 }, "availableRefundAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "description": "Indicates the amount (in USD) still refundable.\n\nExample: 120.99\n", "example": 120.99 }, "isFullyRefunded": { "type": "boolean", "description": "Indicates the amount has been fully refunded.\n\nIf `true`, the amount has been fully refunded.
\nIf `false`, the amount has not been fully refunded.\n\nExample: true\n", "example": true } }, "additionalProperties": false, "description": "Indicates an object detailing the refund posture for a transaction that can be refunded.\n\nThis value is null on transactions that are themselves refunds or credits.\nThose cannot be refunded again.\n" }, "TransactionCardDetailsDto": { "type": "object", "description": "Indicates the card details exposed on transaction responses.\n\nThese may be masked for sensitive fields or fully displayed for non-sensitive fields.\n", "properties": { "paymentMethodId": { "$ref": "#/components/schemas/paymentMethodIdResponse" }, "maskedCardNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked card number.\n\nThis displays only the last four numbers.\n\nExample: ************1111\n", "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.\n\nThese may be masked for sensitive fields or fully displayed for non-sensitive fields.\n", "properties": { "paymentMethodId": { "$ref": "#/components/schemas/paymentMethodIdResponse" }, "maskedAccountNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked ACH account number.\n\nThis displays only the last four numbers.\n\nExample: **************89\n", "example": "**************89" }, "accountRoutingNumber": { "type": "string", "nullable": true, "x-method": "response", "description": "Indicates the masked ACH routing number.\n\nExample: 123123123\n", "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.\n\nIf `true`, the transaction uses the same-day ACH processing.
\nIf `false`, the transaction does not use the same-day ACH processing.
\nIf null or omitted, the default standard ACH processing is used.\n\nExample: true\n", "example": true }, "requesterIpAddress": { "maxLength": 45, "minLength": 0, "type": "string", "x-method": "request", "description": "Indicates the IP address of the end user.\n\nValid IP address formats are:
\nIPv4
\nIPv6 format3\n\nThis end user may be the customer, operator, or application responsible for submitting the transaction.\nThis is required for audit and fraud-detection purposes.\n\nExample: 192.168.1.1\n", "example": "192.168.1.1" } }, "additionalProperties": false }, "declineDetails": { "type": "object", "description": "Indicates an object detailing a declined or failed transaction.\nThis value is null when the transaction was approved or is pending.\n", "properties": { "code": { "type": "string", "nullable": true, "description": "Indicates the decline or failure code from the processor or gateway.\n\nExample: 41\n", "example": 41 }, "message": { "type": "string", "nullable": true, "description": "Indicates a human-readable decline or failure message.\n\nExample: Do Not Honor\n", "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.\n", "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.\n\nValid values are:\n\n| Type | Description |\n|--------------------|----------------------------------------------------|\n| Authorization | Authorizes the transaction. |\n| Capture | Collects funds from an approved authorization. |\n| CardAuthentication | Confirms cardholder identity before payment. |\n| Credit | Sends funds back to a cardholder outside a refund. |\n| Hold | Pauses a transaction or account temporarily. |\n| Refund | Returns funds for a completed sale. |\n| Sale | Authorizes and captures payment in one step. |\n| Settle | Submits a batch for final processing. |\n| TipAdjustment | Adds or changes a tip after the sale. |\n| UnHold | Removes a hold and resumes normal activity. |\n| Void | Cancels a transaction before it settles. |\n\nExample: Authorization\n", "example": "Authorization" }, "transactionEventStatus": { "type": "string", "x-method": "response", "enum": [ "Pending", "Approved", "Declined", "Failed" ], "description": "Indicates the status of the event.\n\n| Value | Description |\n| --------- | --------------------------------------------------------- |\n| Approved | The processor approved the event. |\n| Declined | The processor declined the event. |\n| Failed | The event ended in an error before a processor decision. |\n| Pending | The event is waiting for a result. |\n\nExample: Approved\n", "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.\n\nExample: 2026-06-15T14:30:00Z\n", "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.\n\nExample: 120.99\n", "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.\n\nThis value is null when the event was approved or is pending.\n", "properties": { "code": { "type": "string", "nullable": true, "description": "Indicates the decline or failure code from the processor or gateway.\n\nExample: 41\n", "example": "41" }, "message": { "type": "string", "nullable": true, "description": "Indicates a human-readable decline or failure message.\n\nExample: HOLD-CALL\n", "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.\n\nThis value is available after processing.\n\nExample: f01339ec-8184-48c7-b58d-0780d6499ef4\n", "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.\n\nExample: 2026-05-05T14:30:42.938Z\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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).\n\nIf null or omitted, the full authorized amount is captured.
\nIf an amount is specified, a partial amount is captured.\n\nThis value must both:\n* Be greater than zero\n* Not exceed the remaining authorized amount.\n\nExamples:
\nnull
\n129.99\n", "example": 129.99 } }, "additionalProperties": false, "description": "Specifies an object describing the capture request.\n\nOmit amount or send empty body for full capture; set `captureAmount` for partial capture.\n" }, "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.\n\nIf a value is provided, the refund is for partial card refunds only.
\nIf null or omitted, the full transaction amount is refunded.\n\nDo not use this value for void operations and ACH refunds.\n\nExample: 50.24\n", "example": 50.24 } }, "additionalProperties": false, "description": "Request to refund, or reverse, a transaction.\n\nThe backend automatically determines whether to void or refund based on the transaction's settlement status.\n" }, "CreditDetailsDto": { "type": "object", "properties": { "cardData": { "$ref": "#/components/schemas/CardDataDto" }, "achData": { "$ref": "#/components/schemas/AchDataDto" } }, "additionalProperties": false, "description": "Specifies credit payment method details.\n\nEither `cardData` or `achData` must be provided.\n" }, "CreditRequestDto": { "type": "object", "description": "Request to create an unreferenced credit (card unreferenced refund or ACH credit).\n", "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.\n\nExample: 99.99\n", "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.\n\nThis is included in the duplicate-check key.\nIt allows the same card and amount combination to be charged multiple times when the reference identifiers are different.\n\nExample: REF-EXT-12345\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "response", "multipleOf": 0.01, "description": "Specifies a percentage of the tip to be added.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\n
\nCare must be taken that a value other than zero can be provided to either `tipAmount` or `tipRate`.\nA non-zero value cannot be provided to both.\n
\n\nExample: 18.50 (for 18.50%)\n", "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.\n\nValid values are:\n\n| Type | Description |\n|----------------|-------------------------------------------------------|\n| CashDiscount | Listed price includes a discount for cash payment. |\n| DualPricing | Displays a separate price for cash and card. |\n| None | No zero cost processing program applied. |\n| Surcharge | Adds a fee to the card price at checkout. |\n\nExample: CashDiscount\n", "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.\n\nExample: 22.5 (for $22.5)\n", "example": 22.5 }, "discountRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the discount percent applied.\n\nExample: 18.5 (for 18.5%)\n", "example": 18.5 }, "surchargeAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "response", "description": "Indicates the surcharge amount (in USD) applied.\n\nExample: 12.75 (for $12.75)\n", "example": 12.75 }, "surchargeRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the surcharge percent applied.\n\nExample: 8.25 (for 8.25%)\n", "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.\n\nIf this value is provided, it must be greater than zero.\n\nThis amount adds to the base amount of the original transaction.\nThat transaction must be authorized first (`POST /pay-api/v1/transactions/auth`).\n\nExample: 14.50 (for $14.50)\n", "example": 14.5 }, "tipRate": { "type": "number", "format": "double", "x-method": "response", "description": "Indicates the tip percent applied.\n\nExample: 15.25 (for 15.25%)\n", "example": 15.25 }, "totalAmount": { "type": "number", "format": "double", "multipleOf": 0.01, "x-method": "response", "description": "Indicates the final total amount (in USD).\n\nExample: 124.99\n", "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.\n\nValid values are:\n\n| Value | Description |\n| ------ | --------------------------------------------------- |\n| Email | The system sends the notification by email. |\n| None | The system does not send a notification. |\n| Sms | The system sends the notification by text message. |\n\nExample: Sms\n", "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.\n\nThis value is required only for SMS messages.\n\nA receipt can be sent to any phone number the customer provides at time of receipt.\n\nExample: +14155552309\n", "example": "+14155552309" }, "hasCustomerConsent": { "type": "boolean", "x-method": "request", "description": "Specifies the customer has consented to receive the SMS.\n\nIf `true`, the customer has consented to receive the SMS.
\nIf `false`, the customer has not consented to receive the SMS.\n\nExample: true\n", "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.\n\nValid values are:\n| Value | Description |\n| --------- | ------------------------------------------------ |\n| Active | The webhook endpoint is enabled and available for use. |\n| Inactive | The webhook endpoint is disabled and not available for use.

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. |\n\nExample: Active\n", "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": "
Identifies events that are subscribed to.\n\nValid values are:\n\n| Wire value | Meaning | Group | \n|-------------------------------|---|---| \n| api_key.created | An API key was created | API Keys (affiliate only) | \n| api_key.deleted | An API key was revoked or deleted | API Keys (affiliate only) | \n| invoice.created | A new invoice was created | Invoices | \n| invoice.paid | An invoice was marked as paid | Invoices | \n| merchant.created | A new merchant account was created | Merchants (affiliate only) | \n| payment_session.completed | A payment session reached a terminal state (completed, failed, or cancelled) | Payment Sessions |\n| payment_session.created | A payment session was created | Payment Sessions |\n| quick_payment.created | A quick payment link was created | Quick Payments |\n| quick_payment.paid | A quick payment link was paid | Quick Payments |\n| settlement.batch.completed | A batch settlement was processed and settled | Settlement |\n| subscription.created | A new subscription was created | Subscriptions |\n| subscription.delinquent | A subscription entered a delinquent state after repeated payment failures | Subscriptions |\n| subscription.paid | A subscription payment was successfully collected | Subscriptions |\n| subscription.payment_failed | A subscription payment attempt failed | Subscriptions |\n| terminal.added | A new terminal was registered to the account | Terminals |\n| terminal.deactivated | A terminal was deactivated on the account | Terminals |\n| terminal.out_of_paper | A terminal paper roll is empty | Terminals |\n| transaction.ach.cancelled | An ACH transaction was cancelled before processing | ACH Transactions |\n| transaction.ach.charged_back | An ACH transaction was returned or charged back | ACH Transactions |\n| transaction.ach.cleared | An ACH transaction successfully cleared | ACH Transactions |\n| transaction.ach.failed | An ACH transaction failed due to a processing error | ACH Transactions |\n| transaction.ach.held | An ACH transaction was placed on hold for review | ACH Transactions |\n| transaction.ach.in_progress | An ACH transaction was submitted to the network | ACH Transactions |\n| transaction.ach.refunded | An ACH transaction was refunded to the originator | ACH Transactions |\n| transaction.ach.scheduled | An ACH transaction was created and scheduled | ACH Transactions |\n| transaction.card.authorized | A card payment authorization was approved | Card Transactions |\n| transaction.card.captured | An authorized card payment was captured | Card Transactions |\n| transaction.card.declined | A card payment was declined by the issuer | Card Transactions |\n| transaction.card.failed | A card payment failed due to a processing error | Card Transactions |\n| transaction.card.refunded | A card payment was refunded to the cardholder | Card Transactions |\n| transaction.card.voided | A card authorization was voided before capture | Card Transactions |\n\nExamples:
\nnull
\n[ \"transaction.card.captured\" ]
\n[ \"transaction.card.captured\", \"transaction.card.authorized\" ]\n", "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.\n\nExample: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36\n", "example": "9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36" }, "endpointName": { "type": "string", "nullable": true, "maxLength": 255, "description": "Indicates the display name for the webhook.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "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.\n\nExamples: https://example.com/webhooks/pepparedstreetcafe
\n", "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.\n\nExample: 2026-05-05T14:30:36.759Z\n", "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.\n\nExample: 2026-07-10T03:22:47.918Z\n", "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.\n\nExample: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36\n", "example": "9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36" }, "endpointName": { "type": "string", "nullable": true, "x-method": "response", "maxLength": 255, "description": "Indicates the display name for the webhook.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "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.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "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.\n\nThis value is returned only on creation and is never shown again.\n" }, "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.\n\nExample: 2026-01-15T10:30:56.264Z\n", "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.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "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.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "example": "https://example.com/webhooks/pepparedstreetcafe" }, "endpointStatus": { "type": "string", "enum": [ "Active", "Inactive" ], "description": "Specifies the webhook state.\n\nValid values are:\n| Value | Description |\n| --------- | ------------------------------------------------ |\n| Active | The webhook endpoint is enabled and available for use. |\n| Inactive | The webhook endpoint is disabled and not available for use.

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.

Any delivery attempts still queued for an endpoint that becomes `Inactive` is force-terminated as `Failed` rather than retried again.

Inactive endpoints can still be pinged manually. |\n\nExample: Active\n", "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.\n\nIf `true`, the ping was delivered successfully.
\nIf `false`, the ping was not delivered successfully.\n\nExample: true\n", "example": true }, "endpointHTTPResponseCode": { "type": "integer", "format": "int32", "nullable": true, "description": "Indicates the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|--------------------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 200\n", "example": 200 }, "roundTripDurationMs": { "type": "integer", "format": "int32", "description": "Indicates the round-trip duration (in milliseconds).\n\nExample: 367\n", "example": 367 }, "errorMessage": { "type": "string", "nullable": true, "description": "Indicates an error message if the delivery failed.\n\nExample: Recipient not available\n", "example": "Recipient not available" } }, "additionalProperties": false }, "webhookdeliverylogstatus": { "type": "string", "enum": [ "Success", "Failure" ], "description": "Indicates the webhook delivery log status.\n\nValid values are:\n\n| Status | Explanation |\n|---------|-----------------------------------------------|\n| Failure | The webhook delivery attempt did not succeed. |\n| Success | The webhook delivery attempt succeeded. |\n\nExample: Success\n", "example": "Success" }, "webhookdeliverylogisvsummarydto": { "type": "object", "properties": { "deliveryLogId": { "type": "string", "format": "uuid", "description": "Indicates the webhook delivery log identifier to retrieve.\n\nExample: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25\n", "example": "89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25" }, "endpointId": { "type": "string", "format": "uuid", "description": "Indicates the webhook endpoint identifier.\n\nExample: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36\n", "example": "9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36" }, "endpointName": { "type": "string", "nullable": true, "description": "Indicates the display name for the webhook.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "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.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "example": "https://example.com/webhooks/pepparedstreetcafe" }, "eventId": { "type": "string", "format": "uuid", "description": "Indicates the event identifier.\n\nExample: 399f9d7d-0714-453c-9b6d-dda836e1d8e6\n", "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.\n\nExample: 3\n", "example": 3 }, "status": { "$ref": "#/components/schemas/webhookdeliverylogstatus" }, "endpointHTTPResponseCode": { "type": "integer", "format": "int32", "nullable": true, "description": "Indicates the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|--------------------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 200\n", "example": 200 }, "roundTripDurationMs": { "type": "integer", "format": "int32", "description": "Indicates the round-trip duration (in milliseconds).\n\nExample: 367\n", "example": 367 }, "errorMessage": { "type": "string", "nullable": true, "description": "Indicates an error message if the delivery failed.\n\nExample: Recipient not available\n", "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.\n\nExample: 2025-01-27T12:05:54.322Z\n", "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.\n\nExample: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25\n", "example": "89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25" }, "endpointId": { "type": "string", "format": "uuid", "description": "Indicates the webhook endpoint identifier.\n\nExample: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36\n", "example": "9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36" }, "endpointName": { "type": "string", "nullable": true, "description": "Indicates the display name for the webhook.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "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.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "example": "https://example.com/webhooks/pepparedstreetcafe" }, "eventId": { "type": "string", "format": "uuid", "description": "Indicates the event identifier.\n\nExample: 399f9d7d-0714-453c-9b6d-dda836e1d8e6\n", "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.\n\nExample: 3\n", "example": 3 }, "deliveryLogStatus": { "$ref": "#/components/schemas/webhookdeliverylogstatus" }, "endpointHTTPResponseCode": { "type": "integer", "format": "int32", "nullable": true, "description": "Indicates the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|--------------------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 200\n", "example": 200 }, "roundTripDurationMs": { "type": "integer", "format": "int32", "description": "Indicates the round-trip duration (in milliseconds).\n\nExample: 367\n", "example": 367 }, "errorMessage": { "type": "string", "nullable": true, "description": "Indicates an error message if the delivery failed.\n\nExample: Recipient not available\n", "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.\n\nExample: 2025-01-27T12:05:54.322Z\n", "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.\n\nThis value may be null if an attempt succeeded or there is no next retry attempt.\n\nExample: 2026-02-19T20:24:52.934Z\n", "example": "2026-02-19T20:24:52.934Z" }, "requestHeaders": { "type": "object", "nullable": true, "description": "Indicates an object describing the request headers.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } }, "requestBody": { "type": "string", "nullable": true, "description": "Indicates the request body.\n" }, "responseHeaders": { "type": "object", "nullable": true, "description": "Indicates an object describing the response headers.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } }, "responseBody": { "type": "string", "nullable": true, "description": "Indicates the response body.\n" } }, "additionalProperties": false }, "retrywebhookdeliveryisvresponsedto": { "type": "object", "properties": { "deliveryLogId": { "type": "string", "format": "uuid", "description": "Indicates the webhook delivery log identifier to retrieve.\n\nExample: 89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25\n", "example": "89a2c8d9-0e1f-4a2b-3c4d-5e6f7a8b9c25" }, "endpointId": { "type": "string", "format": "uuid", "description": "Indicates the webhook endpoint identifier.\n\nExample: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36\n", "example": "9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36" }, "endpointName": { "type": "string", "nullable": true, "maxLength": 255, "description": "Indicates the display name for the webhook.\n\nThis is a free-formed name that is convenient to recognize.\n\nExample: Peppared Street Cafe's Reconciliation\n", "example": "Peppared Street Cafe's Reconciliation" }, "endpointUrl": { "type": "string", "maxLength": 2048, "x-method": "response", "description": "Indicates the HTTPS callback URL that receives webhook events.\n\nExample: https://example.com/webhooks/pepparedstreetcafe\n", "example": "https://example.com/webhooks/pepparedstreetcafe", "nullable": true }, "eventId": { "type": "string", "format": "uuid", "description": "Indicates the event identifier.\n\nExample: 399f9d7d-0714-453c-9b6d-dda836e1d8e6\n", "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.\n\nExample: 3\n", "example": 3 }, "endpointHTTPResponseCode": { "type": "integer", "format": "int32", "nullable": true, "description": "Indicates the HTTP response status code.\n\nThis is the HTTP status code returned by the attempted delivery.\n\nThe following is a list of HTTP response status codes that include but are not limited to:\n\n| HTTP Status | Meaning |\n|:-----------:|--------------------|\n| 200 | Delivery succeeded |\n| 400 | Bad request |\n| 401 | Unauthorized |\n| 404 | Endpoint not found |\n| 429 | Rate limited |\n\nExample: 200\n", "example": 200 }, "roundTripDurationMs": { "type": "integer", "format": "int32", "description": "Indicates the round-trip duration (in milliseconds).\n\nExample: 367\n", "example": 367 }, "errorMessage": { "type": "string", "nullable": true, "description": "Indicates an error message if the delivery failed.\n\nExample: Recipient not available\n", "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.\n\nExample: 2025-01-27T12:05:54.322Z\n", "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.\n\nThis value may be null if an attempt succeeded or there is no next retry attempt.\n\nExample: 2026-02-19T20:24:52.934Z\n", "example": "2026-02-19T20:24:52.934Z" }, "requestHeaders": { "type": "object", "nullable": true, "description": "Indicates an object describing the request headers.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } }, "requestBody": { "type": "object", "nullable": true, "description": "Indicates an object describing the request body.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } }, "responseHeaders": { "type": "object", "nullable": true, "description": "Indicates an object describing the response headers.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } }, "responseBody": { "type": "object", "nullable": true, "description": "Indicates an object describing the response body.\n", "additionalProperties": { "type": "string", "nullable": true, "description": "This object may not contain fields that are predefined.\n\nReview the actual returned fields for names and values.\n" } } }, "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": "", "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": "", "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": "", "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": "", "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": "", "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": "", "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": "", "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": "", "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.\n\nA page is considered each set of the `pageSize` values.\n\nThe page count is zero-based.\nThe maximum for `pageIndex`, or the page number, is the `pageSize` divided by the `total` count rounded down.\nFor example, the `pageSize` is 50 and the `total` is 130.\nThat means there are three pages, but the `pageIndex` value is in the inclusive range from zero to two.\n\nValue restrictions include:\n* A value less than zero is not permitted.
\n* Values equal to or greater than `totalPages` end successfully but will not return any items.\n\nFor page size information, see `pageSize`.\n\nExample: 0\n", "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.\n\nA page is considered each set of the `pageSize` values.\n\nThe page count is zero-based.\nThe maximum for `pageIndex`, or the page number, is the `pageSize` divided by the `total` count rounded down.\nFor example, the `pageSize` is 50 and the `total` is 130.\nThat means there are three pages, but the `pageIndex` value is in the inclusive range from zero to two.\n\nFor page numbering information, see `pageIndex`.\n\nExample: 50\n", "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.\n\nThe sort field is specified by the `orderBy` value.\n\nIf `true`, the sort order is ascending.
\nIf `false`, the sort order is descending.\n\nExample: true\n", "schema": { "type": "boolean", "default": true, "x-method": "query" } }, "sortby": { "name": "sortBy", "in": "query", "description": "Specifies the field the results get ordered or sorted by.\n\nThe sort order is specified by the `sortOrder` value.
\nThe field that gets sorted by is specified by the `sortBy` value.\n", "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).\n\nIf only `createdFrom` is specified, the search returns all available items from the `createdFrom` value to the present.\nThe fields `createdFrom` and `createdTo` may be used together to create an inclusive range.\nWe recommend creating an inclusive range to avoid a potentially excessive number of returns.\n", "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).\n\nIf only `createdFrom` is specified, the search returns all available items from the `createdFrom` value to the present.\nThe fields `createdFrom` and `createdTo` may be used together to create an inclusive range.\nWe recommend creating an inclusive range to avoid a potentially excessive number of returns.\n", "schema": { "type": "string", "format": "date-time", "example": "2026-03-06T14:24:52.934Z" } }, "sortOrder": { "name": "sortOrder", "in": "query", "description": "Specifies the sort order.\n\nThe sort order is specified by the `sortOrder` value.
\nThe field that gets sorted by is specified by the `sortBy` value.\n\nValid values are:\n\n| Value | Description |\n| ------ | --------------------------------------------------------- |\n| asc | Sort results from the lowest value to the highest value. |\n| desc | Sort results from the highest value to the lowest value. |\n", "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).\n\nIf only `dateFrom` is specified, the search returns all available items from the `dateFrom` value to the present.\nThe fields `dateFrom` and `dateTo` may be used together to create an inclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "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).\n\nIf only `dateTo` is specified, the search returns all available items before including the `dateTo` value.\nThe fields `dateFrom` and `dateTo` may be used together to create an inclusive range.\nWe recommend creating an explicit range to avoid a potentially excessive number of returns.\n", "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.\n\nValid values are:\n\n| Batch Type | Meaning |\n|------------|---------|\n| Open | An open batch is still active and accepting transactions. |\n| Settled | A settled batch has completed processing with the acquirer or bank. |\n\nExample: Open\n", "schema": { "type": "string", "example": "Open" } }, "AggregatedTransactionParameterStatus": { "name": "transactionStatus", "in": "query", "description": "Specifies a filter by the aggregated transaction status.\n\nValid values are:\n\n| Status | Description | Type |\n|-----------------------|-----------------------------------------------------|:----:|\n| Authorized | Payment approved but funds not yet captured. | Card |\n| Cancelled | Transaction stopped before it completed. | ACH |\n| Captured | Approved funds collected from the card. | Card |\n| ChargedBack | Cardholder disputed the charge with their bank.| ACH |\n| Cleared | Funds finished processing and settled. | ACH |\n| Declined | Payment rejected by the bank or processor. | Card/ACH |\n| Failed | Transaction could not complete due to an error. | Card/ACH |\n| Held | Transaction paused and awaiting release. | ACH |\n| HeldByProcessor | Processor paused the transaction for review. | ACH |\n| Informational | Record used for reference only, not a live charge. | Card |\n| InProgress | Transaction is still processing. | ACH |\n| PartiallyAuthorized | Only part of the requested amount was approved. | Card |\n| Pending | Transaction is waiting for a result. | Card/ACH |\n| Refunded | Funds returned to the cardholder. | Card |\n| Scheduled | Transaction set to run at a future time. | ACH |\n| Settled | Funds moved from issuer to the merchant account. | Card |\n| Verified | Card or account confirmed as valid. | Card |\n| Voided | Authorization cancelled before capture. | Card |\n", "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.\n\nOmit this parameter to include all event types.\n\nValid values are:\n\n| Wire value | Meaning | Group |\n|-------------------------------|---|---|\n| api_key.created | An API key was created | API Keys (affiliate only) |\n| api_key.deleted | An API key was revoked or deleted | API Keys (affiliate only) |\n| invoice.created | A new invoice was created | Invoices |\n| invoice.paid | An invoice was marked as paid | Invoices |\n| merchant.created | A new merchant account was created | Merchants (affiliate only) |\n| payment_session.completed | A payment session reached a terminal state (completed, failed, or cancelled) | Payment Sessions |\n| payment_session.created | A payment session was created | Payment Sessions |\n| quick_payment.created | A quick payment link was created | Quick Payments |\n| quick_payment.paid | A quick payment link was paid | Quick Payments |\n| settlement.batch.completed | A batch settlement was processed and settled | Settlement |\n| subscription.created | A new subscription was created | Subscriptions |\n| subscription.delinquent | A subscription entered a delinquent state after repeated payment failures | Subscriptions |\n| subscription.paid | A subscription payment was successfully collected | Subscriptions |\n| subscription.payment_failed | A subscription payment attempt failed | Subscriptions |\n| terminal.added | A new terminal was registered to the account | Terminals |\n| terminal.deactivated | A terminal was deactivated on the account | Terminals |\n| terminal.out_of_paper | A terminal paper roll is empty | Terminals |\n| transaction.ach.cancelled | An ACH transaction was cancelled before processing | ACH Transactions |\n| transaction.ach.charged_back | An ACH transaction was returned or charged back | ACH Transactions |\n| transaction.ach.cleared | An ACH transaction successfully cleared | ACH Transactions |\n| transaction.ach.failed | An ACH transaction failed due to a processing error | ACH Transactions |\n| transaction.ach.held | An ACH transaction was placed on hold for review | ACH Transactions |\n| transaction.ach.in_progress | An ACH transaction was submitted to the network | ACH Transactions |\n| transaction.ach.refunded | An ACH transaction was refunded to the originator | ACH Transactions |\n| transaction.ach.scheduled | An ACH transaction was created and scheduled | ACH Transactions |\n| transaction.card.authorized | A card payment authorization was approved | Card Transactions |\n| transaction.card.captured | An authorized card payment was captured | Card Transactions |\n| transaction.card.declined | A card payment was declined by the issuer | Card Transactions |\n| transaction.card.failed | A card payment failed due to a processing error | Card Transactions |\n| transaction.card.refunded | A card payment was refunded to the cardholder | Card Transactions |\n| transaction.card.voided | A card authorization was voided before capture | Card Transactions |\n", "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" ] } } } } }