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
Validation: Verify the authorization exists and can be voided
Void Processing: Cancel the authorization hold
Fund Release: Release held funds on customer's card
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
transactionId
String
Yes
Transaction ID from the authorization response
transaction_info (Required)
type
String
Yes
Must be "authorization_reversal"
reference_code
String
Yes
Your reference for this reversal
device_info (Optional)
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
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
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:
Wait for Expiration: Let authorization expire naturally (7 days)
Capture + Refund: If accidentally captured, refund the payment
Customer Service: Contact customer service for manual intervention
Refund Process: If payment was completed, process refund
Last updated
Was this helpful?