Make an initial payment with 'shopperReference' (your stable customer ID), 'shopperInteraction: Ecommerce', 'recurringProcessingModel: CardOnFile' or 'Subscription', and 'storePaymentMethod: true'; the customer completes 3DS as required.
Adyen returns a 'recurringDetailReference' (also surfaced in the RECURRING_CONTRACT notification) — store this alongside your 'shopperReference'; this pair identifies the stored card for future use.
For subsequent merchant-initiated transactions (MIT), POST to /payments with 'shopperReference', 'selectedRecurringDetailReference' (the stored reference), 'shopperInteraction: ContAuth', and 'recurringProcessingModel: CardOnFile' or 'Subscription' as appropriate.
Do not include a 'shopperEmail' or 'returnUrl' on MIT calls; include 'merchantInitiatedReason' if required by the card network (e.g., 'RESUBMISSION', 'DELAYED_CHARGE').
Handle the response synchronously: Adyen returns a final 'resultCode' of 'Authorised', 'Refused', or 'Error' for most recurring charges without requiring a redirect — process the result inline.
Subscribe to Adyen webhooks (AUTHORISATION, CAPTURE, REFUND, CHARGEBACK) and verify each notification using the HMAC signature computed over a specific concatenated string of notification fields using your HMAC key from the Customer Area.
Known gotchas
Using 'shopperInteraction: Ecommerce' for unattended recurring charges (without the cardholder present) violates card network rules and increases decline rates — always use 'ContAuth' for subsequent MIT charges.
The 'recurringDetailReference' can be invalidated if the card expires, is replaced, or the customer disputes a charge — always handle 'Refused' responses with reason 'Recurring transaction not found' by prompting the customer to update their payment method.
Adyen's test environment (test.adyen.com) uses different API credentials from live (live.adyen.com with a unique subdomain prefix per merchant) — hardcoded URLs cause silent failures when promoting to production.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp