Void

Overview

The Void RPC cancels an authorized payment before it has been captured. This releases the held funds back to the customer's payment method, effectively canceling the transaction without charging the customer.

Business Use Case: When a customer cancels their order before it ships, or an item is out of stock after authorization. Void is the appropriate action when no funds have been transferred yet. Unlike refunds (which return captured funds), voids prevent the charge from ever occurring.

Purpose

Why use Void instead of Refund?

Scenario	Developer Implementation
Order cancellation	Customer cancels before shipping - call Void with connector_transaction_id to release held funds
Out of stock	Item unavailable after authorization - call Void to cancel authorization, no charge appears on customer statement
Fraud detection	Suspicious order flagged before capture - call Void to block the transaction entirely
Duplicate prevention	Accidental double authorization - call Void on the duplicate to release the hold
Price adjustment	Order total needs to change - Void the original, create new authorization with correct amount

Key outcomes:

• No charge appears on customer's statement (authorization disappears within 1-3 business days)

• Funds immediately available to customer (vs. 5-10 days for refunds)

• Transaction moves to VOIDED status

• No settlement fees (vs. refund processing fees)

Request Fields

Field	Type	Required	Description
merchant_void_id	string	Yes	Your unique identifier for this void operation
connector_transaction_id	string	Yes	The connector's transaction ID from the original authorization
cancellation_reason	string	No	Reason for canceling the authorization
all_keys_required	bool	No	Whether all key fields must match for void to succeed
browser_info	BrowserInformation	No	Browser details for 3DS verification
amount	Money	No	Amount to void (for partial voids)
metadata	SecretString	No	Additional metadata for the connector
connector_feature_data	SecretString	No	Connector-specific metadata for the transaction
state	ConnectorState	No	State from previous multi-step flow
test_mode	bool	No	Process as test transaction
merchant_order_id	string	No	Your internal order ID for reference

Response Fields

Field	Type	Description
connector_transaction_id	string	Connector's transaction ID
status	PaymentStatus	Current status. Values: VOIDED, VOID_INITIATED, VOID_FAILED
error	ErrorInfo	Error details if status is VOID_FAILED
status_code	uint32	HTTP-style status code (200, 402, etc.)
response_headers	map<string, string>	Connector-specific response headers
merchant_transaction_id	string	Your transaction reference (echoed back)
state	ConnectorState	State to pass to next request in multi-step flow
raw_connector_request	SecretString	Raw API request sent to connector (debugging)
mandate_reference	MandateReference	Mandate details if recurring payment
incremental_authorization_allowed	bool	Whether amount can be increased later
connector_feature_data	SecretString	Connector-specific metadata for the transaction

Example

Request (grpcurl)

grpcurl -H "x-connector: stripe" \
  -H "x-connector-auth: {\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}" \
  -d '{
    "merchant_void_id": "void_001",
    "connector_transaction_id": "pi_3Oxxx...",
    "cancellation_reason": "Customer requested cancellation",
    "merchant_order_id": "order-001",
    "test_mode": true
  }' \
  localhost:8080 \
  types.PaymentService/Void

Response

{
  "connector_transaction_id": "pi_3Oxxx...",
  "status": "VOIDED",
  "status_code": 200
}

Next Steps

• Authorize - Authorize a new payment

• Capture - Finalize the payment and transfer funds

• Get - Check current payment status