QuickBooks: Create a charge

← payments_charges operations · Get started · OpenAPI downloads

Contract 2026-10-20 · Operation quickbooks.payments.charges.create_a_charge

Provider route: POST /quickbooks/v4/payments/charges. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/quickbooks with npm, or alter-sdk-quickbooks with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { QuickBooksIntegration } from "@alter-ai/quickbooks";

async function execute(input: Parameters<QuickBooksIntegration["paymentsCharges"]["create"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new QuickBooksIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.paymentsCharges.create(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_quickbooks import QuickBooksIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = QuickBooksIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.payments_charges.create(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
headers	object	Required within parent	Additional keys: not allowed
headers.request-Id	string	Required within parent	The request-Id that uniquely identifies the HTTP request sent by your app to the server. This lets apps correlate requests and responses in case it needs to resend a request due to a dropped connection. Maximum length: 50
body	object	Required within parent	Additional keys: not allowed
body.amount	JSON	Required within parent	Amount of the transaction. Valid values range 0.00 through 99999.99. Decimal string
body.amount (anyOf 1)	number	Alternative
body.amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.authCode	string	Optional	The authorization code for the charge. Note : This is only available for uncaptured charges.
body.avsStreet	string	Optional	The address verification service (AVS). This service verifies the street address submitted by the customer for their credit or debit card. AVS compares the ZIP code submitted at the time of the transaction with what’s on file at the cardholder’s bank. AVS is supported by most US banks and some international banks. Valid responses: Pass Fail NotAvailable
body.avsZip	string	Optional	The address verification service (AVS). This service verifies the ZIP code submitted by the customer for their credit or debit card. AVS compares the ZIP code submitted at the time of the transaction with what’s on file at the cardholder’s bank. AVS is supported by most US banks and some international banks. Valid responses: Pass Fail NotAvailable
body.capture	JSON	Optional	Capture flag. Valid values include: true —The charge has been captured. false —The charge is uncaptured and pending authorization.
body.capture (anyOf 1)	boolean	Alternative
body.capture (anyOf 2)	string	Alternative	One of: true, false
body.captureDetail	Model	Optional	Expand Create a charge — request body — body capture Detail Details about the captured charge. Available for previously authorized charges. Read only: true
body.card	Model	Optional	Expand Create a charge — request body — body card Token is preferred in order to avoid PCI compliance requirements. Explicit credit card or debit card details associated with this charge. Required if neither token nor cardOnFile are specified.
body.cardSecurityCodeMatch	string	Optional	The 3 or 4 digit card security code number that appears on credit and debit cards. This number is not part of the main credit card number. This field indicates if the security code submitted at the time of the transaction matches what’s on file at the cardholder’s bank. Valid responses: Pass Fail NotAvailable
body.context	Model	Required within parent	Expand Create a charge — request body — body context Additional data you wish to store for this transaction.
body.created	string	Optional	The time the object was originally created. In ISO 8601 date-time format. It appears as YYYY-MM-DDTHH:MM:SSZ . Read only: true
body.currency	string	Required within parent	Three-letter ISO 4217 currency code representing the currency in which the charge was made.
body.description	string	Optional	Additional text details to be associated with the charge.
body.id	string	Optional	The unique identifier for the charge. This is a system-generated alpha-numeric ID. Conditionally required
body.refundDetail	array	Optional
body.refundDetail[]	Model	Each item	Expand Create a charge — request body — body refund Detail item Details for one or more refunds applied to this charge.
body.status	string	Optional	The status of the charge. Charge athorization and capture are a two part process. Learn more about charge states for the QuickBookls Payments API. Valid values: AUTHORIZED : The card’s issuing bank has authorized the cardholder’s ability to pay. This ensures the credit or debit card account is in good standing with sufficient funds. DECLINED : The card authorization was declined, rejected by the payment transaction service (PTS), or returned by the payment processor. CAPTURED : The payment is in the second part of the two-step authorization and capture process. CANCELLED : The transaction was cancelled. SETTLED : The payment was successfully funded. The money moved to the seller’s (i.e. merchant’s) bank account. At this point, the charge is complete. REFUNDED : The money successfully transferred back to the buyer (i.e. card holder). Read only: true
body.token	string	Optional	Preferred to specifying card or cardOnFile in order to ensure PCI compliance. Opaque representation of the credit card or debit card associated with this charge, as returned by the token endpoint. Applications that access cardholder information using the Payments API are required to follow the payment application data security standard (PA DSS) established by the payment card industry, which specifies how cardholder data must be protected. As such, the token resource provides a programatic way to comply with this standard without having to hold sensitive card information on your own servers.
body.cardOnFile	string	Optional	The id for a card that has been previously stored on file. Required if neither token nor card are specified.
body (anyOf 1)	JSON	Alternative
body (anyOf 2)	JSON	Alternative
body (anyOf 3)	JSON	Alternative

Referenced models: Create a charge — request body — body capture Detail, Create a charge — request body — body card, Create a charge — request body — body context, Create a charge — request body — body refund Detail item

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a charge — response body

Referenced models: Create a charge — response body

Policy, approvals and errors

SDK function policy ID: quickbooks.payments.charges.create_a_charge. Catalog operation: payments/charges/create_a_charge. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source