Sets a transaction to void, ending the transaction before it's processed.
The Void Transaction endpoint allows you to cancel a transaction before it is processed (settled). Voiding a transaction prevents it from being captured and stops any associated fees from being assessed. When a transaction is voided, a child transaction with type = void is created and linked to the original transaction.
Key Points
Timing is Critical: Transactions can only be voided before they have been batched (settled). Transactions typically batch around 8 pm EST, but this can vary based on merchant configurations. In some cases, the window to void a transaction is very small.
Irreversible Action: Once a transaction is batched, it cannot be voided. You must issue a refund instead.
Child Transactions: The void action results in a new child transaction linked to the original transaction for tracking purposes.
Testing Environment:
In a sandbox account, transactions are not refundable until 12 am EST.
Settlement Tokenization Considerations:
If your merchant account has Settlement Tokenization enabled and the transaction is not yet available for a refund, this endpoint will return a status code 422 with the message:
This transaction is not yet available to be refunded via API. You can still complete this transaction through the card present flow.
In such cases, you may use the POST /terminal/void-or-refund endpoint instead.
Usage Notes
Void Eligibility: Before attempting to void a transaction, check if it is eligible by verifying it has not been batched. The is_voidable flag on the transaction object can help determine this.
No Partial Voids: Partial voids are not supported. You must void the entire transaction amount.
Error Handling: If a void request is sent after the transaction has been batched, the API will return an error indicating the transaction cannot be voided.
Contact Support: For any uncertainties regarding the void window or transaction statuses, reach out to support for assistance.
Response Structure
| Code | Response | Reason |
|---|---|---|
| 200 | Success | Returns the original transaction object with an added child transaction of type = void. |
| 400 | Bad Request | Invalid request parameters. |
| 401 | Unauthorized | Authentication failed. |
| 404 | Not Found | Transaction ID does not exist. |
| 422 | Unprocessable Entity | Transaction cannot be voided (e.g., already batched). |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
Alternative Endpoint
POST /transaction/{id}/void-or-refund: This endpoint automatically determines whether to void or refund the transaction based on its status.
Important Considerations
Voiding vs. Refunding
Voiding is only possible before settlement. After settlement, you must process a refund.
Batch Times
Be aware of your merchant account's batch processing times to effectively manage voids.
Terminal Transactions
For transactions processed through terminals, and if Settlement Tokenization is enabled, you may need to use terminal-specific endpoints.