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

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 (Optional)

Field
Type
Required
Description

ip_address

String

No

Customer IP address (for fraud tracking)

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

Last updated

Was this helpful?