Integrating Adyen
Auth: API key · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-15
Adyen Checkout / Management API — global enterprise gateway with strong alt-method coverage.
Auth model
Section titled “Auth model”
rawis opt-in. The upstream payload is withheld unless an operator enablesdata_store.raw_payload.paymentsin Admin → Settings → Data store. It is off by default because across the payments adapters it declares bank account numbers, IBANs and card numbers the canonical schema does not expose.
api_key. Submit an API key from your Adyen Customer Area along with the merchant account name. The adapter sends X-API-Key: <key> on every request.
Configure in admin
Section titled “Configure in admin”- In the Adyen Customer Area, go to Developers → API credentials → Web service user, generate a new API key, and grant it the roles you need (Checkout webservice role + Management API role at minimum).
- Note the merchant account (e.g.
YourCompanyECOM). - Open
/platforms→ Payments → Adyen → Configure and submit:apiKeymerchantAccountbaseUrl— test =https://checkout-test.adyen.com; live = your live prefix from the Customer Area (each Adyen account has a unique live host).
Webhooks
Section titled “Webhooks”Adyen delivers standard webhook notifications as batched HMAC-signed payloads. Configure them at Developers → Webhooks → Standard Notification:
- URL:
https://${PUBLIC_BASE_URL}/webhooks/adyen - Method: JSON
- HMAC key: generate and store as the webhook secret on the adapter
The adapter verifies each item’s hmacSignature field against the configured key.
Quirks
Section titled “Quirks”- No bulk list endpoint. Adyen doesn’t expose
GET /payments— the canonical pattern is “webhook-first”: consume notifications, look up bypspReferenceon demand viagetCharge. pspReferenceis the gateway ID. Used asexternalIdeverywhere — long-running operations chain off it.- Subscriptions surface as
RecurringContract, not a first-class Subscription resource. The adapter does not normalise them into a canonical Subscription resource; enable and inspectrawif you need theRecurringContractdetails. - Tax + alt methods. Adyen normalises hundreds of payment methods server-side; if you need the local-method detail (iDEAL, BLIK, Boleto …), inspect
raw.paymentMethod.
References
Section titled “References”- API explorer: https://docs.adyen.com/api-explorer/
- Payment methods overview: https://docs.adyen.com/payment-methods/
- Webhooks (HMAC signature verification): https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.