QuickBooks: Refund a charge

← payments_charges operations · Get started · OpenAPI downloads

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

Provider route: POST /quickbooks/v4/payments/charges/{id}/refunds. 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"]["refund"]>[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.refund(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.refund(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
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent	Minimum length: 1
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	The transaction amount. Valid values: Any value between 0.01 and 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	A flag that indicates if the charge was captured. Valid values: True : The charge was captured False : The charge wasn’t captured. It’s pending authorization. Defaults to true .
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 The credit or debit card used for the charge. Required if token isn’t specified. Conditionally required
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	Optional	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	Optional	The 3-letter ISO 4217 compliant currency code, which defines the currency for the charge.
body.description	string	Optional	Text info you want to store with the transaction.
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	The opaque container for the credit or debit card account associated with the transaction. Required if the card isn’t specified. Tokens are preferred to directly specifying a card or cardOnFile to comply with PCI standards. Learn more about creating tokens.

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.refund_a_charge. Catalog operation: payments/charges/refund_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