Convex component integrating Adyen payments with Drop-in checkout sessions, recurring card charges, and HMAC-validated webhook handling.
npm install @abdssamie/adyen-paymentsAdyen Payments is a Convex component that integrates Adyen's payment infrastructure into your backend. It exposes server-side actions for creating Drop-in/Web Components checkout sessions, charging stored payment tokens for recurring billing, and modifying payments via capture, refund, or cancel. Incoming Adyen webhooks are verified using HMAC signatures and automatically update payment records in the component's internal database.
The Adyen Payments component exposes a createCheckoutSession method callable from a Convex action. It accepts amount, currency, successUrl, cancelUrl, and shopperReference, then returns sessionId and sessionData needed to initialize the Adyen Drop-in or Web Components SDK on the frontend.
Use createWebhookHandler from @abdssamie/adyen-payments inside a 'use node' Convex internal action, since HMAC signature verification requires Node.js. Map the handler to a POST route at /adyen/webhooks in your convex/http.ts router. The component automatically validates the HMAC signature and enriches each notification with shopperReference, metadata, and isSuccess before calling your event callbacks.
After a shopper completes checkout and consents to saving payment details, Adyen stores a token referenced by recurringDetailReference. Call adyenClient.chargeStoredCard from a Convex action with shopperReference, recurringDetailReference, amount, and currency to trigger a merchant-initiated charge against that stored card.
The Adyen Payments component provides refundPayment and cancelPayment methods on the AdyenPayments client. Call them from Convex actions with the pspReference returned by the original authorization. refundPayment also requires amount and currency. capturePayment is available for manual capture flows when autoCapture is set to false.
The @abdssamie/adyen-payments component supports the Adyen Drop-in and Web Components SDK only. It does not support hosted checkout pages (HPP) or Pay By Link. The session response includes sessionId and sessionData for initializing the frontend SDK, and the url field is null for most merchant configurations.
You need five environment variables set in your Convex dashboard: ADYEN_API_KEY for server-side API requests, ADYEN_MERCHANT_ACCOUNT for your merchant account code, ADYEN_ENVIRONMENT set to TEST or LIVE, ADYEN_HMAC_KEY for webhook signature validation, and APP_URL for your application base URL.
HMAC signature verification in the Adyen Payments component depends on Node.js-native packages. The createWebhookHandler function must be used inside a file marked 'use node' and wrapped in an internalAction. Your convex/http.ts router then delegates to this internal action via ctx.runAction.
When initializing AdyenPayments with autoCapture set to true (the default), authorized payments are captured immediately. Setting autoCapture to false enables manual capture, requiring you to call adyenClient.capturePayment with the pspReference, amount, and currency after authorization succeeds.
Run npm install @abdssamie/adyen-payments, then import adyenPayments from @abdssamie/adyen-payments/convex.config.js and register it with app.use(adyenPayments) in your convex/convex.config.ts file. After that, initialize the client in your action files using new AdyenPayments(components.adyenPayments, options).