[Tech Spec] ADYEN — VoidPostCapture

[iemyashasvi]

ADYEN — VoidPostCapture

Complexity: low
Generated by: Grace pipeline run run-2026-05-13T20-46-35-097Z-06ded9

Summary

Implement VoidPostCapture payment method for ADYEN connector. Technical Specification — Adyen VoidPostCapture

Scope

Technical Specification — Adyen VoidPostCapture

1. Connector Profile

Field	Value
Connector	Adyen
Flow	VoidPostCapture
API Family	Adyen Checkout API
API Version	v68
Production Host	https://{{merchant_endpoint_prefix}}-checkout-live.adyenpayments.com/checkout/
Sandbox Host	https://checkout-test.adyen.com/
Regional Endpoints	Configurable via endpoint_prefix in connector config
Description	Adyen is a Dutch payment company with the status of an acquiring bank that allows businesses to accept e-commerce, mobile, and point-of-sale payments.

2. Authentication

Field	Detail
Scheme	API Key (Bearer-style header)
Header	X-Api-Key
Credentials Required	api_key (Secret), merchant_account (Secret)
Additional Config	review_key (optional, Secret), endpoint_prefix (optional, for live environment), base_url, dispute_base_url
Implementation	API key sent as X-Api-Key header value; merchant_account included in request body as merchantAccount

3. Supported Flows

Flow	HTTP	Path	Notes
Authorize	POST	/v68/payments	Supports card, wallet, bank debit, BNPL, redirect methods
PSync	POST	/v68/payments/details	Payment sync for redirects; optional when no encoded_data
Capture	POST	/v68/payments/{id}/captures	Capture an authorized payment; id = pspReference
Void (Pre-Capture)	POST	/v68/payments/{id}/cancels	Cancel an authorized (uncaptured) payment
VoidPostCapture	POST	/v68/payments/{id}/cancels	Cancel/reverse a captured payment; same endpoint as Void but applied post-capture; Adyen processes as refund when payment is already captured
Refund	POST	/v68/payments/{id}/refunds	Partial or full refund on captured payment
RSync	—	—	Not implemented; relies on webhook CANCELLATION / REFUND events
Webhooks	P

Out of Scope

Not specified in techspec

Technical Constraints

• Follow existing connector patterns in the codebase

---

Full Tech Spec

Technical Specification — Adyen VoidPostCapture

1. Connector Profile

Field	Value
Connector	Adyen
Flow	VoidPostCapture
API Family	Adyen Checkout API
API Version	v68
Production Host	https://{{merchant_endpoint_prefix}}-checkout-live.adyenpayments.com/checkout/
Sandbox Host	https://checkout-test.adyen.com/
Regional Endpoints	Configurable via endpoint_prefix in connector config
Description	Adyen is a Dutch payment company with the status of an acquiring bank that allows businesses to accept e-commerce, mobile, and point-of-sale payments.

2. Authentication

Field	Detail
Scheme	API Key (Bearer-style header)
Header	X-Api-Key
Credentials Required	api_key (Secret), merchant_account (Secret)
Additional Config	review_key (optional, Secret), endpoint_prefix (optional, for live environment), base_url, dispute_base_url
Implementation	API key sent as X-Api-Key header value; merchant_account included in request body as merchantAccount

3. Supported Flows

Flow	HTTP	Path	Notes
Authorize	POST	/v68/payments	Supports card, wallet, bank debit, BNPL, redirect methods
PSync	POST	/v68/payments/details	Payment sync for redirects; optional when no encoded_data
Capture	POST	/v68/payments/{id}/captures	Capture an authorized payment; id = pspReference
Void (Pre-Capture)	POST	/v68/payments/{id}/cancels	Cancel an authorized (uncaptured) payment
VoidPostCapture	POST	/v68/payments/{id}/cancels	Cancel/reverse a captured payment; same endpoint as Void but applied post-capture; Adyen processes as refund when payment is already captured
Refund	POST	/v68/payments/{id}/refunds	Partial or full refund on captured payment
RSync	—	—	Not implemented; relies on webhook CANCELLATION / REFUND events
Webhooks	POST	Merchant endpoint	CANCELLATION event for void confirmations; HMAC-SHA256 signed

4. Request Schema Highlights

VoidPostCapture Request (AdyenVoidRequest)

Field	Type	Required	Notes
merchantAccount	Secret<String>	Yes	Merchant account code from connector config
reference	String	Yes	Merchant void reference ID (connector_request_reference_id)

Idempotency: Adyen supports idempotent requests via the Idempotency-Key header (not currently wired in implementation).

URL Construction: Path parameter {id} is the connector_transaction_id (Adyen pspReference) from the original payment.

Sample request (from field probe):

{
  "merchantAccount": "probe_merchant",
  "reference": "probe_void_001"
}

→ POST https://checkout-test.adyen.com/v68/payments/probe_connector_txn_001/cancels

Key difference from pre-capture Void: When applied to a captured payment, Adyen's /cancels endpoint automatically triggers a refund flow. The response status received indicates the cancellation/refund was accepted; processing indicates it is still being processed.

5. Response Schema Highlights

VoidPostCapture Response (AdyenVoidResponse)

Field	Type	Notes
paymentPspReference	String	PSP reference for the cancel/reversal request
status	AdyenVoidStatus	received or processing
reference	String	Merchant reference echoed back

Status Mapping

Adyen status	Hyperswitch AttemptStatus	Meaning
received	Voided	Cancellation/reversal completed
processing	VoidInitiated	Cancellation/reversal in progress

Async completion: When status is processing, the final result is delivered via the CANCELLATION webhook event.

Error Response (AdyenErrorResponse)

Field	Type	Notes
status	i32	HTTP-equivalent status code
errorCode	String	Adyen error code
message	String	Human-readable error description
errorType	String	Error classification
pspReference	Option<String>	PSP reference (if available)

6. Error Handling

HTTP	status / errorCode	Cause
401	Invalid credential	Invalid or missing API key
403	901	Forbidden — merchant not authorized for operation
422	200	Invalid data — malformed request body or missing required fields
422	101	Invalid merchant account — merchantAccount not found
404	—	Payment not found — pspReference does not exist
409	—	Conflict — payment already cancelled or in incompatible state
422	702	Payment already captured — cannot cancel; use refund endpoint
5xx	—	Adyen server error; retry with idempotency key

7. Webhooks / Async Notifications

Aspect	Detail
Event Code	CANCELLATION — fires when a /cancels request completes
Success field	"true" or "false"
Delivery	HTTP POST to merchant webhook endpoint
Format	{"notificationItems":[{"NotificationRequestItem":{...}}]}
Verification	HMAC-SHA256 signature in additionalData.hmacSignature
HMAC Message	pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success
HMAC Key	Hex-decoded webhook secret from ConnectorWebhookSecrets.secret
Comparison	Base64-encoded computed HMAC vs. received hmacSignature
Retry Policy	Adyen retries failed deliveries with exponential backoff (up to 5 days)
Acknowledgment	Respond with [accepted] (HTTP 200)
Webhook Status Mapping	CANCELLATION + success=true → Voided; CANCELLATION + success=false → VoidFailed
Documented Gaps	Source verification is currently marked as non-mandatory (is_webhook_source_verification_mandatory returns false)

8. References

1. Adyen Checkout API v68 — Payments: https://docs.adyen.com/api-explorer/Checkout/68/post/payments
2. Adyen Checkout API v68 — Cancel payment: https://docs.adyen.com/api-explorer/Checkout/68/post/payments/-paymentPspReference-/cancels
3. Adyen Checkout API v68 — Capture: https://docs.adyen.com/api-explorer/Checkout/68/post/payments/-paymentPspReference-/captures
4. Adyen Checkout API v68 — Refund: https://docs.adyen.com/api-explorer/Checkout/68/post/payments/-paymentPspReference-/refunds
5. Adyen Webhooks: https://docs.adyen.com/development-resources/webhooks
6. Adyen HMAC Signature Verification: https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures
7. Adyen Cancel or Refund: https://docs.adyen.com/online-payments/cancel-or-refund