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

{
  "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

Parameter	Type	Required	Description
ip_address	String	Yes	Customer's IP address
fingerprint_session_id*	String	Yes	A unique numerical ID generated for each user session on a website.

_{(*) The fingerprint_session_id is generated using a Koin script that is called from the webpage.}

Response Format

Success Response (200)

{
    "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)

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

cURL Examples

Authorization Void

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