Intuit Payments API

openapi: 3.1.0
info:
  title: QuickBooks Online Accounting Customers Payments API
  description: The QuickBooks Online Accounting API is a RESTful API that provides programmatic access to QuickBooks Online company data. This specification covers core entities including invoices, customers, items, and payments, enabling developers to automate accounting workflows, synchronize financial data, and extend QuickBooks Online functionality for small and mid-sized businesses. All API calls require OAuth 2.0 authorization and a valid company ID (realmId). Responses follow the Intuit entity response envelope pattern, and the API supports minor version parameters to access newer fields and behaviors without breaking existing integrations.
  version: '75'
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com
    email: developer-support@intuit.com
  license:
    name: Intuit Developer Terms of Service
    url: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  x-logo:
    url: https://developer.intuit.com/app/developer/common/imgs/IntuitDev_Logo.svg
servers:
- url: https://quickbooks.api.intuit.com/v3/company/{realmId}
  description: Production
  variables:
    realmId:
      description: The QuickBooks Online company ID (realm ID) that uniquely identifies the company dataset to operate on.
      default: '1234567890'
- url: https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}
  description: Sandbox
  variables:
    realmId:
      description: The sandbox company ID for testing and development purposes.
      default: '1234567890'
security:
- oauth2: []
tags:
- name: Payments
  description: A Payment object records a payment received from a customer against one or more invoices or credit memos. Payments can be applied to specific invoices or left as unapplied credits.
  externalDocs:
    url: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/payment
paths:
  /query:
    get:
      operationId: queryEntities
      summary: Query Entities
      description: Executes a SQL-like query against QuickBooks Online entities. The query language supports SELECT, WHERE, ORDER BY, COUNT, STARTPOSITION, and MAXRESULTS clauses. This endpoint is used to query invoices, customers, items, payments, and other entity types.
      tags:
      - Payments
      parameters:
      - name: query
        in: query
        required: true
        description: 'A SQL-like query string. For example: SELECT * FROM Invoice WHERE TotalAmt > ''100.00'' ORDERBY TxnDate'
        schema:
          type: string
        example: SELECT * FROM Invoice WHERE TotalAmt > '100.00' MAXRESULTS 10
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                Queryentities200Example:
                  summary: Default queryEntities 200 response
                  x-microcks-default: true
                  value:
                    QueryResponse:
                      startPosition: 10
                      maxResults: 10
                      totalCount: 10
                      Invoice:
                      - {}
                      Customer:
                      - {}
                      Item:
                      - {}
                      Payment:
                      - {}
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payment:
    post:
      operationId: createPayment
      summary: Create a Payment
      description: Creates a new payment received from a customer. The payment can be applied to one or more outstanding invoices using the Line array with LinkedTxn references. If TotalAmt exceeds the sum of linked transactions, the remainder is treated as an unapplied amount.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
            examples:
              CreatepaymentRequestExample:
                summary: Default createPayment request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  TxnDate: '2026-01-15'
                  TotalAmt: 42.5
                  CustomerRef:
                    value: example_value
                    name: Example Title
                  DepositToAccountRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  PaymentRefNum: example_value
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  ExchangeRate: 42.5
                  Line:
                  - Amount: 42.5
                    LinkedTxn: {}
                  PrivateNote: example_value
                  UnappliedAmt: 42.5
                  ProcessPayment: true
                  TxnSource: example_value
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                Createpayment200Example:
                  summary: Default createPayment 200 response
                  x-microcks-default: true
                  value:
                    Payment:
                      Id: abc123
                      SyncToken: example_value
                      TxnDate: '2026-01-15'
                      TotalAmt: 42.5
                      PaymentRefNum: example_value
                      ExchangeRate: 42.5
                      Line:
                      - {}
                      PrivateNote: example_value
                      UnappliedAmt: 42.5
                      ProcessPayment: true
                      TxnSource: example_value
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payment/{paymentId}:
    get:
      operationId: readPayment
      summary: Read a Payment
      description: Retrieves the details of a payment that has been previously created. Supply the unique payment ID.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/paymentId'
      - $ref: '#/components/parameters/minorVersion'
      responses:
        '200':
          description: Payment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                Readpayment200Example:
                  summary: Default readPayment 200 response
                  x-microcks-default: true
                  value:
                    Payment:
                      Id: abc123
                      SyncToken: example_value
                      TxnDate: '2026-01-15'
                      TotalAmt: 42.5
                      PaymentRefNum: example_value
                      ExchangeRate: 42.5
                      Line:
                      - {}
                      PrivateNote: example_value
                      UnappliedAmt: 42.5
                      ProcessPayment: true
                      TxnSource: example_value
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: updatePayment
      summary: Update a Payment
      description: Updates an existing payment. The request must include the Id and SyncToken. Use this to change the linked transactions, payment method, or other details.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/paymentId'
      - name: sparse
        in: query
        description: Set to true for a sparse (partial) update
        schema:
          type: boolean
        example: true
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
            examples:
              UpdatepaymentRequestExample:
                summary: Default updatePayment request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
                  MetaData:
                    CreateTime: '2026-01-15T10:30:00Z'
                    LastUpdatedTime: '2026-01-15T10:30:00Z'
                  TxnDate: '2026-01-15'
                  TotalAmt: 42.5
                  CustomerRef:
                    value: example_value
                    name: Example Title
                  DepositToAccountRef:
                    value: example_value
                    name: Example Title
                  PaymentMethodRef:
                    value: example_value
                    name: Example Title
                  PaymentRefNum: example_value
                  CurrencyRef:
                    value: example_value
                    name: Example Title
                  ExchangeRate: 42.5
                  Line:
                  - Amount: 42.5
                    LinkedTxn: {}
                  PrivateNote: example_value
                  UnappliedAmt: 42.5
                  ProcessPayment: true
                  TxnSource: example_value
                  domain: example_value
                  sparse: true
      responses:
        '200':
          description: Payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                Updatepayment200Example:
                  summary: Default updatePayment 200 response
                  x-microcks-default: true
                  value:
                    Payment:
                      Id: abc123
                      SyncToken: example_value
                      TxnDate: '2026-01-15'
                      TotalAmt: 42.5
                      PaymentRefNum: example_value
                      ExchangeRate: 42.5
                      Line:
                      - {}
                      PrivateNote: example_value
                      UnappliedAmt: 42.5
                      ProcessPayment: true
                      TxnSource: example_value
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /payment/{paymentId}/void:
    post:
      operationId: voidPayment
      summary: Void a Payment
      description: Voids the specified payment. The payment is not deleted but marked as voided. The request body must include the Id and SyncToken. Include the operation=void query parameter.
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/paymentId'
      - name: operation
        in: query
        required: true
        schema:
          type: string
          enum:
          - void
        example: void
      - $ref: '#/components/parameters/minorVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - Id
              - SyncToken
              properties:
                Id:
                  type: string
                SyncToken:
                  type: string
            examples:
              VoidpaymentRequestExample:
                summary: Default voidPayment request
                x-microcks-default: true
                value:
                  Id: abc123
                  SyncToken: example_value
      responses:
        '200':
          description: Payment voided successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                Voidpayment200Example:
                  summary: Default voidPayment 200 response
                  x-microcks-default: true
                  value:
                    Payment:
                      Id: abc123
                      SyncToken: example_value
                      TxnDate: '2026-01-15'
                      TotalAmt: 42.5
                      PaymentRefNum: example_value
                      ExchangeRate: 42.5
                      Line:
                      - {}
                      PrivateNote: example_value
                      UnappliedAmt: 42.5
                      ProcessPayment: true
                      TxnSource: example_value
                      domain: example_value
                      sparse: true
                    time: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    QueryResponse:
      type: object
      description: Response wrapper for query operations. Contains the array of matching entities along with pagination metadata.
      properties:
        QueryResponse:
          type: object
          properties:
            startPosition:
              type: integer
              description: Starting position of the results
            maxResults:
              type: integer
              description: Maximum number of results returned
            totalCount:
              type: integer
              description: Total count of matching entities
            Invoice:
              type: array
              items:
                $ref: '#/components/schemas/Invoice'
            Customer:
              type: array
              items:
                $ref: '#/components/schemas/Customer'
            Item:
              type: array
              items:
                $ref: '#/components/schemas/Item'
            Payment:
              type: array
              items:
                $ref: '#/components/schemas/Payment'
          example: example_value
        time:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    Customer:
      type: object
      description: A Customer represents a consumer of the service or product that the business offers. Customers can be organized as sub-customers (jobs) within a parent customer hierarchy.
      properties:
        Id:
          type: string
          description: Unique identifier for the customer
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        Title:
          type: string
          description: Title of the person (e.g., Mr., Mrs., Ms.)
          maxLength: 16
          example: Example Title
        GivenName:
          type: string
          description: Given (first) name of the customer
          maxLength: 100
          example: example_value
        MiddleName:
          type: string
          description: Middle name of the customer
          maxLength: 100
          example: example_value
        FamilyName:
          type: string
          description: Family (last) name of the customer
          maxLength: 100
          example: example_value
        Suffix:
          type: string
          description: Suffix of the person (e.g., Jr., Sr., III)
          maxLength: 16
          example: example_value
        DisplayName:
          type: string
          description: The name displayed to identify the customer. Must be unique across Customer, Employee, and Vendor objects.
          maxLength: 500
          example: example_value
        CompanyName:
          type: string
          description: The name of the company associated with the customer
          maxLength: 500
          example: example_value
        PrintOnCheckName:
          type: string
          description: Name of the customer as printed on a check
          maxLength: 110
          example: example_value
        Active:
          type: boolean
          description: Whether the customer is currently active
          default: true
          example: true
        Taxable:
          type: boolean
          description: Whether the customer is taxable
          example: true
        PrimaryEmailAddr:
          $ref: '#/components/schemas/EmailAddress'
        PrimaryPhone:
          $ref: '#/components/schemas/TelephoneNumber'
        Mobile:
          $ref: '#/components/schemas/TelephoneNumber'
        Fax:
          $ref: '#/components/schemas/TelephoneNumber'
        AlternatePhone:
          $ref: '#/components/schemas/TelephoneNumber'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        Notes:
          type: string
          description: Free-form text about the customer
          maxLength: 2000
          example: example_value
        Job:
          type: boolean
          description: Whether this customer is a sub-customer (job)
          example: true
        ParentRef:
          $ref: '#/components/schemas/ReferenceType'
        Level:
          type: integer
          description: Depth level in the customer hierarchy (0 = top)
          readOnly: true
          example: 10
        FullyQualifiedName:
          type: string
          description: Fully qualified name of the entity, including parent names separated by colons
          readOnly: true
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        PreferredDeliveryMethod:
          type: string
          description: Preferred delivery method for communications
          enum:
          - Print
          - Email
          - None
          example: Print
        Balance:
          type: number
          description: Open balance amount for the customer
          readOnly: true
          example: 42.5
        BalanceWithJobs:
          type: number
          description: Open balance amount including balances of sub-customers (jobs)
          readOnly: true
          example: 42.5
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TaxExemptionReasonId:
          type: string
          description: Tax exemption reason ID
          example: '500123'
        WebAddr:
          type: object
          properties:
            URI:
              type: string
              format: uri
              description: Website address
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - DisplayName
    Payment:
      type: object
      description: A Payment records a payment received from a customer. Payments can be applied to one or more outstanding invoices, or left as unapplied credit.
      properties:
        Id:
          type: string
          description: Unique identifier for the payment
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        TxnDate:
          type: string
          format: date
          description: The date of the payment transaction
          example: '2026-01-15'
        TotalAmt:
          type: number
          description: Total amount of the payment
          example: 42.5
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentRefNum:
          type: string
          description: Reference number for the payment (e.g., check number)
          maxLength: 21
          example: example_value
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate
          example: 42.5
        Line:
          type: array
          description: Lines indicating which invoices or credit memos this payment is applied against
          items:
            $ref: '#/components/schemas/PaymentLine'
          example: []
        PrivateNote:
          type: string
          description: Private note for internal use
          maxLength: 4000
          example: example_value
        UnappliedAmt:
          type: number
          description: Amount not yet applied to invoices
          readOnly: true
          example: 42.5
        ProcessPayment:
          type: boolean
          description: Whether to process the payment through the Intuit payment gateway
          example: true
        TxnSource:
          type: string
          description: Source of the transaction
          readOnly: true
          example: example_value
        domain:
          type: string
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          example: true
      required:
      - CustomerRef
      - TotalAmt
    CustomField:
      type: object
      description: Custom field defined for the entity
      properties:
        DefinitionId:
          type: string
          description: Unique identifier of the custom field definition
          example: '500123'
        Name:
          type: string
          description: Name of the custom field
          example: Example Title
        Type:
          type: string
          description: Data type of the custom field
          enum:
          - StringType
          - BooleanType
          - NumberType
          - DateType
          example: StringType
        StringValue:
          type: string
          description: Value when Type is StringType
          example: example_value
    ReferenceType:
      type: object
      description: A reference type used throughout the API to link entities. Contains the ID value and optionally the display name of the referenced entity.
      properties:
        value:
          type: string
          description: The ID of the referenced entity
          example: example_value
        name:
          type: string
          description: An identifying name for the referenced entity
          example: Example Title
      required:
      - value
    Invoice:
      type: object
      description: An Invoice represents a sales form where the customer pays for a product or service later. It creates an accounts receivable transaction.
      properties:
        Id:
          type: string
          description: Unique identifier for the invoice (assigned by QuickBooks)
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number of the entity, used for optimistic locking. Required for updates.
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        DocNumber:
          type: string
          description: Reference number for the transaction. If not provided, QuickBooks auto-generates one.
          maxLength: 21
          example: example_value
        TxnDate:
          type: string
          format: date
          description: The date of the transaction. Defaults to the current date.
          example: '2026-01-15'
        DueDate:
          type: string
          format: date
          description: Date when the payment of the transaction is due
          example: '2026-01-15'
        PrivateNote:
          type: string
          description: A private note that is not displayed to the customer
          maxLength: 4000
          example: example_value
        CustomerMemo:
          type: object
          description: A note to the customer displayed on the invoice
          properties:
            value:
              type: string
              maxLength: 1000
          example: example_value
        CustomerRef:
          $ref: '#/components/schemas/ReferenceType'
        BillAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        ShipAddr:
          $ref: '#/components/schemas/PhysicalAddress'
        BillEmail:
          $ref: '#/components/schemas/EmailAddress'
        Line:
          type: array
          description: Individual line items of the transaction. At least one line is required.
          items:
            $ref: '#/components/schemas/InvoiceLine'
          minItems: 1
          example: []
        TxnTaxDetail:
          $ref: '#/components/schemas/TxnTaxDetail'
        TotalAmt:
          type: number
          description: Total amount of the transaction including tax
          readOnly: true
          example: 42.5
        Balance:
          type: number
          description: The balance remaining on the invoice. A value of 0 indicates the invoice is fully paid.
          readOnly: true
          example: 42.5
        Deposit:
          type: number
          description: Deposit amount applied to the invoice
          example: 42.5
        DepositToAccountRef:
          $ref: '#/components/schemas/ReferenceType'
        SalesTermRef:
          $ref: '#/components/schemas/ReferenceType'
        PaymentMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        CurrencyRef:
          $ref: '#/components/schemas/ReferenceType'
        ExchangeRate:
          type: number
          description: Currency exchange rate (multicurrency enabled companies)
          example: 42.5
        ShipDate:
          type: string
          format: date
          description: Date for delivery of goods or services
          example: '2026-01-15'
        ShipMethodRef:
          $ref: '#/components/schemas/ReferenceType'
        TrackingNum:
          type: string
          description: Shipping tracking number
          example: example_value
        ApplyTaxAfterDiscount:
          type: boolean
          description: Whether to apply tax after discount
          example: true
        PrintStatus:
          type: string
          description: Printing status of the invoice
          enum:
          - NotSet
          - NeedToPrint
          - PrintComplete
          example: NotSet
        EmailStatus:
          type: string
          description: Email delivery status of the invoice
          enum:
          - NotSet
          - NeedToSend
          - EmailSent
          example: NotSet
        GlobalTaxCalculation:
          type: string
          description: Method in which tax is applied
          enum:
          - TaxExcluded
          - TaxInclusive
          - NotApplicable
          example: TaxExcluded
        AllowOnlinePayment:
          type: boolean
          description: Whether online payment is allowed
          example: true
        AllowOnlineCreditCardPayment:
          type: boolean
          description: Whether online credit card payment is allowed
          example: true
        AllowOnlineACHPayment:
          type: boolean
          description: Whether online ACH (bank) payment is allowed
          example: true
        CustomField:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          maxItems: 3
          example: []
        LinkedTxn:
          type: array
          items:
            $ref: '#/components/schemas/LinkedTxn'
          example: []
        domain:
          type: string
          description: Domain (e.g., QBO)
          readOnly: true
          example: example_value
        sparse:
          type: boolean
          description: Whether this is a sparse (partial) representation
          example: true
      required:
      - CustomerRef
      - Line
    EmailAddress:
      type: object
      description: Email address
      properties:
        Address:
          type: string
          format: email
          description: Email address string
          maxLength: 100
          example: example_value
    Item:
      type: object
      description: An Item represents a product or service that a company buys, sells, or re-sells. Items are used in line items on invoices, sales receipts, bills, and other transactions.
      properties:
        Id:
          type: string
          description: Unique identifier for the item
          readOnly: true
          example: abc123
        SyncToken:
          type: string
          description: Version number for optimistic locking
          example: example_value
        MetaData:
          $ref: '#/components/schemas/MetaData'
          readOnly: true
        Name:
          type: string
          description: Name of the item. Must be unique within the same type.
          maxLength: 100
          example: Example Title
        Description:
          type: string
          description: Description of the item used in sales transactions
          maxLength: 4000
          example: A sample description.
        PurchaseDesc:
          type: string
          description: Description of the item used in purchase transactions
          maxLength: 4000
          example: example_value
        Active:
          type: boolean
          description: Whether the item is currently active
          default: true
          example: true
        FullyQualifiedName:
          type: string
          description: Fully qualified name of the item
          readOnly: true
          example: example_value
        Taxable:
          type: boolean
          description: Whether sales of this item are taxable
          example: true
        SalesTaxIncluded:
          type: boolean
          description: Whether the sales tax is included in the item amount
          example: true
        UnitPrice:
          type: number
          description: Sales price for this item
          example: 42.5
        Type:
          type: string
          description: Classification of the item
          enum:
          - Inventory
          - NonInventory
          - Service
          - Group
          - Category
          - Bundle
          example: Inventory
        PurchaseCost:
          type: number
          description: Purchase cost of the item
          example: 42.5
        QtyOnHand:
          type: number
       

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intuit/refs/heads/main/openapi/intuit-payments-api-openapi.yml