Skip to main content

Payments

Tool types that drive the QuickBooks Payments API: tokenizing cards and bank accounts, charging and refunding them, storing payment methods on customers, and composites that collapse tokenize-store-charge sequences into one call.

Every type on this page requires a QuickBooks connector whose Intuit company has a QuickBooks Payments merchant account; connectorId is the ID of that connector. Unlike the accounting families, these tools move real money in production — sandbox connectors hit Intuit's sandbox Payments endpoint and accept test card and bank numbers. Charges and refunds here do not write accounting entries by themselves; the *_AND_RECORD_* composites here and on the Workflows page bridge the two sides.

Tokenize card TOOLQUICKBOOKS_TOKENIZE_CARD​

Exchanges raw card details for a single-use payment token, so downstream calls never carry the card number. Tokens are short-lived — spend the token promptly with QUICKBOOKS_CHARGE_CARD or store it with QUICKBOOKS_CREATE_CARD, or use the tokenize-and-* composites to do both steps atomically.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_CARD",
  "connectorId": "V1StGXR8Z5",
  "cardNumber": "@@{cardNumber}",
  "expMonth": "@@{expMonth}",
  "expYear": "@@{expYear}",
  "cvc": "@@{cvc}",
  "cardHolderName": "@@{cardHolderName}",
  "addressPostalCode": "@@{billingZip}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    cardNumber
    Type
    string
    Description
    Credit card number
  • Name
    expMonth
    Type
    string
    Description
    Expiration month (MM)
  • Name
    expYear
    Type
    string
    Description
    Expiration year (YYYY)
  • Name
    cvc
    Type
    string
    Description
    Card verification code
  • Name
    cardHolderName
    Type
    string
    Description
    Name on card
  • Name
    addressStreet
    Type
    string
    Description
    Billing address street
  • Name
    addressCity
    Type
    string
    Description
    Billing address city
  • Name
    addressRegion
    Type
    string
    Description
    Billing address state/region
  • Name
    addressPostalCode
    Type
    string
    Description
    Billing address postal code
  • Name
    addressCountry
    Type
    string
    Description
    Billing address country (ISO code)

Tokenize bank account TOOLQUICKBOOKS_TOKENIZE_BANK_ACCOUNT​

Exchanges bank account details (routing and account number) for a single-use token for ACH eCheck processing. accountType is one of PERSONAL_CHECKING, PERSONAL_SAVINGS, BUSINESS_CHECKING, or BUSINESS_SAVINGS. Pair with QUICKBOOKS_PROCESS_ECHECK or the tokenize-and-* composites.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_BANK_ACCOUNT",
  "connectorId": "V1StGXR8Z5",
  "routingNumber": "@@{routingNumber}",
  "accountNumber": "@@{accountNumber}",
  "accountType": "PERSONAL_CHECKING",
  "accountHolderName": "@@{accountHolderName}",
  "phone": "@@{phone}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    routingNumber
    Type
    string
    Description
    Bank routing number (9 digits)
  • Name
    accountNumber
    Type
    string
    Description
    Bank account number
  • Name
    accountType
    Type
    string
    Description
    PERSONAL_CHECKING, PERSONAL_SAVINGS, BUSINESS_CHECKING, BUSINESS_SAVINGS
  • Name
    accountHolderName
    Type
    string
    Description
    Name on account
  • Name
    phone
    Type
    string
    Description
    Account holder phone

Create card TOOLQUICKBOOKS_CREATE_CARD​

Stores a tokenized card on a QuickBooks customer as a reusable payment method, returning a permanent cardId. The cardToken must come from a fresh QUICKBOOKS_TOKENIZE_CARD call; isDefault makes it the customer's default method.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_CREATE_CARD",
  "connectorId": "V1StGXR8Z5",
  "customerId": "@@{customerId}",
  "cardToken": "@@{cardToken}",
  "isDefault": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    customerId
    Type
    string
    Description
    QuickBooks customer ID
  • Name
    cardToken
    Type
    string
    Description
    Token from tokenizeCard
  • Name
    isDefault
    Type
    boolean
    Description
    Set as default payment method

Charge card TOOLQUICKBOOKS_CHARGE_CARD​

Charges a card for amount — pass either a one-time cardToken or a stored cardId (with its owning customerId), never both. capture defaults to true; set it false to authorize only. This processes money but books nothing; use QUICKBOOKS_CHARGE_AND_RECORD_PAYMENT on the Workflows page to also write the accounting entry.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_CHARGE_CARD",
  "connectorId": "V1StGXR8Z5",
  "amount": 450.00,
  "currency": "USD",
  "cardToken": "@@{cardToken}",
  "capture": true,
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    amount
    Type
    number
    Description
    Charge amount
  • Name
    currency
    Type
    string
    Description
    Currency code (USD, etc.)
  • Name
    cardToken
    Type
    string
    Description
    Token for one-time payment (use this OR cardId)
  • Name
    cardId
    Type
    string
    Description
    Stored card ID (use this OR cardToken)
  • Name
    customerId
    Type
    string
    Description
    Customer ID (required if using cardId)
  • Name
    capture
    Type
    boolean
    Description
    Whether to capture immediately (default true)
  • Name
    description
    Type
    string
    Description
    Payment description

Process eCheck TOOLQUICKBOOKS_PROCESS_ECHECK​

Debits a bank account via ACH — pass either a one-time bankAccountToken or a stored bankAccountId (with its customerId). paymentMode is the ACH authorization class (WEB default, TEL, CCD, PPD). ACH settles over days rather than instantly, so treat the result as initiated, not cleared.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_PROCESS_ECHECK",
  "connectorId": "V1StGXR8Z5",
  "amount": 450.00,
  "bankAccountToken": "@@{bankAccountToken}",
  "paymentMode": "WEB",
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    amount
    Type
    number
    Description
    Payment amount
  • Name
    bankAccountToken
    Type
    string
    Description
    Token for one-time payment (use this OR bankAccountId)
  • Name
    bankAccountId
    Type
    string
    Description
    Stored bank account ID (use this OR bankAccountToken)
  • Name
    customerId
    Type
    string
    Description
    Customer ID (required if using bankAccountId)
  • Name
    paymentMode
    Type
    string
    Description
    WEB (default), TEL, CCD, PPD
  • Name
    description
    Type
    string
    Description
    Payment description

Refund charge TOOLQUICKBOOKS_REFUND_CHARGE​

Refunds a card charge by chargeId, back to the original card. Omit amount for a full refund or set it for a partial one. The refund is Payments-API-only; QUICKBOOKS_REFUND_CHARGE_AND_RECORD_CREDIT below also books the credit memo.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_REFUND_CHARGE",
  "connectorId": "V1StGXR8Z5",
  "chargeId": "@@{chargeId}",
  "amount": 450.00,
  "description": "@@{refundReason}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    chargeId
    Type
    string
    Description
    ID of the charge to refund
  • Name
    amount
    Type
    number · optional
    Description
    Refund amount (optional for partial refund)
  • Name
    description
    Type
    string
    Description
    Refund description/reason

Refund eCheck TOOLQUICKBOOKS_REFUND_ECHECK​

Refunds an ACH eCheck payment by echeckId, in full (omit amount) or partially. eCheck refunds can only be issued once the original debit has settled, so a refund immediately after processing may be rejected.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_REFUND_ECHECK",
  "connectorId": "V1StGXR8Z5",
  "echeckId": "@@{echeckId}",
  "description": "@@{refundReason}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    echeckId
    Type
    string
    Description
    ID of the eCheck to refund
  • Name
    amount
    Type
    number · optional
    Description
    Refund amount (optional for partial refund)
  • Name
    description
    Type
    string
    Description
    Refund description/reason

Tokenize and charge TOOLQUICKBOOKS_TOKENIZE_AND_CHARGE​

Tokenizes raw card details and charges the token in one call — the standard way to take a one-off card payment without juggling short-lived tokens across tool calls. The card is not stored; for repeat billing use QUICKBOOKS_TOKENIZE_AND_STORE_CARD instead.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_AND_CHARGE",
  "connectorId": "V1StGXR8Z5",
  "amount": 450.00,
  "currency": "USD",
  "cardNumber": "@@{cardNumber}",
  "expMonth": "@@{expMonth}",
  "expYear": "@@{expYear}",
  "cvc": "@@{cvc}",
  "cardHolderName": "@@{cardHolderName}",
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    amount
    Type
    number
    Description
    Charge amount
  • Name
    currency
    Type
    string
    Description
    Currency code (USD, etc.)
  • Name
    cardNumber
    Type
    string
    Description
    Credit card number
  • Name
    expMonth
    Type
    string
    Description
    Expiration month (MM)
  • Name
    expYear
    Type
    string
    Description
    Expiration year (YYYY)
  • Name
    cvc
    Type
    string
    Description
    Card verification code
  • Name
    cardHolderName
    Type
    string
    Description
    Name on card
  • Name
    description
    Type
    string
    Description
    Payment description

Tokenize and process eCheck TOOLQUICKBOOKS_TOKENIZE_AND_PROCESS_ECHECK​

Tokenizes bank account details and initiates the ACH debit in one call — the eCheck counterpart of tokenize-and-charge. The bank account is not stored for reuse; that's QUICKBOOKS_TOKENIZE_AND_STORE_BANK_ACCOUNT.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_AND_PROCESS_ECHECK",
  "connectorId": "V1StGXR8Z5",
  "amount": 450.00,
  "routingNumber": "@@{routingNumber}",
  "accountNumber": "@@{accountNumber}",
  "accountType": "PERSONAL_CHECKING",
  "accountHolderName": "@@{accountHolderName}",
  "paymentMode": "WEB",
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    amount
    Type
    number
    Description
    Payment amount
  • Name
    routingNumber
    Type
    string
    Description
    Bank routing number
  • Name
    accountNumber
    Type
    string
    Description
    Bank account number
  • Name
    accountType
    Type
    string
    Description
    PERSONAL_CHECKING, PERSONAL_SAVINGS, etc.
  • Name
    accountHolderName
    Type
    string
    Description
    Name on account
  • Name
    paymentMode
    Type
    string
    Description
    WEB, TEL, CCD, PPD
  • Name
    description
    Type
    string
    Description
    Payment description

Tokenize and store card TOOLQUICKBOOKS_TOKENIZE_AND_STORE_CARD​

Tokenizes a card and stores it on an existing customer in one call, returning a permanent cardId for later QUICKBOOKS_CHARGE_STORED_CARD calls. Nothing is charged. If the customer record may not exist yet, QUICKBOOKS_SETUP_CUSTOMER_PAYMENT_METHOD below handles that too.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_AND_STORE_CARD",
  "connectorId": "V1StGXR8Z5",
  "customerId": "@@{customerId}",
  "cardNumber": "@@{cardNumber}",
  "expMonth": "@@{expMonth}",
  "expYear": "@@{expYear}",
  "cvc": "@@{cvc}",
  "cardHolderName": "@@{cardHolderName}",
  "isDefault": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    customerId
    Type
    string
    Description
    Customer to store card for
  • Name
    cardNumber
    Type
    string
    Description
    Credit card number
  • Name
    expMonth
    Type
    string
    Description
    Expiration month (MM)
  • Name
    expYear
    Type
    string
    Description
    Expiration year (YYYY)
  • Name
    cvc
    Type
    string
    Description
    Card verification code
  • Name
    cardHolderName
    Type
    string
    Description
    Name on card
  • Name
    isDefault
    Type
    boolean
    Description
    Set as default payment method

Tokenize and store bank account TOOLQUICKBOOKS_TOKENIZE_AND_STORE_BANK_ACCOUNT​

Tokenizes a bank account and stores it on an existing customer in one call, returning a permanent bankAccountId for later QUICKBOOKS_CHARGE_STORED_BANK_ACCOUNT calls. Nothing is debited at store time.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_TOKENIZE_AND_STORE_BANK_ACCOUNT",
  "connectorId": "V1StGXR8Z5",
  "customerId": "@@{customerId}",
  "routingNumber": "@@{routingNumber}",
  "accountNumber": "@@{accountNumber}",
  "accountType": "PERSONAL_CHECKING",
  "accountHolderName": "@@{accountHolderName}",
  "isDefault": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    customerId
    Type
    string
    Description
    Customer to store bank account for
  • Name
    routingNumber
    Type
    string
    Description
    Bank routing number
  • Name
    accountNumber
    Type
    string
    Description
    Bank account number
  • Name
    accountType
    Type
    string
    Description
    PERSONAL_CHECKING, PERSONAL_SAVINGS, etc.
  • Name
    accountHolderName
    Type
    string
    Description
    Name on account
  • Name
    phone
    Type
    string
    Description
    Account holder phone
  • Name
    isDefault
    Type
    boolean
    Description
    Set as default payment method

Charge stored card TOOLQUICKBOOKS_CHARGE_STORED_CARD​

Charges a card previously stored on a customer, identified by customerId plus cardId — no card details or fresh token needed. This is the repeat-billing workhorse for customers set up via the store composites.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_CHARGE_STORED_CARD",
  "connectorId": "V1StGXR8Z5",
  "customerId": "@@{customerId}",
  "cardId": "@@{cardId}",
  "amount": 450.00,
  "currency": "USD",
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    customerId
    Type
    string
    Description
    Customer ID who owns the card
  • Name
    cardId
    Type
    string
    Description
    Stored card ID
  • Name
    amount
    Type
    number
    Description
    Charge amount
  • Name
    currency
    Type
    string
    Description
    Currency code (USD, etc.)
  • Name
    description
    Type
    string
    Description
    Payment description

Charge stored bank account TOOLQUICKBOOKS_CHARGE_STORED_BANK_ACCOUNT​

Debits a bank account previously stored on a customer via ACH, identified by customerId plus bankAccountId. paymentMode carries the ACH authorization class, and the same settlement-delay caveat as QUICKBOOKS_PROCESS_ECHECK applies.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_CHARGE_STORED_BANK_ACCOUNT",
  "connectorId": "V1StGXR8Z5",
  "customerId": "@@{customerId}",
  "bankAccountId": "@@{bankAccountId}",
  "amount": 450.00,
  "paymentMode": "WEB",
  "description": "@@{paymentDescription}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    customerId
    Type
    string
    Description
    Customer ID who owns the bank account
  • Name
    bankAccountId
    Type
    string
    Description
    Stored bank account ID
  • Name
    amount
    Type
    number
    Description
    Payment amount
  • Name
    paymentMode
    Type
    string
    Description
    WEB, TEL, CCD, PPD
  • Name
    description
    Type
    string
    Description
    Payment description

Setup customer payment method TOOLQUICKBOOKS_SETUP_CUSTOMER_PAYMENT_METHOD​

The full onboarding composite: finds the customer by email (creating one if missing), then tokenizes and stores the payment method on them. paymentMethodType selects CARD (card fields required) or BANK_ACCOUNT (bank fields required), so one tool config can onboard either kind. Returns the customer, whether it was created, and the stored method.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_SETUP_CUSTOMER_PAYMENT_METHOD",
  "connectorId": "V1StGXR8Z5",
  "email": "@@{customerEmail}",
  "displayName": "@@{customerName}",
  "paymentMethodType": "CARD",
  "cardNumber": "@@{cardNumber}",
  "expMonth": "@@{expMonth}",
  "expYear": "@@{expYear}",
  "cvc": "@@{cvc}",
  "cardHolderName": "@@{cardHolderName}",
  "setAsDefault": true
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    email
    Type
    string
    Description
    Customer email (primary search key)
  • Name
    displayName
    Type
    string
    Description
    Customer display name
  • Name
    givenName
    Type
    string
    Description
    First name
  • Name
    familyName
    Type
    string
    Description
    Last name
  • Name
    paymentMethodType
    Type
    string
    Description
    CARD or BANK_ACCOUNT
  • Name
    cardNumber
    Type
    string
    Description
    Required string value.
  • Name
    expMonth
    Type
    string
    Description
    Required string value.
  • Name
    expYear
    Type
    string
    Description
    Required string value.
  • Name
    cvc
    Type
    string
    Description
    Required string value.
  • Name
    cardHolderName
    Type
    string
    Description
    Required string value.
  • Name
    routingNumber
    Type
    string
    Description
    Required string value.
  • Name
    accountNumber
    Type
    string
    Description
    Required string value.
  • Name
    accountType
    Type
    string
    Description
    Required string value.
  • Name
    accountHolderName
    Type
    string
    Description
    Required string value.
  • Name
    phone
    Type
    string
    Description
    Required string value.
  • Name
    setAsDefault
    Type
    boolean
    Description
    Required boolean value.

Refund charge and record credit TOOLQUICKBOOKS_REFUND_CHARGE_AND_RECORD_CREDIT​

Refunds a card charge and books a matching credit memo against the customer in the same call, keeping the Payments side and the ledger in sync. Omit amount for a full refund; reason lands on both the refund and the credit memo.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_REFUND_CHARGE_AND_RECORD_CREDIT",
  "connectorId": "V1StGXR8Z5",
  "chargeId": "@@{chargeId}",
  "customerId": "@@{customerId}",
  "reason": "@@{refundReason}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    chargeId
    Type
    string
    Description
    Charge ID to refund
  • Name
    customerId
    Type
    string
    Description
    Customer ID for credit memo
  • Name
    amount
    Type
    number · optional
    Description
    Refund amount (optional for full refund)
  • Name
    reason
    Type
    string
    Description
    Refund reason/description

Refund eCheck and record credit TOOLQUICKBOOKS_REFUND_ECHECK_AND_RECORD_CREDIT​

The ACH counterpart: refunds an eCheck by echeckId and books the matching credit memo against the customer in one call. The eCheck must have settled before it can be refunded, same as the plain refund tool.

Example​

Tool config
{
  "toolType": "QUICKBOOKS_REFUND_ECHECK_AND_RECORD_CREDIT",
  "connectorId": "V1StGXR8Z5",
  "echeckId": "@@{echeckId}",
  "customerId": "@@{customerId}",
  "reason": "@@{refundReason}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    echeckId
    Type
    string
    Description
    eCheck ID to refund
  • Name
    customerId
    Type
    string
    Description
    Customer ID for credit memo
  • Name
    amount
    Type
    number · optional
    Description
    Refund amount (optional for full refund)
  • Name
    reason
    Type
    string
    Description
    Refund reason/description