Skip to main content
Cancel (void) an authorized transaction before it is captured. This releases the hold on funds without charging the customer. Voiding is only applicable to authorizations, not to completed charges.

​
Method signature

async void(request: VoidRequest): Promise<VoidResult>

​
Parameters

​
body.transactionId
string
required
The transaction ID of the authorization to void.
​
body.idempotencyKey
string
Unique key to prevent duplicate void operations when retrying the same request.

​
Returns

​
VoidResult
object
Normalized void result containing cancellation details.

​
Error handling

The void() method may throw the following errors:
Thrown when an idempotency key is reused with different request data.
Thrown when the provider for the original transaction cannot be found.
The provider may return errors such as:
  • Authorization not found
  • Authorization already captured (cannot void a completed charge)
  • Authorization already voided
  • Authorization expired

​
Example

// Create authorization for hotel reservation
const authorization = await client.authorize({
  amount: 50000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  description: 'Hotel reservation - Room 305',
  idempotencyKey: 'auth-reservation-789'
});

console.log(authorization.status); // 'authorized'

// Customer cancels reservation
const voidResult = await client.void({
  transactionId: authorization.id,
  idempotencyKey: 'void-reservation-789'
});

console.log(voidResult.status); // 'completed'
// Hold is released, customer is not charged

​
Implementation details

The void operation (src/client/vault-client.ts:274-295):
  1. Looks up the provider that handled the original authorization using the transaction index
  2. Executes the void operation through the provider adapter
  3. Returns a VoidResult with minimal details (void operations don’t have amounts)
  4. Queues transaction report to the platform with amount set to 0
Void operations are processed through the same provider that handled the original authorization. The operation is immediate and releases the hold on funds.
You can only void authorizations that have not been captured yet. For completed charges, use refund() instead.

​
When to use void vs refund

Use void()

  • Transaction is authorized but not captured
  • Customer cancels before service/delivery
  • Want to release hold immediately
  • No funds have been transferred

Use refund()

  • Transaction is already captured/charged
  • Customer returns product after delivery
  • Need to return funds to customer
  • Funds have been transferred
Implement automatic voiding for authorizations that are not captured within a certain timeframe to ensure customers aren’t left with unnecessary holds on their cards.

​
Authorization lifecycle

1

Authorization created

Status is "authorized" and funds are on hold.
2

Decision point

You can either:
  • Call capture() to complete the charge
  • Call void() to cancel and release the hold
  • Wait for automatic expiration (typically 7 days)
3

Final state

  • If captured: status becomes "completed", funds are transferred
  • If voided: status becomes "cancelled", hold is released
  • If expired: hold is automatically released

Build docs developers (and LLMs) love

Get started for freeTalk to us