QuickBooks Cards API

openapi: 3.2.0
info:
  title: QuickBooks Payments Cards 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: Cards
  description: 'The card entity lets you create and store credit and debit card objects.


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


    Keep in mind, the card entity is the only way to store credit and debit card info using the QuickBooks Payments API. Apps can''t automatically store info from swiped transactions.


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


    Available operations:POST/Create

    GET/Read

    Delete'
paths:
  /quickbooks/v4/customers/{id}/cards:
    post:
      operationId: createCards
      summary: Create a card
      tags:
      - Cards
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/cards
      x-intuit-operation: POST /quickbooks/v4/customers/<id>/cards
      description: 'This POST operation lets you create and store credit or debit card objects.


        Keep in mind, the card object is only accessible via the QuickBooks Payments API. It won''t appear in QuickBooks Online.'
      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: 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 customer your app is creating the card for. \n\nIf you're using the QuickBooks Online Accounting API, you can use the Customer, Vendor, or Employee entity to get their ID. This value can be stored in QuickBooks or your app."
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cardrequest'
            example:
              expMonth: '12'
              address:
                postalCode: '44112'
                city: Richmond
                streetAddress: 1245 Hana Rd
                region: VA
                country: US
              number: '4408041234567893'
              name: Test User
              expYear: '2026'
        required: true
        description: 'To create a card object, include the following required attributes:number

          expMonth

          expYear

          cvc

          You can also include optional attributes:name

          default

          commercialCardCode

          address

          isBusiness'
      responses:
        '200':
          description: Returns a new credit or debit card object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
              example:
                updated: '2015-03-25T22:24:33Z'
                name: Test User
                created: '2015-03-25T22:24:33Z'
                default: false
                number: xxxxxxxxxxxx7893
                expMonth: '12'
                address:
                  postalCode: '44112'
                  city: Richmond
                  region: VA
                  streetAddress: 1245 Hana Rd
                  country: US
                expYear: '2026'
                isBusiness: false
                id: '101101015602106732027893'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
    get:
      operationId: readCards
      summary: Get a list of cards for a specific customer
      tags:
      - Cards
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/cards
      x-intuit-operation: GET /quickbooks/v4/customers/<id>/cards
      description: 'This GET operation gives you a list of up to 10 credit or debit cards.


        Use the id attribute to specify the customer or QuickBooks Online company (i.e. realmID). If you need info for more than 10 cards, specify the number at the end of the query ?count=[number]. For example, /cards?count=100 gets 100 cards.


        Important: This operation can''t retrieve cards users enter via the QuickBooks Online interface.'
      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: 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 customer your app is getting card info for.


          If you''re using the QuickBooks Online Accounting API, you can use the Customer, Vendor, or Employee entity to get their ID. This value can be stored in QuickBooks or your app.'
        required: true
      responses:
        '200':
          description: Returns a list of card objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
              example:
              - updated: '2015-03-25T22:24:33Z'
                expMonth: '12'
                name: Test User
                created: '2015-03-25T22:24:33Z'
                default: false
                number: xxxxxxxxxxxx7893
                cvvVerification:
                  date: '2015-03-25T22:24:33Z'
                  result: NOT_DONE
                address:
                  postalCode: '44112'
                  city: Richmond
                  region: VA
                  streetAddress: 1245 Hana Rd
                  country: US
                expYear: '2026'
                isBusiness: false
                id: '101101015602106732027893'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
  /quickbooks/v4/customers/{id}/cards/createFromToken:
    post:
      operationId: createCardFromToken
      summary: Create a card from a token
      tags:
      - Cards
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/cards
      x-intuit-operation: POST /quickbooks/v4/customers/<id>/cards/createFromToken
      description: This POST operation lets you use a token to create a credit or debit card object, instead of creating it manually.
      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: 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 customer your app is creating the card for. \n\nIf you're using the QuickBooks Online Accounting API, you can use the Customer, Vendor, or Employee entity to get their ID. This value can be stored in QuickBooks or your app."
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token'
            example:
              value: F+hgXXynTwwTi3B70MFysfj/s7o=
        required: true
        description: 'Specify the token value in your request:'
      responses:
        '200':
          description: Returns a new credit or debit card object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
              example:
                updated: '2015-03-25T22:24:33Z'
                name: Test User
                created: '2015-03-25T22:24:33Z'
                default: false
                number: xxxxxxxxxxxx7893
                expMonth: '12'
                address:
                  postalCode: '44112'
                  city: Richmond
                  region: VA
                  streetAddress: 1245 Hana Rd
                  country: US
                expYear: '2026'
                isBusiness: false
                id: '101101015602106732027893'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
  /quickbooks/v4/customers/{id}/cards/{card_id}:
    delete:
      operationId: deleteCards
      summary: Delete a card
      tags:
      - Cards
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/cards
      x-intuit-operation: DELETE /quickbooks/v4/customers/<id>/cards/<card_id>
      description: This DELETE operation lets you delete a specified credit or debit card object.
      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: id
        in: path
        required: true
        schema:
          type: string
      - name: card_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 customer you're deleting the card for. \n\nIf you're using the QuickBooks Online Accounting API, you can use the Customer, Vendor, or Employee entity to get their ID. This value can be stored in QuickBooks or your app."
        required: true
      - name: card_id
        in: query
        schema:
          type: string
        description: The ID of the card you plan to delete.
        required: true
      responses:
        '200':
          description: The response confirms the delete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
              example: {}
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
    get:
      operationId: getDetailsAboutCard
      summary: Get details about a card
      tags:
      - Cards
      x-source: https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/cards
      x-intuit-operation: GET /quickbooks/v4/customers/<id>/cards/<card_id>
      description: 'This GET operation gets info for a specific credit or debit card object.


        Use the idattribute to specify the customer or QuickBooks Online company (i.e. realmID).'
      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: id
        in: path
        required: true
        schema:
          type: string
      - name: card_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 customer your app is getting card info for. \n\nIf you're using the QuickBooks Online Accounting API, you can use the Customer, Vendor, or Employee entity to get their ID. This value can be stored in QuickBooks or your app."
        required: true
      - name: card_id
        in: query
        schema:
          type: string
        description: The card or debit card you want info for.
        required: true
      responses:
        '200':
          description: Returns info for the credit or debit card object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card'
              example:
                updated: '2015-03-25T22:24:33Z'
                expMonth: '12'
                name: Test User
                created: '2015-03-25T22:24:33Z'
                default: false
                number: xxxxxxxxxxxx7893
                cvvVerification:
                  date: '2015-03-25T22:24:33Z'
                  result: NOT_DONE
                address:
                  postalCode: '44112'
                  city: Richmond
                  region: VA
                  streetAddress: 1245 Hana Rd
                  country: US
                expYear: '2026'
                isBusiness: false
                id: '101101015602106732027893'
        '400':
          $ref: '#/components/responses/Fault'
        '401':
          $ref: '#/components/responses/Fault'
        '429':
          $ref: '#/components/responses/Throttled'
      security:
      - oauth2:
        - com.intuit.quickbooks.payment
components:
  schemas:
    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
    cardrequest:
      type: object
      title: cardrequest
      properties:
        Name:
          type: string
          description: The name of the credit or debit card holder, as it appears on the card.
          x-intuit-required: Optional
        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
        Number:
          type: string
          description: The credit or debit card number.
          x-intuit-required: Required
        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
        ExpMonth:
          type: string
          description: The card's two digit expiration month.
          x-intuit-required: 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
        IsBusiness:
          type: boolean
          description: This flag is set to true if the credit or debit card is a business card.
          x-intuit-required: Optional
        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
      required:
      - Cvc
      - ExpMonth
      - ExpYear
      - Number
  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.