--- name: bijection-abdssamie-adyen-payments description: "Evaluate and integrate the Adyen Payments component with Bijection." --- # Adyen Payments Convex component for Adyen payments. Supports Drop-in checkout sessions, recurring card charges, and HMAC-validated webhooks. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: @abdssamie/adyen-payments - Source: https://github.com/Abdssamie/adyen-payments - npm: https://www.npmjs.com/package/%40abdssamie%2Fadyen-payments - Directory: https://bijection.com/components/abdssamie-adyen-payments Read the upstream README for setup, license, and compatibility before using it. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @abdssamie/adyen-payments. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. # Adyen Payments ## Instructions Use Adyen Payments to convex component integrating adyen payments with drop-in checkout sessions, recurring card charges, and hmac-validated webhook handling. This Convex component integrates directly with your backend. ### Installation ```bash npm install @abdssamie/adyen-payments ``` ### Capabilities - Implement Adyen Drop-in and Web Components checkout sessions with a single action call returning sessionId and sessionData ready for the frontend SDK. - Charge stored payment tokens for recurring or merchant-initiated transactions without managing tokenization logic directly. - Receive and validate Adyen webhooks with automatic HMAC signature verification and pre-resolved shopperReference, metadata, and isSuccess fields on every notification. - Support manual capture, refund, and cancel workflows via dedicated action wrappers with no additional Adyen API boilerplate. ## Examples ### how to integrate Adyen checkout sessions with Convex backend 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. ### how to handle Adyen webhooks in Convex 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. ### recurring payments with stored card tokens in Convex 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. ### how to refund or cancel an Adyen payment in Convex 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. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by Adyen Payments is not needed ## Troubleshooting **What Adyen integration types does the Adyen Payments Convex component support?** 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. **What environment variables are required to configure the Adyen Payments component?** 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. **Why does the Adyen webhook handler need to run in a 'use node' context?** 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. **How does autoCapture work in the Adyen Payments component?** 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. **How do I install and register the Adyen Payments component in a Convex project?** 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). ## Resources - [npm package](https://www.npmjs.com/package/%40abdssamie%2Fadyen-payments) - [GitHub repository](https://github.com/Abdssamie/adyen-payments) - [Live demo](https://adyen-convex.pages.dev) - [Convex Components Directory](https://www.convex.dev/components/abdssamie/adyen-payments) - [Convex documentation](https://docs.convex.dev)