Setup Adyen

Adyen Payment Gateway

Use this skill for Adyen online payment integration work for Malaysian merchants.

Source

Read references/adyen-api.md first. It is the entry point: environments, auth, idempotency, endpoint catalogue, flow summary, HMAC algorithm, statuses, amounts, IP ranges, common errors, and links to the topic files.

Read the topic file for the task:

• references/adyen-checkout.md: Sessions flow, Hosted Checkout, Advanced flow, Drop-in, actions, result codes, 3DS2.
• references/adyen-webhooks.md: webhook setup, payload, HMAC verification code, event codes, retries.
• references/adyen-modifications.md: capture, refund, cancel, reversal, amount update, lifecycle, disputes API.
• references/adyen-payment-methods-my.md: FPX issuers, DuitNow, Touch 'n Go, GrabPay, Boost, Atome, Alipay, Alipay+, WeChat Pay, cards.
• references/adyen-tokenization-links.md: tokens and payment links.
• references/adyen-errors-testing.md: sandbox data, refusal reasons, error codes.
• references/adyen-fields.md: full request and response field tables from the official OpenAPI.

Read references/account-setup.md for registration, documents, Customer Area paths, credentials, env vars, payment method activation, payouts, reports, and go live.

Read references/source-map.md to pick the right official page and to see what the skill covers.

Core Workflow

1. Identify environment: test (checkout-test.adyen.com) or live (<PREFIX>-checkout-live.adyenpayments.com).
2. Pick the flow: Hosted Checkout, Sessions flow with Drop-in, or Advanced flow; payment links for invoices.
3. Confirm Customer Area setup: merchant account, API credential roles, API key, client key with allowed origins, payment methods added (FPX and others), webhook with HMAC key.
4. Create a local pending order (amount in sen, MYR) before calling Adyen.
5. Call POST /sessions (or /paymentMethods then /payments) server-side with x-API-key, idempotency-key, reference = order id, countryCode: "MY", returnUrl.
6. Render Drop-in with session.id and sessionData and the client key, or redirect to the Hosted Checkout url.
7. On return, submit redirectResult and show resultCode as UX only.
8. Verify each webhook item's additionalData.hmacSignature (HMAC-SHA256, hex-decoded key, 8 fields joined by :), store it, return 2xx within 10 seconds, then process.
9. Settle idempotently from AUTHORISATION with success == "true" after matching reference, amount, currency, merchant account and environment.
10. Run captures, refunds, cancels and reversals server-side; treat their webhooks as the outcome.

Core Facts

• Checkout API version used by the docs: v72. Test base https://checkout-test.adyen.com/v72.
• Live base https://<PREFIX>-checkout-live.adyenpayments.com/checkout/v72; prefix from live Customer Area > Developers > API URLs.
• Auth: x-API-key header from Developers > API credentials; client key (test_ / live_) for the frontend only.
• amount.value is an integer in minor units; MYR has 2 decimals.
• idempotency-key header, max 64 characters, kept at least 7 days.
• Webhook HMAC string: pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success.
• Webhooks must get 2xx within 10 seconds; retries run up to 30 days.
• Modifications return status: "received"; outcomes come by CAPTURE, REFUND, CANCELLATION, CANCEL_OR_REFUND, TECHNICAL_CANCEL webhooks.
• FPX type molpay_ebanking_fpx_MY with required issuer; all 18 issuers must be shown (PayNet rule).
• DuitNow is QR only and its result comes only by webhook; DuitNow and Touch 'n Go are enabled through Support.
• Malaysian local methods have no recurring and no separate capture; Boost allows full refunds only.
• No webhook is sent at settlement; use the Settlement details report.

Critical Rules

• Keep the API key, HMAC key and report credentials server-side. The client key is public but restrict its allowed origins.
• Never fulfil from resultCode, onPaymentCompleted, redirectResult, sessionResult or a return URL alone.
• Verify HMAC per notification item with the hex-decoded key and constant-time comparison; reject items without hmacSignature.
• For header-signed webhooks (token life cycle, Management), verify over the raw body.
• Use test keys with test hosts and live keys with the live prefix host; check webhook live matches.
• Accept, store and acknowledge webhooks before business logic; make processing idempotent on pspReference, eventCode, success.
• Compare amount.value as an integer and amount.currency against the stored order.
• Send every POST with an idempotency-key; retry only with the same key.
• Show all 18 FPX banks; do not filter the issuer list.
• Respect method limits: GrabPay reference max 32 [A-Za-z0-9_-]; Atome MYR 10 to 1,500 debit or 5,000 credit, required shopper fields, no portable electronics.
• Do not copy fees; link https://www.adyen.com/pricing.
• Say "Not documented in official docs" instead of guessing.

Completion Criteria

An Adyen integration is done only when:

1. Session or payment creation runs server-side with x-API-key and idempotency-key.
2. The frontend only renders Drop-in or redirects; it cannot mark an order paid.
3. A Standard webhook is configured per environment with its own HMAC key.
4. The webhook handler verifies HMAC exactly as documented, stores, acknowledges within 10 seconds, and processes asynchronously.
5. Settlement checks merchantReference, amount, currency, merchantAccountCode, live, and success.
6. Duplicate webhooks, late AUTHORISATION after Pending, OFFER_CLOSED, and modification failures are handled idempotently.
7. Tests cover bad HMAC, replayed event, wrong amount or currency, refused payment, pending FPX or wallet, refund failure, and a successful payment.
8. Deployment docs list ADYEN_API_KEY, ADYEN_MERCHANT_ACCOUNT, ADYEN_CLIENT_KEY, ADYEN_HMAC_KEY, ADYEN_ENVIRONMENT, ADYEN_LIVE_URL_PREFIX, return URL, webhook URL, and test or live separation.

Loophole Review Loop

When asked whether an Adyen strategy is "100% confident", run this loop until no factual gaps remain:

1. List trust boundaries: browser, Drop-in, return URL, Hosted Checkout page, backend creator, Adyen API, webhook receiver, queue, database, fulfilment, modification jobs, Customer Area settings, reports.
2. Check bypasses: forged return URL, forged webhook, HMAC over wrong fields or unhexed key, test key in live, wrong prefix host, wrong merchant account, amount or currency mismatch, duplicate or out-of-order events, slow handler causing retries, pending marked failed too early, refunds before capture, cancel after capture, method not enabled, missing FPX banks.
3. Add fixes: server-side creation, local pending order first, documented HMAC check, constant-time compare, strict field matching, durable event log, idempotency keys, environment-separated config, DNS-based allowlisting, report reconciliation.
4. Re-read the relevant reference file for any gap.
5. State remaining uncertainty that depends on the merchant's contract, enabled methods, live region, payout model, or Support-enabled features.