Skip to content

About

No description or website provided.

Topics

Resources

Security policy

Stars

3 stars

Watchers

3 watching

Forks

Repository files navigation

connect-payment-integration-adyen

This repository provides a connect for integration to Adyen payment service provider (PSP).

Features

  • Typescript language supported.
  • Uses Fastify as web server framework.
  • Uses commercetools SDK for the commercetools-specific communication.
  • Uses connect payment SDK to manage request context, sessions and JWT authentication.
  • Includes local development utilities in npm commands to build, start, test, lint & prettify code.

Overview

The adyen-integration connector contains two modules :

  • 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.
  • 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.
%%{ init : { "theme" : "", "flowchart" : { "defaultRenderer": "dagre-wrapper", "curve" : "linear" }}}%%

flowchart TD
    node1(( ))
    node2(( ))
    user("User")-->checkout("Commercetools Checkout")
    subgraph connector
        enabler
        processor
    end
    subgraph coco["Commercetools Composable Commerce"]
        cart
        order
        payment

    end
    checkout----node1

    node1--"1. Cart management"-->cart("cart")
    node1--"2. Order management"-->order("order")
    checkout("Commercetools Checkout")----node2
    node2--"3. Get static assets"-->enabler("enabler")
    node2--"4. Request payment \noperations"-->processor("processor")
    processor--"5. Request payment \noperations"-->psp("Adyen payment service provider")
    psp("Adyen payment service provider")--"6. Return response"-->processor
    processor--"7. Payment management"-->payment("payment")
Loading
  1. commercetools Checkout in front-end side sends requests to composable commerce for cart creation.
  2. commercetools Checkout retrieves SDK as static assets from enabler in connector.
  3. After downloading the SDK, commercetools Checkout sends request via the SDK to endpoints exposed by processor for various payment operations.
  4. The processor transforms the received request and send them to Ayden platform.
  5. Adyen processes the payment operations and return the response to processor.
  6. The processor handles the payment persistence to composable commerce, and return the result to front-end.
  7. commercetools Checkout handles the order management in composable commerce once it receives the result from the processor.

Prerequisite

1. commercetools composable commerce API client

Users 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. In addition, please make sure the API client should have enough scope to be able to manage payment. For details, please refer to Running Application

2. various URLs from commercetools composable commerce

Various URLs from commercetools platform are required to be configured so that the connect application can handle session and authentication process for endpoints. Their values are taken as input as environment variables/ configuration for connect with variable names CTP_API_URL, CTP_AUTH_URL and CTP_SESSION_URL.

3. Adyen account credentials

Various 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. Their 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, ADYEN_ENVIRONMENT and ADYEN_CLIENT_ENVIRONMENT.

Development Guide

Regarding the development of enabler module, please refer to the following documentations:

Regarding the development of processor module, please refer to the following documentations:

Connector in commercetools Connect

Use public connector listed in connect marketplace. If any customization done, follow guidelines here to register the connector for private use.

Deployment Configuration

In order to deploy your customized connector application on commercetools Connect, it needs to be published. For details, please refer to documentation about commercetools Connect In addition, in order to support connect, the adyen payment integration connector has a folder structure as listed below

├── enabler
│   ├── src
│   ├── test
│   └── package.json
├── processor
│   ├── src
│   ├── test
│   └── package.json
└── connect.yaml

Connect 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

deployAs:
  - name: enabler
    applicationType: assets
  - name: processor
    applicationType: service
    endpoint: /
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: commercetools project key
          required: true
        - key: CTP_AUTH_URL
          description: commercetools Auth URL
          required: true
          default: https://auth.europe-west1.gcp.commercetools.com
        - key: CTP_API_URL
          description: commercetools API URL
          required: true
          default: https://api.europe-west1.gcp.commercetools.com
        - key: CTP_SESSION_URL
          description: Session API URL
          required: true
          default: https://session.europe-west1.gcp.commercetools.com
        - key: CTP_CHECKOUT_URL
          description: Checkout API URL (example - https://checkout.europe-west1.gcp.commercetools.com).
          required: true
          default: https://checkout.europe-west1.gcp.commercetools.com
        - key: CTP_CLIENT_ID
          description: commercetools client ID with manage_payments, manage_orders, view_sessions, view_api_clients & introspect_oauth_tokens scopes
          required: true
        - key: ADYEN_ENVIRONMENT
          description: Adyen environment. Must be exactly LIVE or TEST.
          required: true
          default: TEST
        - key: ADYEN_CLIENT_ENVIRONMENT
          description: Adyen Web (frontend) environment, e.g. test, live, live-us, live-au, live-apse, live-in, live-nea. If unset, derived from ADYEN_ENVIRONMENT (TEST->test, LIVE->live).
          required: false
        - key: ADYEN_MERCHANT_ACCOUNT
          description: Adyen merchant account
          required: true
        - key: ADYEN_CLIENT_KEY
          description: Adyen client key
          required: true
        - key: ADYEN_LIVE_URL_PREFIX
          description: Adyen live URL prefix
        - key: MERCHANT_RETURN_URL
          description: Merchant return URL
          required: true
        - key: CTP_JWKS_URL
          description: JWKs url (example - https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json)
          required: true
          default: https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json
        - key: CTP_JWT_ISSUER
          description: JWT Issuer for jwt validation (example - https://mc-api.europe-west1.gcp.commercetools.com)
          required: true
          default: https://mc-api.europe-west1.gcp.commercetools.com
        - key: ADYEN_APPLEPAY_OWN_MERCHANT_ID
          description: Apple merchant ID. Needed when using own certificate
          required: false
        - key: ADYEN_APPLEPAY_OWN_MERCHANT_DOMAIN
          description: Apple merchant domain. Needed when using own certificate
          required: false
        - key: ADYEN_APPLEPAY_OWN_DISPLAY_NAME
          description: Apple display name. Needed when using own certificate
          required: false
        - key: ADYEN_SHOPPER_STATEMENT
          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
          required: false
        - key: ADYEN_PAYMENT_COMPONENTS_CONFIG
          description: Adyen payment components configuration in JSON String format. For example: {"paypal":{"blockPayPalVenmoButton":false}}. Please refer to the Adyen documentation for more details.
          required: false
        - key: ADYEN_PAYMENT_METHODS_CONFIG
          description: Payment methods configuration overrides in JSON String format. For example: {"bcmc":{"supportSeparateCapture":false}}.
          required: false
        - key: ADYEN_STORED_PAYMENT_METHODS_ENABLED
          description: If set to "true" then the stored payment methods feature is enabled. Default value is "false".
          required: false
        - key: ADYEN_STORED_PAYMENT_METHODS_PAYMENT_INTERFACE
          description: The payment method payment interface value used in the commerceotools payment methods. Default value is "adyen".
          required: false
        - key: ADYEN_STORED_PAYMENT_METHODS_INTERFACE_ACCOUNT
          description: The payment method interface account value used in the commerceotools payment methods.
          required: false
        - key: ADYEN_RECURRING_PAYMENTS_ENABLED
          description: If set to "true" then payment methods are tokenized for recurring carts so they can be used for future recurring payments. Also forces the stored payment methods feature on regardless of ADYEN_STORED_PAYMENT_METHODS_ENABLED. Default value is "false".
          required: false
      securedConfiguration:
        - key: CTP_CLIENT_SECRET
          description: commercetools client secret
          required: true
        - key: ADYEN_API_KEY
          description: Adyen API key
          required: true
        - key: ADYEN_NOTIFICATION_HMAC_KEY
          description: Adyen HMAC key, used for every webhook that has no HMAC key of its own
          required: true
        - key: ADYEN_NOTIFICATION_HMAC_TOKENIZATION_WEBHOOKS_KEY
          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.)
          required: false
        - key: ADYEN_NOTIFICATION_HMAC_DONATION_WEBHOOKS_KEY
          description: Adyen HMAC donation 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.)
          required: false
        - key: ADYEN_APPLEPAY_OWN_CERTIFICATE
          description: Apple Pay own certificate
          required: false

Here you can see the details about various variables in configuration

  • CTP_PROJECT_KEY: The key of commercetools composable commerce project.
  • 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 introspect_oauth_tokens.
  • 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.
  • 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.
  • CTP_API_URL: The URL for commercetools composable commerce API. Default value is https://api.europe-west1.gcp.commercetools.com.
  • 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.
  • 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.
  • 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
  • ADYEN_ENVIRONMENT: The environment used by the backend Adyen SDK. Default value is TEST. Must be configured as exactly LIVE or TEST (case-insensitive) — any other value (e.g. a region suffix like LIVE-AU) fails connector startup. Region-specific LIVE routing is configured separately via ADYEN_LIVE_URL_PREFIX.
  • ADYEN_CLIENT_ENVIRONMENT: The environment forwarded to the Adyen Web SDK in the browser. One of test, live, live-us, live-au, live-apse, live-in, live-nea. If not set, it is derived from ADYEN_ENVIRONMENT (TEST->test, LIVE->live, non-regional). Merchants on a region-qualified LIVE account (e.g. Australia) must set this explicitly to the matching live-* value; it has no effect on backend routing.
  • ADYEN_MERCHANT_ACCOUNT: The name of adyen merchant account.
  • ADYEN_CLIENT_KEY: Client key provided by Adyen for client-side authentication. For details, please refer to Adyen client-side authentication.
  • 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.
  • MERCHANT_RETURN_URL: The return URL located in merchant platform.
  • ADYEN_API_KEY: It represents the API Key used for Ayden request authentication. For details, please refer to Ayden API key authentication.
  • 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. It verifies the standard payment webhook, and every other webhook for which no dedicated key is configured. For details, please refer to Verify HMAC signatures.
  • 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 to create the certificate. The value should be in base64 format.
  • ADYEN_APPLEPAY_OWN_MERCHANT_ID: The merchant identifier created in the Apple portal. Only needed if using an own certificate
  • 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.
  • 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.
  • ADYEN_SHOPPER_STATEMENT: The text to be shown on the shopper's bank statement. For more information, see Adyen's reference.
  • ADYEN_PAYMENT_METHODS_CONFIG: Payment methods configuration overrides in JSON format to control specific payment method behaviors such as the separate capture capability. This is useful when Adyen is configured with immediate capture, preventing the receipt of capture webhooks.
  • ADYEN_PAYMENT_COMPONENTS_CONFIG: Configuration in JSON format that is forwarded to the Adyen Web SDK components rendered by the enabler. Use the payment method name as key for a web component (for example {"paypal":{"blockPayPalVenmoButton":false}}) and nest under "embedded" for the drop-in (for example {"embedded":{"card":{"hasHolderName":false}}}). Stored cards use the "storedCard" key, see Hiding the CVC field on stored cards. Refer to the Adyen documentation for the available options per component. Malformed JSON is logged and ignored.
  • 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".
  • 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.
  • 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.
  • 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.
  • ADYEN_NOTIFICATION_HMAC_DONATION_WEBHOOKS_KEY: A specific hmac key for the donation webhooks from Adyen. If not provided then the existing "ADYEN_NOTIFICATION_HMAC_KEY" env value is used.
  • ADYEN_ORDER_EXPIRY_MINUTES: Number of minutes before an Adyen Order expires for split payments (e.g. gift card + remaining method). When the order expires, Adyen sends an ORDER_CLOSED webhook which cancels the pending split and automatically refunds any partial payments. Default value is 60.
  • ADYEN_PARTIAL_PAYMENTS_ENABLED: If set to "true" then partial payments (split payments via the Adyen Orders API, e.g. gift cards) are enabled. When enabled, the connector creates a custom type to store Adyen Order data (adyenOrderData, adyenOrderPspReference) on the CT payment resource. Only supported with the Drop-in component. Default value is "false".
  • ADYEN_RECURRING_PAYMENTS_ENABLED: If set to "true" then payment methods are tokenized for recurring carts so they can be used for future recurring payments. Enabling this also forces the stored payment methods feature on, regardless of ADYEN_STORED_PAYMENT_METHODS_ENABLED. Default value is "false".

Feature

stored payment methods

The 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.

Currently supported payment-methods for storing: (for both web-components and drop-ins)

  • card

Setting up stored payment methods

  1. update the env configuration
    1. set ADYEN_STORED_PAYMENT_METHODS_ENABLED to true. By default it is not enabled.
    2. set ADYEN_STORED_PAYMENT_METHODS_PAYMENT_INTERFACE to any string value.
    3. optionally set ADYEN_STORED_PAYMENT_METHODS_INTERFACE_ACCOUNT to any string value.
    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
  2. 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.
  3. create a new webhook in Adyen of type Recurring tokens life cycle events with the event to be send of recurring.token.created.
    1. the destination must be to <processorUrl>/notifications/tokenization
    2. choose either the existing hmac key or generate a new one
  4. ensure that before Checkout is instantiated the cart.customerId is set to the correct customer. The Adyen connector uses this for all interactions.

CT payment-methods and Adyen tokens

When 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.

The 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.

Hiding the CVC field on stored cards

A merchant account can be configured in Adyen so that the CVC (also referred to as CVV / security code) is not required when a shopper pays with a stored card. In that case the CVC input should not be rendered at all. This is done through the ADYEN_PAYMENT_COMPONENTS_CONFIG environment variable, there is no dedicated environment variable for it.

Stored cards are configured under the storedCard key - the Adyen Web SDK resolves the configuration of a stored card from that key and does not fall back to card. Configure it for the stored card web component, for the drop-in, or for both:

{
  "storedCard": { "hideCVC": true },
  "embedded": { "storedCard": { "hideCVC": true } }
}
  • The top level storedCard key configures the stored card web component. It is applied on top of the card key, so use card for all cards and storedCard for stored cards only.
  • The storedCard key nested under embedded configures the stored cards rendered by the drop-in.
  • The option name is case sensitive: hideCVC, not hideCvc. An unknown key is passed to the Adyen Web SDK and silently ignored. The value must be the JSON boolean true, a string such as "false" is truthy and would hide the field as well.

The value of the environment variable is that JSON as a single line. Covering both the web component and the drop-in:

ADYEN_PAYMENT_COMPONENTS_CONFIG={"storedCard":{"hideCVC":true},"embedded":{"storedCard":{"hideCVC":true}}}

Only the stored card web component:

ADYEN_PAYMENT_COMPONENTS_CONFIG={"storedCard":{"hideCVC":true}}

Only the drop-in:

ADYEN_PAYMENT_COMPONENTS_CONFIG={"embedded":{"storedCard":{"hideCVC":true}}}

When other components are configured as well the keys are siblings of the existing ones, so extend the existing value instead of adding it a second time:

ADYEN_PAYMENT_COMPONENTS_CONFIG={"paypal":{"blockPayPalVenmoButton":false},"storedCard":{"hideCVC":true},"embedded":{"card":{"hasHolderName":false},"storedCard":{"hideCVC":true}}}

Note that a malformed value disables the whole variable and not just the affected key - the processor logs Error parsing payment components config and continues without any component configuration at all. If the configuration appears to have no effect, check the processor logs for that message first.

Entering a new card is not affected by the above, the CVC is always requested when card details are entered for the first time. Should the CVC need to be hidden there as well, use the card key instead ({"card":{"hideCVC":true}} for the web component, {"embedded":{"card":{"hideCVC":true}}} for the drop-in).

Considerations
  • Keeping both sides in sync is the merchant's responsibility. This configuration only controls whether the field is rendered, it does not change how the merchant account is configured in Adyen. Only enable it after the CVC has been made optional for stored card payments in the Adyen Customer Area. Hiding the field while Adyen still requires the CVC results in refused payments.
  • Hiding the CVC can affect the risk assessment and, depending on the card scheme and region, the liability shift of a payment. Please consult Adyen before enabling it.
  • The Adyen Web SDK always renders its form instruction ("All fields are required unless marked otherwise.") above the stored card form, even when hiding the CVC leaves that form with nothing left to fill in. For the stored card web component, the enabler blanks out just that instruction when hideCVC is enabled, by giving the Card component its own i18n instance (delegating to the checkout's one, but returning an empty string for that specific translation key) instead of the checkout-wide one - see buildI18nWithBlankFormInstruction in enabler/src/stored/stored-payment-methods/card.ts. This does not apply to the drop-in, where the instruction is shared across all payment methods in the list and can not be scoped to the stored card item alone.

Server-to-server recurring payments

Once a payment method has been tokenized (see stored payment methods above), a backend system - for example Checkout when processing a recurring payment - can charge that stored payment method directly, server-to-server. This is a different flow from the client-to-server flows described above: there is no shopper session and no redirect involved, since the shopper is not present when the charge happens.

Endpoint

POST /operations/transactions

For the full request/response contract, see Create transaction in the processor documentation.

Requirements

  • The stored payment methods feature must be enabled (see Setting up stored payment methods) - a token to charge must already exist.
  • The caller must present an OAuth2 token with the manage_project and manage_checkout_transactions scopes.

Save displayable payment method details

This feature will ensure that on the payment.paymentMethodInfo and the payment-methods entities the custom property is filled with the specific payment details.

Currently supported payment-methods are:

  • card
  • gift cards
  • sepa

Considerations

The payment method details are stored as custom fields. See CT docs for more information. Specifically on the:

  • payment.paymentMethodInfo. (not on the payment entity itself)
  • payment-method

At any point in time entities can only have one custom-type applied. Thus if this feature is enabled it will set the payment method details overwriting anything that already exists.

Configuration

  1. ensure the configured commercetools API client has the scope manage_types.
    1. the health check will fail if the API client does not have this scope but the feature is enabled
  2. In Adyen configure the following settings. (see Adyen docs.)
    1. In Additional Data check the Card Summary in order for Adyen to return the last four digits of the card
    2. In Additional Data check the Expire date in order for Adyen to return the expiration date of the card
  3. set the ADYEN_STORE_PAYMENT_METHOD_DETAILS_ENABLED environment variable to true.
    1. this will create the predefined Checkout custom-types the next time the connector is re-deployed.
    2. enables the feature during runtime.

Partial payments (gift cards)

This feature enables split payments using the Adyen Orders API, allowing shoppers to pay part of the order amount with a gift card and the remainder with another payment method (e.g. credit card).

Note: This feature is only supported with the Drop-in component.

How it works

  1. The shopper selects a gift card in the Drop-in and enters the data.
  2. Adyen checks the balance and, if sufficient to cover part of the order, creates an Adyen Order to track the partial payment.
  3. The Drop-in then prompts the shopper to pay the remaining amount with another payment method.
  4. When the gift card authorization is confirmed, the connector stores the Adyen Order reference (adyenOrderData, adyenOrderPspReference) as custom fields on the CT payment resource so that the Order can be managed (e.g. cancelled) in subsequent sessions.
  5. If the Adyen Order expires (see ADYEN_ORDER_EXPIRY_MINUTES), Adyen sends an ORDER_CLOSED webhook. The connector handles this by marking all partial payments as reversed in CT.

Re-starting a partial payment flow

If the shopper abandons the flow and a new session is created while a previous Adyen Order is still active, the connector automatically cancels any existing open Adyen Orders before creating the new session. This means:

  • Adyen Orders with an approved (authorized or captured, not reverted) CT payment that carries adyenOrderData are cancelled via the Adyen Orders API.
  • The new session amount is recalculated optimistically: the gift card payments are excluded from the total immediately, without waiting for Adyen to confirm the cancellation via the ORDER_CLOSED webhook. The final CT payment deduction happens when that webhook arrives.
  • Cancellation failures are logged but do not block the new session from being created.

UI limitation: because a new Adyen session must always be created from scratch (to reflect any cart changes and maintain security), the Drop-in cannot resume a partially-paid state. The shopper will need to re-apply the gift card in the new session.

Configuration

  1. Ensure the configured commercetools API client has the scope manage_types (needed to create the custom type on deploy).
  2. Set ADYEN_PARTIAL_PAYMENTS_ENABLED to "true". On the next re-deploy, the connector will create the commercetools-checkout-adyen-payment-details custom type.
  3. Optionally configure ADYEN_ORDER_EXPIRY_MINUTES (default: 60) to control how long an open Adyen Order stays active before expiring.
  4. In the Adyen Customer Area, on your webhook's Additional settings tab, under Payment, it is recommended to enable "Include a success boolean for the payments listed in an ORDER_CLOSED event". This makes Adyen report the approval status of each partial payment directly in the ORDER_CLOSED webhook.

Custom type created

Type key Resource Fields
commercetools-checkout-adyen-payment-details payment adyenOrderData (String), adyenOrderPspReference (String), adyenDonationToken (String), adyenDonationAmount (Money), adyenDonationState (Enum: Pending, Success, Failure)

If the CT payment already has a merchant-defined custom type applied, the connector will add its fields to that existing type rather than replacing it.

Adyen Giving (donations)

For a full integration guide (creating the checkout session, loading the enabler, mounting the donation form, callbacks and known errors), see Adyen Giving. This section only covers how the connector itself persists and reports on a donation.

Donation result on the payment

The donation is charged against the payment the shopper already made, so its outcome is recorded on that same commercetools payment, in the adyenDonationAmount and adyenDonationState fields of the commercetools-checkout-adyen-payment-details custom type. adyenDonationState is Pending while Adyen has not settled the donation yet, and Success or Failure once it has.

A donation token is good for a single donation, so once one is charged (Pending or Success) the payment is no longer donatable: both the donation configuration and the donation itself are then rejected with PaymentNotEligible, which keeps the campaign from being rendered again when the shopper reloads the confirmation page. A Failure leaves the payment donatable, since nothing was charged.

Donation webhook

  1. Set ADYEN_GIVING_ENABLED to "true" and ensure the configured commercetools API client has the scope manage_types (needed to create the custom type on deploy).
  2. In the Adyen Customer Area, create a webhook of type Adyen Giving with the event Donation enabled. Adyen sends this event for the charity account the donation was credited to, so set the webhook up on the account that receives the donations.
    1. the destination must be to <processorUrl>/notifications/donations
    2. choose between using a new HMAC key by setting ADYEN_NOTIFICATION_HMAC_DONATION_WEBHOOKS_KEY or, if unset, the connector will use the HMAC key of ADYEN_NOTIFICATION_HMAC_KEY

Blocking payment methods per cart

Merchants can hide specific payment methods for an individual cart by setting the optional adyenBlockedPaymentMethods custom field on it. The field must be of type Set of String and must be added to the custom type the cart already uses, since the connector does not create one.

If the cart does not use a custom type yet, this is a minimal one that defines the field. Carts and orders share the order resource type:

{
  "key": "my-cart-custom-type",
  "name": { "en": "Cart custom fields" },
  "resourceTypeIds": ["order"],
  "fieldDefinitions": [
    {
      "name": "adyenBlockedPaymentMethods",
      "label": { "en": "Adyen blocked payment methods" },
      "required": false,
      "type": { "name": "Set", "elementType": { "name": "String" } }
    }
  ]
}

With the type in place, this cart update sets the field so that PayPal and Giftcard are not offered on that cart:

{
  "version": 1,
  "actions": [
    {
      "action": "setCustomType",
      "type": { "typeId": "type", "key": "my-cart-custom-type" },
      "fields": {
        "adyenBlockedPaymentMethods": ["paypal", "giftcard"]
      }
    }
  ]
}

If the cart already has the custom type applied, use the setCustomField action with name and value instead.

On a recurring cart, they are combined with the payment methods that the connector already blocks because they cannot be used for recurring payments.

Payment methods configuration overrides

Problem

Some payment methods don't support separate capture (manual capture), meaning Adyen immediately captures the funds after authorization without sending a capture webhook. Additionally, some payment methods that do support separate capture may have immediate capture configured in the Adyen console.

In both scenarios, Adyen does not send the CAPTURE webhook event to notify the connector that the payment has been captured. This causes the commercetools payment state to become out of sync with the actual Adyen payment status, as commercetools is unaware that the funds have been captured.

Solution

The connector maintains a static list of payment methods and their capture behavior. When the authorization confirmation is received for methods with supportSeparateCapture: false, the connector automatically creates a Charge transaction in commercetools to keep the payment status in sync with Adyen.

However, certain payment methods (e.g., Bancontact/bcmc) can have this behavior overridden on a per-merchant basis. To allow users to adjust the capture behavior without code changes or connector releases, the configuration has been externalized.

Configuration

Use the ADYEN_PAYMENT_METHODS_CONFIG environment variable to override payment method configurations.

Format: JSON string with payment method configurations.

Merging logic: The environment variable values take precedence over the hardcoded defaults.

Error handling: Malformed JSON is logged as a warning and ignored; the default configuration is used.

Structure: The configuration object follows this schema:

{
  [adyenPaymentMethodCode: string]: {
    supportSeparateCapture: boolean;
  }
}
  • Key: The Adyen payment method code (e.g., bcmc, ideal, eps). See Adyen's technical documentation for more details.
  • Value: An object with a supportSeparateCapture property (boolean)
    • true: The payment method supports manual/deferred capture
    • false: The payment method uses immediate capture only

Default configuration: The following payment methods use immediate capture by default:

{
  "bcmc": { "supportSeparateCapture": false },
  "bcmc_mobile": { "supportSeparateCapture": false },
  "blik": { "supportSeparateCapture": false },
  "eps": { "supportSeparateCapture": false },
  "ideal": { "supportSeparateCapture": false },
  "molpay_ebanking_fpx_MY": { "supportSeparateCapture": false },
  "onlineBanking_PL": { "supportSeparateCapture": false },
  "swish": { "supportSeparateCapture": false }
}

Important: Ensure payment method configurations are accurate and aligned with your Adyen merchant account setup. Incorrect configuration may cause the commercetools payment state to become out of sync with the actual Adyen payment status. Misconfiguration is the responsibility of the merchant, not the connector.

Example: Enabling manual capture for Bancontact

By default, Bancontact (bcmc and bcmc_mobile) uses immediate capture. However, Adyen Support can enable "Deferred sales" (separate/manual capture) for eligible merchants and MCCs. Once enabled on the Adyen side, configure the connector to recognize this:

{
  "bcmc": { "supportSeparateCapture": true },
  "bcmc_mobile": { "supportSeparateCapture": true }
}

Behavior

  • If supportSeparateCapture is false: The connector automatically creates a Charge transaction upon receiving the authorization confirmation, immediately synchronizing the payment state with Adyen's immediate capture.
  • If supportSeparateCapture is true: The connector waits for the CAPTURE webhook from Adyen before creating the Charge transaction, supporting manual/deferred capture workflows.

Interface interaction logging

When enabled, the connector stores every request/response exchanged with Adyen as a payment-interface-interaction custom field on the commercetools Payment resource. This is useful for debugging payment flows or for extracting information that the connector does not explicitly persist.

Covered operations

The following operations are recorded:

Operation Interaction type stored
Create payment CreatePayment
Confirm payment (additional details) ConfirmPayment
Capture CapturePayment
Refund RefundPayment
Cancel CancelPayment
Reverse ReversePayment
Incoming Adyen notification Notification
Donation MakeDonation
Incoming Adyen donation notification DonationNotification

Each interaction records the full request and response .

Sensitive field masking

Before storing any payload, the connector automatically masks sensitive data to avoid persisting PCI or PII information:

  • paymentMethod block: every sub-field except type is replaced with ***. This covers encrypted card fields (encryptedCardNumber, encryptedSecurityCode, etc.), raw card numbers, Apple Pay tokens, Google Pay tokens, and any other payment-method-specific data regardless of field name.

  • Named fields at any nesting depth: the following field names are masked wherever they appear in the payload, including inside additionalData dotted keys (e.g. "tokenization.storedPaymentMethodId"):

    Field Category
    shopperEmail PII
    shopperIP PII
    holderName PII
    storedPaymentMethodId PII
    riskData Opaque SDK blob
    sdkData Opaque SDK blob
    checkoutAttemptId Opaque SDK blob
    clientData Opaque SDK blob

All other fields (amounts, references, result codes, event codes, merchant account, etc.) are stored as-is.

Configuration

Set the environment variable ADYEN_SAVE_INTERFACE_INTERACTIONS to "true". The default value is "false" (disabled).

When enabled, the required commercetools custom type (commercetools-checkout-payment-interface-interaction) is created automatically on connector deploy, no manual setup is needed.

Development

In order to get started developing this connector certain configuration are necessary, most of which involve updating environment variables in both services (enabler, processor).

Configuration steps

1. Environment Variable Setup

Navigate 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.

cp .env.template .env

2. Spin Up Components via Docker Compose

With 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;

docker compose up

This command would start 3 required services, necessary for development

  1. JWT Server
  2. Enabler
  3. Processor

About

No description or website provided.

Topics

Resources

Security policy

Stars

3 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages