# 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 numerical ID generated for each user session on a website.</td></tr></tbody></table>

<p align="center"><sub>(*) The <code>fingerprint_session_id</code> is generated using a Koin script that is called from the webpage.</sub></p>

### 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"
    }
  }'
```

### 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


---

# Agent Instructions: 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://firstoken.gitbook.io/api-docs/api-reference/payments/payments-api-koin/authorization-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.