QuickBooks E Checks API

openapi: 3.2.0
info:
  title: QuickBooks Payments E Checks API
  version: '2026-11-05'
  description: 'QuickBooks Payments API (v4): bank accounts, cards, charges, eChecks, tokens and payment receipts for a QuickBooks Payments merchant. Generated from the JSON Intuit''s API Explorer renders; Intuit publishes no OpenAPI document.'
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/legal-agreements/intuit-terms-of-service-for-intuit-developer-services
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com/s/
  x-generated-from: documentation
  x-generator: convert-intuit-api-explorer.py (deterministic conversion of the provider's API Explorer JSON; no model)
  x-source:
  - https://static.developer.intuit.com/JSONObjects/EntityJsonObject_v1.json
  - https://static.developer.intuit.com/JSONObjects/CodesModelsJsonObjects_v2.json
  - https://static.developer.intuit.com/JSONObjects/TocJsonObject_v1.json
  x-generated: '2026-11-05'
servers:
- url: https://api.intuit.com
  description: Production
- url: https://sandbox.api.intuit.com
  description: Sandbox
security:
- oauth2:
  - com.intuit.quickbooks.payment
tags:
- name: EChecks
  description: 'The eCheck entity lets you create and store eCheck objects.


    Apps can store and use bank accounts as a payment method for payment processing via the charges entity.


    Note: This entity can only be used for US-based QuickBooks Online companies.


    Available operations:POST/Create

    GET/Read

    Unique operationsRefund

    Void'
paths:
  /quickbooks/v4/payments/echecks:
    post:
      operationId: createEChecks
      summary: Create an eCheck
      tags:
      - EChecks
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/echecks
      x-intuit-operation: POST /quickbooks/v4/payments/echecks
      description: 'When you create an eCheck, you''ll also debit a bank account.


        This POST operation creates an eCheck and debits the bank account it''s coming from.'
      x-intuit-parameters-note:
      - "Header Parameters: In your request, specify the request-Id as a header parameter. If the server receives another request with the same request-Id, instead of performing the operation again and potentially returning an error, it sends the same response intended for the original request.\n\n The request-Id must be unique across all requests, regardless of endpoint, for a given QuickBooks Online company.\n\n To avoid duplicates, your app should generate a unique request-Id for each request. We recommend you generate request-Id values with libraries like java.util.UUID or .NET System.GUID."
      parameters:
      - name: Request-Id
        in: header
        schema:
          type: string
        description: "The request-Id that uniquely identifies the HTTP request sent by your app to the server. \n\nThis lets apps correlate requests and responses in case it needs to resend a request due to a dropped connection."
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/echeckrequest'
        required: true
        description: 'To create an eCheck, include the following required attributes:amount

          paymentMode

          token or bankAccount or bankAccountOnFile

          You can also include optional attributes:description

          checkNumber

          context'
      responses:
        '200':
          description: This creates an eCheck and debits the bank account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/echeckresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
  /quickbooks/v4/payments/echecks/{echeck_id}/refunds/{refund_id}:
    get:
      operationId: readEChecks
      summary: Get eCheck refund details
      tags:
      - EChecks
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/echecks
      x-intuit-operation: GET /quickbooks/v4/payments/echecks/<echeck_id>/refunds/<refund_id>
      description: This GET operation gets info about refunded eChecks.
      x-intuit-parameters-note:
      - "Header Parameters: In your request, specify the request-Id as a header parameter. If the server receives another request with the same request-Id, instead of performing the operation again and potentially returning an error, it sends the same response intended for the original request.\n\n The request-Id must be unique across all requests, regardless of endpoint, for a given QuickBooks Online company.\n\n To avoid duplicates, your app should generate a unique request-Id for each request. We recommend you generate request-Id values with libraries like java.util.UUID or .NET System.GUID."
      parameters:
      - name: echeck_id
        in: path
        required: true
        schema:
          type: string
      - name: refund_id
        in: path
        required: true
        schema:
          type: string
      - name: Request-Id
        in: header
        schema:
          type: string
        description: "The request-Id that uniquely identifies the HTTP request sent by your app to the server. \n\nThis lets apps correlate requests and responses in case it needs to resend a request due to a dropped connection."
        required: true
      - name: echeck_id
        in: query
        schema:
          type: string
        description: The id of the eCheck you want info for. The ID is defined in the response of the CREATE eCheck operation.
        required: true
      - name: refund_id
        in: query
        schema:
          type: string
        description: The id of the refund you want info for. The ID is defined in the reponse of the VOID or REFUND eCheck operation.
        required: true
      responses:
        '200':
          description: Returns info about the refund object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/echeckresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
  /quickbooks/v4/payments/echecks/{echeck_id}:
    get:
      operationId: getECheckDetails
      summary: Get eCheck details
      tags:
      - EChecks
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/echecks
      x-intuit-operation: GET /quickbooks/v4/payments/echecks/<echeck_id>
      description: 'This GET operation gets info for an existing eCheck transaction.


        Use the id field to specify the eCheck you want info for.'
      x-intuit-parameters-note:
      - "Header Parameters: In your request, specify the request-Id as a header parameter. If the server receives another request with the same request-Id, instead of performing the operation again and potentially returning an error, it sends the same response intended for the original request.\n\n The request-Id must be unique across all requests, regardless of endpoint, for a given QuickBooks Online company.\n\n To avoid duplicates, your app should generate a unique request-Id for each request. We recommend you generate request-Id values with libraries like java.util.UUID or .NET System.GUID."
      parameters:
      - name: echeck_id
        in: path
        required: true
        schema:
          type: string
      - name: Request-Id
        in: header
        schema:
          type: string
        description: "The request-Id that uniquely identifies the HTTP request sent by your app to the server. \n\nThis lets apps correlate requests and responses in case it needs to resend a request due to a dropped connection."
        required: true
      - name: Id
        in: query
        schema:
          type: string
        description: The id of the eCheck. The ID is defined in the response of the CREATE check operation.
        required: true
      responses:
        '200':
          description: Returns info about the eCheck object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/echeckresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
  /quickbooks/v4/payments/echecks/{echeck_id}/refunds:
    post:
      operationId: voidEChecks
      summary: Void or refund an eCheck
      tags:
      - EChecks
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/echecks
      x-intuit-operation: POST /quickbooks/v4/payments/echecks/<echeck_id>/refunds
      description: 'This POST operation lets you fully or partially refund an eCheck transaction.


        You can void eChecks if the refund request is made the same day as the created debit request.

        We can''t issue refunds unless the original debit transaction is settled. This usually takes 3 business days.

        Use the id field to specify the eCheck you want to refund.'
      x-intuit-parameters-note:
      - "Header Parameters: In your request, specify the request-Id as a header parameter. If the server receives another request with the same request-Id, instead of performing the operation again and potentially returning an error, it sends the same response intended for the original request.\n\n The request-Id must be unique across all requests, regardless of endpoint, for a given QuickBooks Online company.\n\n To avoid duplicates, your app should generate a unique request-Id for each request. We recommend you generate request-Id values with libraries like java.util.UUID or .NET System.GUID."
      parameters:
      - name: echeck_id
        in: path
        required: true
        schema:
          type: string
      - name: Request-Id
        in: header
        schema:
          type: string
        description: "The request-Id that uniquely identifies the HTTP request sent by your app to the server. \n\nThis lets apps correlate requests and responses in case it needs to resend a request due to a dropped connection."
        required: true
      - name: Id
        in: query
        schema:
          type: string
        description: The id of the eCheck. The ID is defined in the response of the CREATE check operation.
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/echeckrefundrequest'
        required: true
      responses:
        '200':
          description: Returns an eCheck refund object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/echeckresponse'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
components:
  schemas:
    bankaccount:
      type: object
      title: bankaccount
      properties:
        Updated:
          type: string
          description: The time the object was last updated. In ISO 8601 date-time format. It appears as YYYY-MM-DDTHH:MM:SSZ.
          x-intuit-required: Conditionally required
        entityType:
          type: string
          description: 'The entity or user type the bank account is associated with. Example values: Customer, Employee, Vendor or Company'
          x-intuit-required: Optional
        Name:
          type: string
          description: The name of the bank account owner.
          x-intuit-required: Required
        AccountNumber:
          type: string
          description: "The number of the bank account.\n\n For privacy and security,\nAccount numbers that are 6 digits or less: all but the last 2 digits are masked\nAccount numbers that are 7 digits or longer: all but the last 4 digits are masked\n Account Number masking changes are available in Sandbox companies currently and will be available from July 11th, 2022 for Production companies."
          x-intuit-required: Required
        Default:
          type: boolean
          description: "Indicates if the bank account is the default. When users set a default, the account flag is true.\n\n This is the bank account QuickBooks uses when another isn't specified.\n\n The flag defaults to false. When a bank account flag is true, all other stored bank accounts are automatically set to false."
          x-intuit-required: Optional
        Country:
          type: string
          description: The ISO-standard country code. Refer to the ISO Country Code List.
          x-intuit-required: Optional
        Created:
          type: string
          description: The time the object was originally created. In ISO 8601 date-time format. It appears as YYYY-MM-DDTHH:MM:SSZ.
        InputType:
          type: string
          description: "Specifies the input type. \n\nValid values:KEYED: Indicates a manually-entered key.\nSCANNED"
          x-intuit-required: Optional
        Phone:
          type: string
          description: The phone number associated with the bank account.
          x-intuit-required: Required
        AccountType:
          type: string
          description: "The type of bank account. \n\nValid values:PERSONAL_CHECKING: Use for personal checking accounts.\n PERSONAL_SAVINGS: Use for personal savings accounts.\nBUSINESS_CHECKING: Use for business checking accounts.\nBUSINESS_SAVINGS: Use for business savings accounts."
          x-intuit-required: Required
        BankCode:
          type: string
          description: 'For US: This should also be the routing number for the bank associated with the account.'
          x-intuit-required: Optional
        entityId:
          type: string
          description: The ID of the entity the bank account is associated with.
          x-intuit-required: Optional
        RoutingNumber:
          type: string
          description: "The routing number for the bank associated with the account.\n\n For privacy and security, we only display the last four digits of the routing number."
          x-intuit-required: Required
        Id:
          type: string
          description: "The unique identifier of a bank account object.\n\n The id is required for update or delete operations."
          x-intuit-required: Conditionally required
      required:
      - AccountNumber
      - AccountType
      - Name
      - Phone
      - RoutingNumber
    restaurant:
      type: object
      title: restaurant
      properties:
        BeverageAmount:
          type: number
          description: The amount of the current charge attributed to beverages.
        ServerID:
          type: string
          description: The 2-digit string that identifies the individual server responsible for the transaction. Restaurant assign their own identifiers to their servers.
        TaxAmount:
          type: number
          description: The amount of the current charge attributed to tax.
        FoodAmount:
          type: number
          description: The amount of the current charge attributed to food.
        TipAmount:
          type: number
          description: The amount of the current charge attributed to tips.
    echeckrequest:
      type: object
      title: echeckrequest
      properties:
        BankAccount:
          allOf:
          - $ref: '#/components/schemas/bankaccount'
          description: Explicit bank account details associated with this transaction. Required if neither token nor bankAccountOnFile are specified
        Description:
          type: string
          description: Descriptive text to be stored with the transaction.
          x-intuit-required: Optional
        CheckNumber:
          type: string
          description: The number for the echeck, if desired.
          x-intuit-required: Optional
        PaymentMode:
          type: object
          x-intuit-type: ECheckPaymentModeType
          description: "The payment mode. This is also known as the SEC Code. Valid options include:\n\n  WEB: Internet-initiated entry mode, used for internet transactions."
          x-intuit-required: Required
        Token:
          type: string
          description: An opaque representation of the bank account associated with the debit, as returned by the token endpoint. Required if neither bankAccount nor bankAccountOnFile are specified
        BankAccountOnFile:
          type: string
          description: The bank account details that have been previously stored on file. Required if neither token nor bankAccount are specified
        Amount:
          type: number
          description: "Amount of the transaction. Valid values for amount are in the range\n   0.00  through\n   99999.99  ."
          x-intuit-required: Required
        Context:
          allOf:
          - $ref: '#/components/schemas/checkcontext'
          description: Additional data that may be stored with the transaction.
          x-intuit-required: Optional
      required:
      - Amount
      - PaymentMode
    checkcontext:
      type: object
      title: checkcontext
      properties:
        DeviceInfo:
          allOf:
          - $ref: '#/components/schemas/deviceinfo'
          description: Info about the device used to process the payment.
          x-intuit-required: Optional
    lodging:
      type: object
      title: lodging
      properties:
        LengthOfStay:
          type: number
          description: The anticipated, actual, or icremental length of stay, depending on the transaction type.
        CheckInDate:
          type: string
          format: date
          description: "The date of actual or anticipated check-in, depending on the transaction type.\n\nThe check-in date can't be later than the check-out date. The date format is dates is CCCC-MM-DD where: CCCC: The four-digit year\nMM: The two digit month\nDD: The Two digit day\n For example: June 5, 2019 is represented as 2019-06-05."
        RoomRate:
          type: number
          description: "The nightly rate for the room. \n\nThis field is only relevant for lodging apps. It should represent the nightly rate for the room as quoted at the time of reservation, including the taxes. If the reservation spans multiple days, provide the average rate for those days."
        SpecialProgram:
          type: object
          x-intuit-type: SpecialProgramEnumorator
          description: 'Indicates if the current charge is a normal room charge, an advance deposit, and so forth.


            This field is only relevant for lodging apps. It indicates the reason for the charge.


            Valid values: AdvanceDeposit

            AssuredReservation

            DelayedCharge

            ExpressService

            NormalCharge

            NoShowCharge'
        ChargeType:
          type: object
          x-intuit-type: ChargeTypeEnumerator
          description: 'Indicates the specific lodging or non-lodging service charged to the customer.


            Valid values: ConventionFees

            GiftShop

            Golf

            HealthClub

            Hotel

            Restaurant

            Salon

            Tennis'
        FolioID:
          type: string
          description: The unique ID that identifies the bill for a particular guest's stay. This value can be assigned by a hotel or automatically by lodging apps.
        ExtraCharges:
          type: object
          x-intuit-type: Array of strings
          description: "Indicates if the current charge contains one or more additional charges. \n\nThis field is only relevant for lodging apps. It indicates the types of extra charges billed to the customer. They usually apply after a customer checks out. \n\nValid values: GiftShop\nLaundry\nMinibar\nRestaurant\nTelephone\nOther"
        CheckOutDate:
          type: string
          format: date
          description: "The date of actual or anticipated check-out, depending on the transaction type.\n\nThe check-out date must always be later than the check-in date. The date format is dates is CCCC-MM-DD where: CCCC: The four-digit year\nMM: The two digit month\nDD: The Two digit day\n For example: June 5, 2019 is represented as 2019-06-05."
        TotalAuthAmount:
          type: number
          description: 'The total amount authorized by the card issuer for the current credit card and the current FolioID.


            It refers to the total amount authorized for the particular card and folio and includes tax and other applicable charges. Apps are responsible for keeping a running total of authorizations and submitting the correct amount in this field.'
    IntuitFault:
      type: object
      properties:
        Fault:
          type: object
          properties:
            type:
              type: string
              enum:
              - ValidationFault
              - SystemFault
              - AuthenticationFault
              - AuthorizationFault
            Error:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  element:
                    type: string
                  Message:
                    type: string
                  Detail:
                    type: string
        time:
          type: string
          format: date-time
    echeckrefundrequest:
      type: object
      title: echeckrefundrequest
      properties:
        Amount:
          type: object
          x-intuit-type: number
          description: 'The amount to be refunded. Valid values: Any value between 0.01 and 99999.99.'
          x-intuit-required: Required
        Description:
          type: string
          description: A description of the refund.
          x-intuit-required: Optional
        Context:
          allOf:
          - $ref: '#/components/schemas/paymentcontext'
          description: Additional info that will be stored with the transaction.
          x-intuit-required: Optional
      required:
      - Amount
    deviceinfo:
      type: object
      title: deviceinfo
      properties:
        MacAddress:
          type: string
          description: The device's media access control (MAC) address.
          x-intuit-required: Optional
        Encrypted:
          type: boolean
          description: The device's encryption status.
          x-intuit-required: Optional
        IpAddress:
          type: string
          description: The device's IP address.
          x-intuit-required: Optional
        Longitude:
          type: string
          description: The device's longitude coordinates.
          x-intuit-required: Optional
        PhoneNumber:
          type: string
          description: The device's phone number (if available).
          x-intuit-required: Optional
        Latitude:
          type: string
          description: The device's latitude coordinates.
          x-intuit-required: Optional
        Type:
          type: string
          description: The type of device.
          x-intuit-required: Optional
        Id:
          type: string
          description: The device's ID.
          x-intuit-required: Conditionally required
    paymentcontext:
      type: object
      title: paymentcontext
      properties:
        Restaurant:
          allOf:
          - $ref: '#/components/schemas/restaurant'
          description: For restaurant transactions, provides details about the restaurant.
        Mobile:
          type: boolean
          description: "Flag that indicates if the charge was made from a mobile device.\n\n The card can be keyed, swiped, dipped or tapped on the merchant's POS device."
          x-intuit-required: Required
          x-intuit-default: false
        Tax:
          type: number
          description: The sales tax required for commercial card processing.
          x-intuit-required: Optional
        IsEcommerce:
          type: boolean
          description: Flag that indicates if the charge is an eCommerce transaction made over the web.
          x-intuit-required: Required
          x-intuit-default: false
        DeviceInfo:
          allOf:
          - $ref: '#/components/schemas/deviceinfo'
          description: Provides info about the device used to swipe or take payments.
          x-intuit-required: Optional
        Lodging:
          allOf:
          - $ref: '#/components/schemas/lodging'
          description: For lodging transactions, provides details about the lodging.
        Recurring:
          type: boolean
          description: 'This is set to true if the charge is recurring. Note: This value ignored for capture and refund requests.'
          x-intuit-required: Optional
          x-intuit-default: false
      required:
      - IsEcommerce
      - Mobile
    echeckresponse:
      type: object
      title: echeckresponse
      properties:
        Status:
          type: object
          x-intuit-type: ECheckStatus
          description: "The current status of the check. Learn more about check states.\n\nValid values types:PENDING: The check is being processed.\nSUCCEEDED: The check was funded and the transaction is complete.\nDECLINED: The check was rejected.\n VOIDED: The check was voided.\nREFUNDED: The check was refunded."
        BankAccount:
          allOf:
          - $ref: '#/components/schemas/bankaccount'
          description: "Specify or create the bank account associated with this transaction. \n\nRequired if the token or bankAccountOnFile aren't specified.\n\nReview the bankAccount entity for field details."
          x-intuit-required: Conditionally required
        Description:
          type: string
          description: Additional details about the eCheck and transaction.
          x-intuit-required: Optional
        Created:
          type: string
          description: The time the object was originally created. In ISO 8601 date-time format. It appears as YYYY-MM-DDTHH:MM:SSZ.
        CheckNumber:
          type: string
          description: "The number of the eCheck associated with the transaction. \n\nThis number must be unique. Using the same checkNumber to create multiple eChecks will result in declines."
          x-intuit-required: Optional
        AuthCode:
          type: string
          description: The authorization code for the echeck.
          x-intuit-required: Optional
        PaymentMode:
          type: object
          x-intuit-type: PaymentModeType
          description: 'The payment mode. This is also known as the SEC Code.


            Valid values:WEB: Internet-initiated entry mode used for internet transactions.'
          x-intuit-required: Required
        Token:
          type: string
          description: 'The opaque container for the credit or debit card account associated with the transaction.


            Required if the bankAccount or bankAccountOnFile aren''t specified. Learn more about creating tokens.'
          x-intuit-required: Conditionally Required
        BankAccountOnFile:
          type: string
          description: 'An existing bank account that was previously stored.


            Specify the ID of the existing bank account. Required if the token or bankAccount aren''t specified.'
          x-intuit-required: Conditionally Required
        Amount:
          type: number
          description: 'The eCheck amount.


            Valid values: Any value between 0.01 and 99999.99.'
          x-intuit-required: Required
        Context:
          allOf:
          - $ref: '#/components/schemas/checkcontext'
          description: Additional info stored with the transaction.
          x-intuit-required: Optional
        Id:
          type: string
          description: The unique identifier for the eCheck.
          x-intuit-required: Conditionally required
      required:
      - Amount
      - PaymentMode
  responses:
    Fault:
      description: Error. The body carries a Fault element (type ValidationFault, SystemFault, AuthenticationFault or AuthorizationFault) with one or more Error entries (code, element, Message, Detail).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntuitFault'
    Throttled:
      description: 'HTTP 429: the request was throttled. Wait 60 seconds before retrying.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IntuitFault'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Intuit OAuth 2.0 (authorization code). Discovery: https://developer.api.intuit.com/.well-known/openid_configuration'
      flows:
        authorizationCode:
          authorizationUrl: https://appcenter.intuit.com/connect/oauth2
          tokenUrl: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
          refreshUrl: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
          scopes:
            com.intuit.quickbooks.accounting: Grants access to the QuickBooks Online Accounting API, which focuses on accounting data.
            com.intuit.quickbooks.payment: Grants access to the QuickBooks Payments API, which focuses on payments processing.
            openid: Grants access to OpenID Connect features.
            profile: User's given and family names info
            email: User's email address
            phone: User's phone number
            address: User's physical address
x-generated-from: documentation
x-provenance:
  method: generated
  generated: '2026-11-05'
  source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/charges
  note: Converted from the JSON the developer.intuit.com API Explorer loads (static.developer.intuit.com/JSONObjects). Intuit publishes no OpenAPI document; this is a faithful machine transformation of its own reference data, graded as generated.