> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Void Session

POST https://dev-api.truemed.com/payments/v1/payment_session/{business_id}/void
Content-Type: application/json

The `void_payment_session` endpoint should be called after
[`create_payment_session`](/api-reference/payment-sessions/create-payment-session)
has been called with `kind` of `authorization` as outlined in [Create Payment Session
(Manual Capture)](/guides/setup/api/payment-sessions/manual-delayed-capture).

On a [multi-capture](/guides/setup/api/payment-sessions/manual-delayed-capture#capturing-in-multiple-parts)
session that is `partially_captured`, a void keeps the amount already captured and releases the
uncaptured remainder. The session then reports `captured`, and you can refund its captures.

A void is rejected while a capture on the session is still processing. Retry after that capture
completes.

The failure or success status is communicated to the partner via a
[`payment_session_complete`](/api-reference/payment-sessions/payment-session-completed-webhook) webhook as before.

## Response Notes

### Success Case

HTTP Status: `200`

* `id` - the unique ID for this void session. This same ID will be returned if the endpoint
  is called with the same `idempotency_key`
  * Associate this id with your internal representation of a checkout session, if applicable

### Failure Case:

HTTP Status: `400`

If a field is missing or the request is otherwise can't be processed, we'll return a `400`
with the following fields:

* `error` - can be one of:
  * `MissingField`: one of the required fields is not present in the request
  * `PaymentSessionDoesNotExist` - the `payment_session_id` does not exist.
  * `ServerError`: There was an internal server error.
    * Requests can be retried as long as the `idempotency-key` is the same.
  * `SessionCaptured` - The session has already received a final capture via a call to
    [`/payment_session/{payment_session_id}/capture`](/api-reference/payment-sessions/capture-payment-session)
    and can no longer be voided.
    * In this case, to return funds to the customer, you'll need to issue a refund.
  * `SessionPending` - The survey hasn't been completed by the customer, and no auth hold
    has been placed, so there is no auth hold to void yet.
  * `ImmediateCapture` - The caller is attempting to void a payment\_session that wasn't
    created with `kind=authorization`
  * `ValidationError` - A capture on the session is still processing. Retry the void after
    that capture completes.
* `message`:
  * Indication of one of the following:
    * Which field was missing
    * Details on how the total amount was invalid
    * Details on captured sessions.

Reference: https://developers.truemed.com/api-reference/payment-sessions/void-payment-session

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Path parameters

- `business_id` (string, required) — The UUID of the payment session returned by create_payment_session.

### Body (application/json)

This endpoint expects a PaymentSessionVoidRequest.

- `idempotency_key` (string, required) — Allows the endpoint to be called multiple times. It must be unique to the void session call.

## Response

### 200

Successful response

- `id` (string, required) — The unique ID for this void session. This same ID will be returned if the endpoint is called with the same idempotency_key. Associate this id with your internal representation of a checkout session, if applicable.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `ImmediateCapture`, `SessionCaptured`, `SessionNotAuthorized`, `SessionVoided`, `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Examples

**Request**

```json
{
  "idempotency_key": "string"
}
```

**Response**

```json
{
  "id": "string"
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/payments/v1/payment_session/business_id/void"

payload = { "idempotency_key": "string" }
headers = {
    "x-truemed-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/payments/v1/payment_session/business_id/void';
const options = {
  method: 'POST',
  headers: {'x-truemed-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"idempotency_key":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```