Broadleaf Microservices
  • v1.0.0-latest-prod

Adyen Environment Setup

Prerequisites

  • Users must register their own test accounts with Adyen in order to use the BroadleafCommerce Adyen payment functionality in a test environment.

  • Please familiarize yourself with the Adyen Drop-in documentation before proceeding: Integration checklist

Adding the Adyen Services Dependency

Once you have registered a merchant account with Adyen, add the Broadleaf Adyen Maven dependency to your PaymentTransactionServices project.

<dependency>
    <groupId>com.broadleafcommerce.microservices</groupId>
    <artifactId>broadleaf-adyen</artifactId>
</dependency>
Note
 The dependency’s version will be pulled from the Broadleaf release train pom.xml.

Authentication Service Data Configuration

To access the endpoint used to initiate an Adyen checkout session (part of the Drop-in frontend integration), the following permissions must be defined:

-- Permissions to create the payment session
INSERT INTO auth.blc_security_scope ("id", "name", "open")
VALUES ('-1030', 'ADYEN_CREATE_SESSION', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES ('-1030', 'ADYEN_CREATE_SESSION', 'Y', '-1030');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES ('-1031', 'ADYEN_CREATE_SESSION', 'Y', '-100');

-- Add permission to customer role
INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm")
VALUES ('-1030', 'N', '1970-01-01 00:00:00.000', 'ALL_ADYEN_CREATE_SESSION', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id)
VALUES ('-100', '-1030');

-- Add permission to anonymous client (used for anonymous customers)
INSERT INTO auth.blc_client_scopes ("id", "scope")
VALUES ('anonymous', 'ADYEN_CREATE_SESSION');
INSERT INTO auth.blc_client_permissions ("id", "permission")
VALUES ('anonymous', 'ALL_ADYEN_CREATE_SESSION');
INSERT INTO auth.blc_client_scopes ("id", "scope")
VALUES ('openapi', 'ADYEN_CREATE_SESSION');
INSERT INTO auth.blc_client_permissions ("id", "permission")
VALUES ('openapi', 'ALL_ADYEN_CREATE_SESSION');

To access endpoints used to interact with Adyen-store saved payment methods, the following permissions must be defined:

-- Permissions to create/delete the saved payment methods
INSERT INTO auth.blc_security_scope ("id", "name", "open")
VALUES ('-1040', 'ADYEN_SAVED_PAYMENT_METHODS', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES ('-1040', 'ADYEN_SAVED_PAYMENT_METHODS', 'Y', '-1040');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES ('-1041', 'ADYEN_SAVED_PAYMENT_METHODS', 'Y', '-100');

-- Add permission to customer role
INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm")
VALUES ('-1040', 'N', '1970-01-01 00:00:00.000', 'ALL_ADYEN_SAVED_PAYMENT_METHODS', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id)
VALUES ('-100', '-1040');

Configuring Adyen

  • Metadata in webhook payloads: To effectively communicate the Broadleaf Application & Tenant Ids via the webhook payloads, you’ll need to request that Adyen includes metadata values from the transaction requests in the webhook payloads.

  • Capture configuration: Our Authorize and AuthorizeAndCapture transactions are configured to use manual and immediate, automatic captures respectively. Make sure that your Capture delay is set to Immediate.

    • Adyen also supports the concept of delayed automatic capture (e.g. automatically capture in 7 days). With that being said, manual or immediate, automatic captures work best with the current state of the framework.

  • Partial Capture configuration: This integration is built assuming that multiple partial captures are supported. To support this functionality, you’ll need to request that Adyen enables this feature.

    • By default, Adyen automatically releases any authorized amounts that are not captured, when a partial capture is requested. If you wish to align with Adyen’s default behavior for partial captures, then you’ll need to declare FORCED_REVERSE_AUTH_WITH_PARTIAL_CAPTURE via the broadleaf.adyen.gateway.supported-features property list. With this in place, the framework will automatically record a ReverseAuthorize transaction for any remaining authorized amount when a partial capture is successfully executed.

Configuring Your Integration

Create API credentials for the Adyen API. Store your API key and client key as you will not be able to copy them after creating your credentials.

Select the following Permissions:

  • Checkout webservice role

  • Merchant Recurring role

Configuration for the Adyen Service

broadleaf:
  adyen:
    apiKey: {api key}
    merchantAccount: {Merchant Account identifier}
    platformStore: {Optional - Adyen Platform Store identifier} (1)
    hmacKey: {HMAC key for webhook signature validation} (2)

  1. The broadleaf.adyen.platform-store property is only needed if you’re using an Adyen Platform account setup.

  2. You can get the HMAC key later when configuring the webhook endpoint

Note

These properties are application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

  • broadleaf.adyen.tenant.mytenant.apiKey={api_key}

  • broadleaf.adyen.application.myapplication.apiKey={api_key}

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

Cart Operation Service Configuration

broadleaf:
  cartoperation:
    service:
      checkout:
        external-payment-transaction:
          callback-redirection:
            storefrontBaseUrl: https://storefront.com
            default-redirect-uri: /checkout/payment-confirmation
        checkout-transaction-types:
          ADYEN: AUTHORIZE
        checkout-payment-method-options:
          - payment-method-type: CREDIT_CARD
            payment-method-gateway-type: ADYEN
Note

These properties are application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

  • broadleaf.cartoperation.service.checkout.tenant.mytenant.checkout-transaction-types.ADYEN=AUTHORIZE

  • broadleaf.cartoperation.service.checkout.application.myapplication.checkout-transaction-types.ADYEN=AUTHORIZE

The same works for the external-payment-transaction.callback-redirection configuration.

  • broadleaf.cartoperation.service.checkout.external-payment-transaction.callback-redirection.tenant.mytenant.storefrontBaseUrl=https://storefront.com

  • broadleaf.cartoperation.service.checkout.external-payment-transaction.callback-redirection.application.myapplication.storefrontBaseUrl=https://storefront.com

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

The external-payment-transaction configuration is used for the Improved 3DS authentication interaction that requires redirecting customers to the external page.

ADYEN should be added to the following property to declare when transactions for this gateway should be executed, relative to other gateways, during checkout processing.

broadleaf:
  cartoperation:
    service:
      checkout:
        payment-gateway-priorities:
          - ...
          - ADYEN
          - ...
Note

This property is application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

  • broadleaf.cartoperation.service.checkout.tenant.mytenant.checkout-transaction-types.ADYEN=AUTHORIZE

  • broadleaf.cartoperation.service.checkout.application.myapplication.checkout-transaction-types.ADYEN=AUTHORIZE

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

Configuration for OrderOperationServices

ADYEN should be added to the following property to declare when ReverseAuthorize or Refund transactions for this gateway should be executed, relative to other gateways, when cancelling a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        cancel-payment-gateway-priorities:
          - ...
          - ADYEN
          - ...

ADYEN should be added to the following property to declare when Capture transactions for this gateway should be executed, relative to other gateways, when capturing payment for a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        capture-payment-gateway-priorities:
          - ...
          - ADYEN
          - ...

ADYEN should be added to the following property to declare when Refund transactions for this gateway should be executed, relative to other gateways, when refunding payment for a fulfillment return.

broadleaf:
  orderoperation:
    service:
      payment:
        refund-payment-gateway-priorities:
          - ...
          - ADYEN
          - ...

To support the async nature of obtaining transaction results for Adyen Capture, Refund, & ReverseAuth transactions relative to fulfillment & return actions in OrderOps, the following property must be declared:

broadleaf:
  orderoperation:
    async-payment-transaction-support:
      enabled: true

Webhook Configuration

  1. Create the Standard webhook and specify the https://{host}/api/payment/webhooks/ADYEN URL.

  2. Generate the new HMAC key and add it to the broadleaf.adyen.hmacKey configuration.

  3. Select the following Events:

    • AUTHORISATION

    • CANCELLATION

    • CAPTURE

    • REFUND

Testing Locally

To test the integration locally, you’ll want to configure your environment to expose access to your application via ngrok. This is especially helpful for testing the full integration including webhooks.

  1. Add the following configuration:

     broadleaf:
   tenant:
     urlresolver:
       application:
         port: '443'
         domain: 'ngrok-free.app'

  2. Execute ngrok http https://{yourAppUri}/ to build the tunnel to your local app. Replace yourAppUri with your app URI e.g myapp.localhost:8456. This will generate the domain e.g. https://c746-176-115-97-170.ngrok-free.app (used in the steps below).

  3. Provide the ngrok url to the following CartOps property: broadleaf.cartoperation.service.checkout.external-payment-transaction.callback-redirection.storefront-base-url=https://c746-176-115-97-170.ngrok-free.app

  4. Run your app locally as usual

  5. In the Admin panel go to the Security → Authorization Servers, open your app configuration and click on Authorized Clients tab (/authorization-servers/{yourAppId}?form=authorizedClients). Add the Redirect Urls - https://c746-176-115-97-170.ngrok-free.app/callback and https://c746-176-115-97-170.ngrok-free.app/silent-callback.html to your Authorized Client.

  6. In the Admin panel go to the Tenant Management → Applications and open your application configuration from the list. In the Application Identifier field replace the value with ngrok-free.app. This step is needed to resolve your application. See com.broadleafcommerce.tenant.web.endpoint.TenantResolverEndpoint.

  7. In the Adyen portal, provide the ngrok URL as an "allowed origin" in the "Client settings" portion of your API credentials.

If you have setup everything correctly, you should be able to open your app by hitting the ngrok-provided URL.

Note
 Also see how to add a payment via the Commerce SDK.

Going to Production

The following configuration is a default configuration for the API provider. You need to change the apiBaseUrl for the live API requests.

broadleaf:
  adyen:
    provider:
      apiBaseUrl: https://checkout-test.adyen.com

Beyond this, you’ll also need to declare production credentials, using the same properties mentioned above:

broadleaf:
  adyen:
    apiKey: {api key}
    merchantAccount: {Merchant Account identifier}
    platformStore: {Optional - Adyen Platform Store identifier}
    hmacKey: {HMAC key for webhook signature validation}

In CartOps, you’ll likely need to modify the 3DS callback storefront base url:

broadleaf:
  cartoperation:
    service:
      checkout:
        external-payment-transaction:
          callback-redirection:
            storefrontBaseUrl: https://storefront.com