QuickBooks Tokens API

openapi: 3.2.0
info:
  title: QuickBooks Payments Tokens 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: Tokens
  description: 'The token entity lets you create opaque containers to mask cardholder''s credit card or bank account info. Your app can use the token to make API calls and process payments without reading or exposing any private info.


    Tokens aren''t a customer-facing feature in QuickBooks Online. Instead, they''re references that let apps anonymize and securely utilize payment info for transactions. Learn more about how to implement tokens.


    Note: As a best practice, use token entities to create a charge. This is the preferred way to send credit card information and maintain PCI compliance. Using the card endpoint directly may require you to get your app PCI-certified.


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


    Available operations:POST/Create

    GET/Read

    Delete'
paths:
  /quickbooks/v4/payments/tokens:
    post:
      operationId: createTokens
      summary: Create a token
      tags:
      - Tokens
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/tokens
      x-intuit-operation: "POST /quickbooks/v4/payments/tokens \nFOR IE8/IE9 - POST /quickbooks/v4/payments/tokens/ie\n\n"
      description: This POST operation lets you create token objects. Generated tokens automatically mask the bank account or credit card info associated with it.
      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/tokenrequest'
            example:
              card:
                name: emulate=0
                number: '4111111111111111'
                expMonth: '02'
                address:
                  postalCode: '94086'
                  country: US
                  region: CA
                  streetAddress: 1130 Kifer Rd
                  city: Sunnyvale
                expYear: '2020'
                cvc: '123'
        required: true
        description: 'To create a token object, include the following required attributes:bankAccount

          card'
      responses:
        '200':
          description: Returns a new token object. You can now use the token for transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token'
              example:
                value: bFy3h7W3D2tmOfYxl2msnLbUirY=
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
      x-intuit-alternate-operations:
      - POST /quickbooks/v4/payments/tokens/ie
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
    address:
      type: object
      title: address
      properties:
        PostalCode:
          type: string
          description: "The postal code for the address. For US and Canada, this is the zip code. \n\nRequired if no region is provided."
          x-intuit-required: Conditionally Required
        City:
          type: string
          description: The city name for the address.
          x-intuit-required: Optional
        StreetAddress:
          type: string
          description: The full street adddress. This may include the house number and street name (CR acceptable).
          x-intuit-required: Optional
        Region:
          type: string
          description: 'Specifies the region within a country. This is the state, province, prefecture, or region name.


            For the US, this is the state name. For Canada, this is the province name.


            Required if no postal code is provided.'
          x-intuit-required: Condtionally Required
        Country:
          type: string
          description: The ISO-standard country code. Refer to the ISO Country Code List.
          x-intuit-required: Optional
    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
    zerodollarverification:
      type: object
      title: zerodollarverification
      properties:
        Status:
          type: string
          description: Denotes the verification status of the credit or debit card.
        TransactionId:
          type: string
          description: The ID of the transaction (if returned) from the verification service.
          x-intuit-required: Optional
        Type:
          type: string
          description: Contains information about type of verification used to verify the creidt or debit card. It can be $0auth with card networks, or be an internal Intuit service
          x-intuit-required: Optional
    card:
      type: object
      title: card
      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
        Name:
          type: string
          description: The name of the credit or debit card holder, as it appears on the card.
          x-intuit-required: Optional
        IsLevel3Eligible:
          type: boolean
          description: Flag set to true if the credit or debit card falls into the L3 eligible Bank Identification Number (BIN) range.
          x-intuit-required: Response Only
        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.
        Default:
          type: boolean
          description: "Indicates if the credit or debit card is the default. When users set a default, the flag is true.\n\nThis is the credit or debit card QuickBooks uses when another isn't specified. \n\nThe flag defaults to false.\n\nWhen a credit or debit card flag is true, all other cards are automatically set to false."
          x-intuit-required: Optional
        entityType:
          type: string
          description: 'The entity or user type the card is associated with. Example values: Customer, Employee, Vendor or Company.'
        CommercialCardCode:
          type: string
          description: 'A code that indicates if the card is a commercial or corporate card.


            This can be used to track specific business purchases.'
          x-intuit-required: Optional
        Number:
          type: string
          description: The credit or debit card number.
          x-intuit-required: Required
        ExpMonth:
          type: string
          description: The card's two digit expiration month.
          x-intuit-required: Required
        CardType:
          type: object
          x-intuit-type: Enumerator
          description: 'The type of credit or debit card.


            Valid values:VISA

            MC

            AMEX

            DISC

            DINERS

            JCB'
          x-intuit-required: Conditionally required
        Address:
          allOf:
          - $ref: '#/components/schemas/address'
          description: The cardholder's full address.
          x-intuit-required: Optional
        ExpYear:
          type: string
          description: The card's four digit expiration year.
          x-intuit-required: Required
        entityId:
          type: string
          description: The ID of the entity the card is associated with.
        IsBusiness:
          type: boolean
          description: This flag is set to true if the credit or debit card is a business card.
          x-intuit-required: Optional
        Id:
          type: string
          description: The unique identifier for the card object.
          x-intuit-required: Conditionally required
        Cvc:
          type: string
          description: "The Card Verification Code (CVC) on the back of the card.\n\n This can be up to four digits. The number varies by card provider. \n\n For security purposes, the CVC value can't be stored. It must be supplied in transaction requests and then erased."
          x-intuit-required: Required
        zeroDollarVerification:
          allOf:
          - $ref: '#/components/schemas/zerodollarverification'
          description: Stores card verification information.
          x-intuit-required: Response Only
      required:
      - Cvc
      - ExpMonth
      - ExpYear
      - Number
    token:
      type: object
      title: token
      properties:
        Value:
          type: string
          description: The ID of the system generated token. Learn more about the token entity.
          x-intuit-required: Required
      required:
      - Value
    tokenrequest:
      type: object
      title: tokenrequest
      properties:
        BankAccount:
          allOf:
          - $ref: '#/components/schemas/bankaccount'
          description: The bank account associated with this charge. Required if a card isn't specified.
          x-intuit-required: Conditionally Required
        Card:
          allOf:
          - $ref: '#/components/schemas/card'
          description: The credit card associated with the token. Required if a  bankAccount  isn't specified.
          x-intuit-required: Conditionally Required
  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.