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

# Authorization Void

### Overview

The Authorization Void endpoint cancels a previously authorized transaction before it has been captured. This releases the held funds on the customer's card immediately, rather than waiting for the authorization to expire naturally.

**POST** `/v1/payments/{transactionId}/void`

### What Happens Internally

```
Client Request → Firstoken API → [KOIN Void] → Response
```

1. **Validation**: Verify the authorization exists and can be voided
2. **Void Processing**: Cancel the authorization hold
3. **Fund Release**: Release held funds on customer's card
4. **Response**: Void confirmation with transaction details

### Request Body

```json
{
  "transaction_info": {
    "type": "authorization_void",
    "reference_code": "123456789"
  },
  "device_info": {
    "ip_address": "12.7.8.120",
    "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
  }
}
```

### Field Specifications

#### URL Parameters

| Parameter       | Type   | Required | Description                                    |
| --------------- | ------ | -------- | ---------------------------------------------- |
| `transactionId` | String | Yes      | Transaction ID from the authorization response |

#### transaction\_info (Required)

| Field            | Type   | Required | Description                       |
| ---------------- | ------ | -------- | --------------------------------- |
| `type`           | String | Yes      | Must be "authorization\_reversal" |
| `reference_code` | String | Yes      | Your reference for this reversal  |

#### Device Info

<table><thead><tr><th width="222.50390625">Parameter</th><th width="108.1484375">Type</th><th width="119.70703125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>ip_address</code></td><td>String</td><td>Yes</td><td>Customer's IP address</td></tr><tr><td><code>fingerprint_session_id</code>*</td><td>String</td><td>Yes </td><td>A unique alpha-numerical ID generated for each user session on a website.</td></tr></tbody></table>

{% hint style="info" %}
`fingerprint_session_id` is required for all KOIN requests. See [KOIN - Device Fingerprint Session ID](/api-docs/guides/koin-device-fingerprint-session-id.md) for implementation by platform (Web, Android, iOS).
{% endhint %}

***

### Response Format

#### Success Response (200)

```json
{
    "status": "success",
    "message": "Authorization void successful",
    "data": {
        "transaction_info": {
            "type": "authorization_void_response",
            "reference_code": "123456789",
            "transaction_id": "0001753573594895181861",
            "request_id": "7535735952676373604807",
            "status": "Voided",
            "created_at": "2025-07-26T23:46:35Z"
        }
    }
}
```

#### Error Response (400/500)

```json
{
    "status": "fail",
    "message": "Invalid request",
    "data": {
        "code": 400,
        "description": "Invalid transaction_id"
    }
}
```

### cURL Examples

#### Authorization Void

```bash
curl -X POST https://api.firstoken.co/v1/payments/0001753573236419268758/void \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "authorization_void",
      "reference_code": "void_{{$guid}}"
    },
    "device_info": {
      "ip_address": "192.168.1.100",
      "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7"
    }
  }'
```

### Void Status Values

| Status    | Description                        |
| --------- | ---------------------------------- |
| `Voided`  | Authorization successfully voided  |
| `Pending` | Void request submitted, processing |
| `Failed`  | Void operation failed              |

### Use Cases

When to Use Authorization Void

* **Customer Cancellation**: Customer cancels before you capture
* **Inventory Check Failed**: Product not available after authorization
* **Fraud Detection**: Suspicious activity detected during review
* **System Error**: Technical error during authorization process
* **Customer Request**: Customer wants to use different payment method
* **Order Modification**: Customer wants to change order significantly
* **Duplicate Authorization**: Accidentally authorized twice

### Important Notes

#### Void Rules

* **Timing**: Must void before capture
* **Amount Limit**: Cannot void more than authorized amount
* **Status Check**: Authorization must be in "Authorized" status
* **Single Operation**: Most authorizations allow only one void operation

#### Void vs Refund vs Expiration

| Aspect                | Authorization Void  | Payment Refund        | Natural Expiration |
| --------------------- | ------------------- | --------------------- | ------------------ |
| **Transaction State** | Authorized only     | Captured/Collected    | Authorized only    |
| **Timing**            | Immediate           | 3-5 business days     | 7 days typically   |
| **Customer Impact**   | Immediate release   | Refund processing     | Delayed release    |
| **Merchant Control**  | Active cancellation | Active refund         | Passive waiting    |
| **Best Practice**     | Recommended         | For captured payments | Poor UX            |

#### When Void is Not Possible

If authorization void fails, consider these alternatives:

1. **Wait for Expiration**: Let authorization expire naturally (7 days)
2. **Capture + Refund**: If accidentally captured, refund the payment
3. **Customer Service**: Contact customer service for manual intervention
4. **Refund Process**: If payment was completed, process refund