QuickBooks: Void or refund an e Check

← payments_echecks operations · Get started · OpenAPI downloads

Contract 2026-10-20 · Operation quickbooks.payments.echecks.void_or_refund_an_e_check

Provider route: POST /quickbooks/v4/payments/echecks/{echeck_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["paymentsEchecks"]["void"]>[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.paymentsEchecks.void(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_echecks.void(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
query.id	string	Optional	The id of the eCheck. The ID is defined in the response of the CREATE check operation.
path	object	Required within parent	Additional keys: not allowed
path.echeck_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 amount to be refunded. 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 echeck.
body.bankAccount	Model	Optional	Expand Void or refund an e Check — request body — body bank Account
body.bankAccountOnFile	string	Optional	An existing bank account that was previously stored. Specify the ID of the existing bank account. Required if the token or bankAccount aren’t specified.
body.checkNumber	string	Optional	The number of the eCheck associated with the transaction. This number must be unique. Using the same checkNumber to create multiple eChecks will result in declines.
body.context	Model	Optional	Expand Create an e Check — request body — body context Additional info that will be stored with the 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.description	string	Optional	A description of the refund. Maximum length: 4000
body.id	string	Optional	The unique identifier for the eCheck. Conditionally required
body.paymentMode	string	Optional	The payment mode. This is also known as the SEC Code. Valid values: WEB : Internet-initiated entry mode used for internet transactions.
body.status	string	Optional	The current status of the check. Learn more about check states . Valid values types: PENDING : The check is being processed. SUCCEEDED : The check was funded and the transaction is complete. DECLINED : The check was rejected. VOIDED : The check was voided. REFUNDED : The check was refunded. Read only: true
body.token	string	Optional	The opaque container for the credit or debit card account associated with the transaction. Required if the bankAccount or bankAccountOnFile aren’t specified. Learn more about creating tokens.

Referenced models: Void or refund an e Check — request body — body bank Account, Create an e Check — request body — body context

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 an e Check — response body

Referenced models: Create an e Check — response body

Policy, approvals and errors

SDK function policy ID: quickbooks.payments.echecks.void_or_refund_an_e_check. Catalog operation: payments/echecks/void_or_refund_an_e_check. 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