{"id":19622189,"url":"https://github.com/commercetools/connect-payment-integration-adyen","last_synced_at":"2026-01-16T10:18:10.821Z","repository":{"id":226402472,"uuid":"757429674","full_name":"commercetools/connect-payment-integration-adyen","owner":"commercetools","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-06T15:20:15.000Z","size":6686,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-08T16:47:25.625Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commercetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-14T13:33:32.000Z","updated_at":"2026-01-06T15:20:10.000Z","dependencies_parsed_at":"2024-03-18T10:27:07.873Z","dependency_job_id":"0dcaeefd-5ee6-4c8b-88d8-72c0180e58f1","html_url":"https://github.com/commercetools/connect-payment-integration-adyen","commit_stats":null,"previous_names":["commercetools/connect-payment-integration-adyen"],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/commercetools/connect-payment-integration-adyen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fconnect-payment-integration-adyen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fconnect-payment-integration-adyen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fconnect-payment-integration-adyen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fconnect-payment-integration-adyen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercetools","download_url":"https://codeload.github.com/commercetools/connect-payment-integration-adyen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fconnect-payment-integration-adyen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T11:26:30.874Z","updated_at":"2026-01-16T10:18:10.809Z","avatar_url":"https://github.com/commercetools.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# connect-payment-integration-adyen\n\n\u003c!--toc:start--\u003e\n\n- [connect-payment-integration-adyen](#connect-payment-integration-adyen)\n  - [Features](#features)\n  - [Overview](#overview)\n  - [Prerequisite](#prerequisite)\n    - [1. commercetools composable commerce API client](#1-commercetools-composable-commerce-api-client)\n    - [2. various URLs from commercetools composable commerce](#2-various-urls-from-commercetools-composable-commerce)\n    - [3. Adyen account credentials](#3-adyen-account-credentials)\n  - [Development Guide](#development-guide)\n    - [Connector in commercetools Connect](#connector-in-commercetools-connect)\n    - [Deployment Configuration](#deployment-configuration)\n  - [Feature](#feature)\n    - [stored payment methods](#stored-payment-methods)\n      - [Setting up stored payment methods](#setting-up-stored-payment-methods)\n      - [CT payment-methods and Adyen tokens](#ct-payment-methods-and-adyen-tokens)\n  - [Development](#development) - [Configuration steps](#configuration-steps) - [1. Environment Variable Setup](#1-environment-variable-setup) - [2. Spin Up Components via Docker Compose](#2-spin-up-components-via-docker-compose)\n  \u003c!--toc:end--\u003e\n\nThis repository provides a [connect](https://docs.commercetools.com/connect) for integration to Adyen payment service provider (PSP).\n\n## Features\n\n- Typescript language supported.\n- Uses Fastify as web server framework.\n- Uses [commercetools SDK](https://docs.commercetools.com/sdk/js-sdk-getting-started) for the commercetools-specific communication.\n- Uses [connect payment SDK](https://github.com/commercetools/connect-payments-sdk) to manage request context, sessions and JWT authentication.\n- Includes local development utilities in npm commands to build, start, test, lint \u0026 prettify code.\n\n## Overview\n\nThe adyen-integration connector contains two modules :\n\n- Enabler: Acts as a wrapper implementation in which frontend components from Adyen embedded. It gives control to checkout product on when and how to load the connector frontend based on business configuration. In cases connector is used directly and not through Checkout product, the connector library can be loaded directly on frontend than the PSP one.\n- Processor : Acts as backend services which is middleware to integrate with Adyen platform. It is mainly responsible for managing transactions with Adyen and updating payment entity in composable commerce. `connect-payment-sdk` will be offered to be used in connector to manage request context, sessions and other tools necessary to transact.\n\n```mermaid\n%%{ init : { \"theme\" : \"\", \"flowchart\" : { \"defaultRenderer\": \"dagre-wrapper\", \"curve\" : \"linear\" }}}%%\n\nflowchart TD\n    node1(( ))\n    node2(( ))\n    user(\"User\")--\u003echeckout(\"Commercetools Checkout\")\n    subgraph connector\n        enabler\n        processor\n    end\n    subgraph coco[\"Commercetools Composable Commerce\"]\n        cart\n        order\n        payment\n\n    end\n    checkout----node1\n\n    node1--\"1. Cart management\"--\u003ecart(\"cart\")\n    node1--\"2. Order management\"--\u003eorder(\"order\")\n    checkout(\"Commercetools Checkout\")----node2\n    node2--\"3. Get static assets\"--\u003eenabler(\"enabler\")\n    node2--\"4. Request payment \\noperations\"--\u003eprocessor(\"processor\")\n    processor--\"5. Request payment \\noperations\"--\u003epsp(\"Adyen payment service provider\")\n    psp(\"Adyen payment service provider\")--\"6. Return response\"--\u003eprocessor\n    processor--\"7. Payment management\"--\u003epayment(\"payment\")\n```\n\n1. commercetools Checkout in front-end side sends requests to composable commerce for cart creation.\n2. commercetools Checkout retrieves SDK as static assets from enabler in connector.\n3. After downloading the SDK, commercetools Checkout sends request via the SDK to endpoints exposed by processor for various payment operations.\n4. The processor transforms the received request and send them to Ayden platform.\n5. Adyen processes the payment operations and return the response to processor.\n6. The processor handles the payment persistence to composable commerce, and return the result to front-end.\n7. commercetools Checkout handles the order management in composable commerce once it receives the result from the processor.\n\n## Prerequisite\n\n#### 1. commercetools composable commerce API client\n\nUsers are expected to create API client responsible for payment management in composable commerce project. Details of the API client are taken as input as environment variables/ configuration for connect such as `CTP_PROJECT_KEY` , `CTP_CLIENT_ID`, `CTP_CLIENT_SECRET`. For details, please read [Deployment Configuration](./README.md#deployment-configuration).\nIn addition, please make sure the API client should have enough scope to be able to manage payment. For details, please refer to [Running Application](./processor/README.md#running-application)\n\n#### 2. various URLs from commercetools composable commerce\n\nVarious URLs from commercetools platform are required to be configured so that the connect application can handle session and authentication process for endpoints.\nTheir values are taken as input as environment variables/ configuration for connect with variable names `CTP_API_URL`, `CTP_AUTH_URL` and `CTP_SESSION_URL`.\n\n#### 3. Adyen account credentials\n\nVarious account data provided by Adyen are necessary to be configured so that the requests from the connect application can be authenticated by Adyen platform within the integration.\nTheir values are taken as input as environment variables/ configuration for connect with variable names `ADYEN_API_KEY`, `ADYEN_NOTIFICATION_HMAC_KEY`, `ADYEN_MERCHANT_ACCOUNT`, `ADYEN_CLIENT_KEY`, `ADYEN_LIVE_URL_PREFIX` and `ADYEN_ENVIRONMENT`.\n\n## Development Guide\n\nRegarding the development of enabler module, please refer to the following documentations:\n\n- [Development of Enabler](./enabler/README.md)\n\nRegarding the development of processor module, please refer to the following documentations:\n\n- [Development of Processor](./processor/README.md)\n\n#### Connector in commercetools Connect\n\nUse public connector listed in connect marketplace. If any customization done, follow guidelines [here](https://docs.commercetools.com/connect/getting-started) to register the connector for private use.\n\n#### Deployment Configuration\n\nIn order to deploy your customized connector application on commercetools Connect, it needs to be published. For details, please refer to [documentation about commercetools Connect](https://docs.commercetools.com/connect/concepts)\nIn addition, in order to support connect, the adyen payment integration connector has a folder structure as listed below\n\n```\n├── enabler\n│   ├── src\n│   ├── test\n│   └── package.json\n├── processor\n│   ├── src\n│   ├── test\n│   └── package.json\n└── connect.yaml\n```\n\nConnect deployment configuration is specified in `connect.yaml` which is required information needed for publishing of the application. Following is the deployment configuration used by enabler and processor modules\n\n```\ndeployAs:\n  - name: enabler\n    applicationType: assets\n  - name: processor\n    applicationType: service\n    endpoint: /\n    configuration:\n      standardConfiguration:\n        - key: CTP_PROJECT_KEY\n          description: commercetools project key\n          required: true\n        - key: CTP_AUTH_URL\n          description: commercetools Auth URL\n          required: true\n          default: https://auth.europe-west1.gcp.commercetools.com\n        - key: CTP_API_URL\n          description: commercetools API URL\n          required: true\n          default: https://api.europe-west1.gcp.commercetools.com\n        - key: CTP_SESSION_URL\n          description: Session API URL\n          required: true\n          default: https://session.europe-west1.gcp.commercetools.com\n        - key: CTP_CLIENT_ID\n          description: commercetools client ID with manage_payments, manage_orders, view_sessions, view_api_clients, manage_checkout_payment_intents \u0026 introspect_oauth_tokens scopes\n          required: true\n        - key: ADYEN_ENVIRONMENT\n          description: Adyen environment\n          required: true\n          default: TEST\n        - key: ADYEN_MERCHANT_ACCOUNT\n          description: Adyen merchant account\n          required: true\n        - key: ADYEN_CLIENT_KEY\n          description: Adyen client key\n          required: true\n        - key: ADYEN_LIVE_URL_PREFIX\n          description: Adyen live URL prefix\n        - key: MERCHANT_RETURN_URL\n          description: Merchant return URL\n          required: true\n        - key: CTP_JWKS_URL\n          description: JWKs url (example - https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json)\n          required: true\n          default: https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json\n        - key: CTP_JWT_ISSUER\n          description: JWT Issuer for jwt validation (example - https://mc-api.europe-west1.gcp.commercetools.com)\n          required: true\n          default: https://mc-api.europe-west1.gcp.commercetools.com\n        - key: ADYEN_APPLEPAY_OWN_MERCHANT_ID\n          description: Apple merchant ID. Needed when using own certificate\n          required: false\n        - key: ADYEN_APPLEPAY_OWN_MERCHANT_DOMAIN\n          description: Apple merchant domain. Needed when using own certificate\n          required: false\n        - key: ADYEN_APPLEPAY_OWN_DISPLAY_NAME\n          description: Apple display name. Needed when using own certificate\n          required: false\n        - key: ADYEN_SHOPPER_STATEMENT\n          description: The text to be shown on the shopper's bank statement. We recommend sending a maximum of 22 characters, otherwise banks might truncate the string\n          required: false\n        - key: ADYEN_PAYMENT_COMPONENTS_CONFIG\n          description: Adyen payment components configuration in JSON String format. For example: {\"paypal\":{\"blockPayPalVenmoButton\":false}}. Please refer to the Adyen documentation for more details.\n          required: false\n        - key: ADYEN_STORED_PAYMENT_METHODS_ENABLED\n          description: If set to \"true\" then the stored payment methods feature is enabled. Default value is \"false\".\n          required: false\n        - key: ADYEN_STORED_PAYMENT_METHODS_PAYMENT_INTERFACE\n          description: The payment method payment interface value used in the commerceotools payment methods. Default value is \"adyen\".\n          required: false\n        - key: ADYEN_STORED_PAYMENT_METHODS_INTERFACE_ACCOUNT\n          description: The payment method interface account value used in the commerceotools payment methods.\n          required: false\n      securedConfiguration:\n        - key: CTP_CLIENT_SECRET\n          description: commercetools client secret\n          required: true\n        - key: ADYEN_API_KEY\n          description: Adyen API key\n          required: true\n        - key: ADYEN_NOTIFICATION_HMAC_KEY\n          description: Adyen HMAC key\n          required: true\n        - key: ADYEN_NOTIFICATION_HMAC_TOKENIZATION_WEBHOOKS_KEY\n          description: Adyen HMAC tokenization webhooks key. This will be used if provided, otherwise the ADYEN_NOTIFICATION_HMAC_KEY will be used. (Please use the dummy placeholder value during the installation process. Once the webhook configuration in Adyen is complete and HMAC known, replace this placeholder with the actual value and redeploy.)\n          required: false\n        - key: ADYEN_APPLEPAY_OWN_CERTIFICATE\n          description: Apple Pay own certificate\n          required: false\n\n```\n\nHere you can see the details about various variables in configuration\n\n- `CTP_PROJECT_KEY`: The key of commercetools composable commerce project.\n- `CTP_CLIENT_ID`: The client ID of your commercetools composable commerce user account. It is used in commercetools client to communicate with commercetools composable commerce via SDK. Expected scopes are: `manage_payments` `manage_orders` `view_sessions` `view_api_clients` `manage_checkout_payment_intents` `introspect_oauth_tokens`.\n- `CTP_CLIENT_SECRET`: The client secret of commercetools composable commerce user account. It is used in commercetools client to communicate with commercetools composable commerce via SDK.\n- `CTP_AUTH_URL`: The URL for authentication in commercetools platform. It is used to generate OAuth 2.0 token which is required in every API call to commercetools composable commerce. The default value is `https://auth.europe-west1.gcp.commercetools.com`. For details, please refer to documentation [here](https://docs.commercetools.com/tutorials/api-tutorial#authentication).\n- `CTP_API_URL`: The URL for commercetools composable commerce API. Default value is `https://api.europe-west1.gcp.commercetools.com`.\n- `CTP_SESSION_URL`: The URL for session creation in commercetools platform. Connectors relies on the session created to be able to share information between enabler and processor. The default value is `https://session.europe-west1.gcp.commercetools.com`.\n- `CTP_JWKS_URL`: The URL which provides JSON Web Key Set. Default value is `https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json`.\n- `CTP_JWT_ISSUER`: The issuer inside JSON Web Token which is required in JWT validation process. Default value is `default: https://mc-api.europe-west1.gcp.commercetools.com`\n- `ADYEN_ENVIRONMENT`: The indicator of adyen environment. Default value is `TEST`. It can be configured either as `LIVE` or `TEST`.\n- `ADYEN_MERCHANT_ACCOUNT`: The name of adyen merchant account.\n- `ADYEN_CLIENT_KEY`: Client key provided by Adyen for client-side authentication. For details, please refer to [Adyen client-side authentication](https://docs.adyen.com/development-resources/client-side-authentication).\n- `ADYEN_LIVE_URL_PREFIX`: It represents live endpoint prefix used by Adyen platform. It is only required for Adyen live environment. For details, please refer to [Adyen live endpoints](https://docs.adyen.com/development-resources/live-endpoints/).\n- `MERCHANT_RETURN_URL`: The return URL located in merchant platform.\n- `ADYEN_API_KEY`: It represents the API Key used for Ayden request authentication. For details, please refer to [Ayden API key authentication](https://docs.adyen.com/development-resources/api-authentication/#api-key-authentication).\n- `ADYEN_NOTIFICATION_HMAC_KEY`: It represents a hash-based signature within Ayden webhook event. It aims at protecting the connector from any unauthorized webhook event. For details, please refer to [Verify HMAC signatures](https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures).\n- `ADYEN_APPLEPAY_OWN_CERTIFICATE`: The merchant identity certificate. This is only needed if using an own certificate instead of the Adyen's Apple Pay certificate. Follow [Adyen's guide](https://docs.adyen.com/payment-methods/apple-pay/enable-apple-pay/?tab=setup-own_2) to create the certificate. **The value should be in base64 format**.\n- `ADYEN_APPLEPAY_OWN_MERCHANT_ID`: The merchant identifier created in the Apple portal. Only needed if using an own certificate\n- `ADYEN_APPLEPAY_OWN_MERCHANT_DOMAIN`: The merchant domain verified in the Apple portal. Only needed if using an own certificate. Do not add the https protocol.\n- `ADYEN_APPLEPAY_OWN_DISPLAY_NAME`: A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. This needs to remain a consistent value for the store and shouldn’t contain dynamic values such as incrementing order numbers. Only needed if using an own certificate.\n- `ADYEN_SHOPPER_STATEMENT`: The text to be shown on the shopper's bank statement. For more information, see [Adyen's reference](https://docs.adyen.com/api-explorer/Checkout/71/post/payments#request-shopperStatement).\n- `ADYEN_STORED_PAYMENT_METHODS_ENABLED`: Indicates if the stored payment methods feature is enabled or not. Must be a string value of \"true\" or \"false\". Default it's \"false\".\n- `ADYEN_STORED_PAYMENT_METHODS_PAYMENT_INTERFACE`: A string value which is used to set the corresponding \"paymentInterface\" value on the CT payment-methods. If this value gets changed then previously created payment-methods won't be retrieved and would need to be manually migrated over.\n- `ADYEN_STORED_PAYMENT_METHODS_INTERFACE_ACCOUNT`: A string value which is used to set the corresponding \"interfaceAccount\" value on the CT payment-methods. If this value gets changed then previously created payment-methods won't be retrieved and would need to be manually migrated over.\n- `ADYEN_NOTIFICATION_HMAC_TOKENIZATION_WEBHOOKS_KEY`: A specific hmac key for the tokenization webhooks from Adyen. If not provided then the existing \"ADYEN_NOTIFICATION_HMAC_KEY\" env value is used.\n\n## Feature\n\n### stored payment methods\n\nThe feature stored payment methods allows the payment details to be tokenised to the next time the customers goes through Checkout they won't have to re-enter the payment details.\n\nCurrently supported payment-methods for storing: (for both web-components and drop-ins)\n\n- `card`\n\n#### Setting up stored payment methods\n\n1. update the env configuration\n   1. set `ADYEN_STORED_PAYMENT_METHODS_ENABLED` to `true`. By default it is not enabled.\n   2. set `ADYEN_STORED_PAYMENT_METHODS_PAYMENT_INTERFACE` to any string value.\n   3. optionally set `ADYEN_STORED_PAYMENT_METHODS_INTERFACE_ACCOUNT` to any string value.\n   4. for the tokenization notifications choose between using a new HMAC key by setting `ADYEN_NOTIFICATION_HMAC_TOKENIZATION_WEBHOOKS_KEY` or if unset the connector will use the HMAC key of `ADYEN_NOTIFICATION_HMAC_KEY`\n2. create a new CT API client which the additional scope of `manage_payment_methods` and update the corresponding env values. The connector health check will fail if the feature is enabled but the configured API client is missing this scope.\n3. create a new webhook in Adyen of type `Recurring tokens life cycle events` with the event to be send of `recurring.token.created`.\n   1. the destination must be to `\u003cprocessorUrl\u003e/notifications/tokenization`\n   2. choose either the existing hmac key or generate a new one\n4. ensure that before Checkout is instantiated the `cart.customerId` is set to the correct customer. The Adyen connector uses this for all interactions.\n\n#### CT payment-methods and Adyen tokens\n\nWhen a payment method is tokenized for the first time Adyen will send a new notification stating that the payment method has been tokenized. The processor handles the notification by creating a new payment-method in CT. The payment-method is attached to the `cart.customerId` as well as the `paymentInterface` and `interfaceAccount` are set based on the previously configured env values.\n\nThe next time the same customer goes through Checkout (either using drop-ins or web-components) they will see the stored payment method as a option to pay with.\n\n## Development\n\nIn order to get started developing this connector certain configuration are necessary, most of which involve updating environment variables in both services (enabler, processor).\n\n### Configuration steps\n\n#### 1. Environment Variable Setup\n\nNavigate to each service directory and duplicate the .env.template file, renaming the copy to .env. Populate the newly created .env file with the appropriate values.\n\n```bash\ncp .env.template .env\n```\n\n#### 2. Spin Up Components via Docker Compose\n\nWith the help of docker compose, you are able to spin up all necessary components required for developing the connector by running the following command from the root directory;\n\n```bash\ndocker compose up\n```\n\nThis command would start 3 required services, necessary for development\n\n1. JWT Server\n2. Enabler\n3. Processor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fconnect-payment-integration-adyen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercetools%2Fconnect-payment-integration-adyen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fconnect-payment-integration-adyen/lists"}