> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/api-reference/void.md).

# Void

## Overview

The `Void` RPC cancels an authorized payment before it has been captured. This releases the held funds back to the customer's payment method, effectively canceling the transaction without charging the customer.

**Business Use Case:** When a customer cancels their order before it ships, or an item is out of stock after authorization. Void is the appropriate action when no funds have been transferred yet. Unlike refunds (which return captured funds), voids prevent the charge from ever occurring.

## Purpose

**Why use Void instead of Refund?**

| Scenario                 | Developer Implementation                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **Order cancellation**   | Customer cancels before shipping - call `Void` with `connector_transaction_id` to release held funds                |
| **Out of stock**         | Item unavailable after authorization - call `Void` to cancel authorization, no charge appears on customer statement |
| **Fraud detection**      | Suspicious order flagged before capture - call `Void` to block the transaction entirely                             |
| **Duplicate prevention** | Accidental double authorization - call `Void` on the duplicate to release the hold                                  |
| **Price adjustment**     | Order total needs to change - `Void` the original, create new authorization with correct amount                     |

**Key outcomes:**

* No charge appears on customer's statement (authorization disappears within 1-3 business days)
* Funds immediately available to customer (vs. 5-10 days for refunds)
* Transaction moves to VOIDED status
* No settlement fees (vs. refund processing fees)

## Request Fields

| Field                      | Type               | Required | Description                                                    |
| -------------------------- | ------------------ | -------- | -------------------------------------------------------------- |
| `merchant_void_id`         | string             | Yes      | Your unique identifier for this void operation                 |
| `connector_transaction_id` | string             | Yes      | The connector's transaction ID from the original authorization |
| `cancellation_reason`      | string             | No       | Reason for canceling the authorization                         |
| `all_keys_required`        | bool               | No       | Whether all key fields must match for void to succeed          |
| `browser_info`             | BrowserInformation | No       | Browser details for 3DS verification                           |
| `amount`                   | Money              | No       | Amount to void (for partial voids)                             |
| `metadata`                 | SecretString       | No       | Additional metadata for the connector                          |
| `connector_feature_data`   | SecretString       | No       | Connector-specific metadata for the transaction                |
| `state`                    | ConnectorState     | No       | State from previous multi-step flow                            |
| `test_mode`                | bool               | No       | Process as test transaction                                    |
| `merchant_order_id`        | string             | No       | Your internal order ID for reference                           |

## Response Fields

| Field                               | Type                 | Description                                                   |
| ----------------------------------- | -------------------- | ------------------------------------------------------------- |
| `connector_transaction_id`          | string               | Connector's transaction ID                                    |
| `status`                            | PaymentStatus        | Current status. Values: VOIDED, VOID\_INITIATED, VOID\_FAILED |
| `error`                             | ErrorInfo            | Error details if status is VOID\_FAILED                       |
| `status_code`                       | uint32               | HTTP-style status code (200, 402, etc.)                       |
| `response_headers`                  | map\<string, string> | Connector-specific response headers                           |
| `merchant_transaction_id`           | string               | Your transaction reference (echoed back)                      |
| `state`                             | ConnectorState       | State to pass to next request in multi-step flow              |
| `raw_connector_request`             | SecretString         | Raw API request sent to connector (debugging)                 |
| `mandate_reference`                 | MandateReference     | Mandate details if recurring payment                          |
| `incremental_authorization_allowed` | bool                 | Whether amount can be increased later                         |
| `connector_feature_data`            | SecretString         | Connector-specific metadata for the transaction               |

## Example

### Request (grpcurl)

```bash
grpcurl -H "x-connector: stripe" \
  -H "x-connector-config: {\"config\":{\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}}" \
  -d '{
    "merchant_void_id": "void_001",
    "connector_transaction_id": "pi_3Oxxx...",
    "cancellation_reason": "Customer requested cancellation",
    "merchant_order_id": "order-001",
    "test_mode": true
  }' \
  localhost:8080 \
  types.PaymentService/Void
```

### Response

```json
{
  "connector_transaction_id": "pi_3Oxxx...",
  "status": "VOIDED",
  "status_code": 200
}
```

## Next Steps

* [Authorize](/integrations/prism/api-reference/authorize.md) - Authorize a new payment
* [Capture](/integrations/prism/api-reference/capture.md) - Finalize the payment and transfer funds
* [Get](/integrations/prism/api-reference/get.md) - Check current payment status


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hyperswitch.io/integrations/prism/api-reference/void.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.