Customization guide

You can customize your shoppers' checkout experience by customizing checkout flows or payment methods. Custom code that you add in a separate cartridge will not be transpiled and will be preserved when you upgrade to a new cartridge version.

When you add custom code in a separate cartridge, you can continue to receive cartridge support from Adyen for supported versions . If you customize the default Adyen cartridge, we may be unable to provide cartridge support, and it becomes harder to upgrade and troubleshoot your integration.

Therefore, we strongly discourage making changes directly to the/src/cartridges directory. If you have already applied customizations to these directories, we recommend to extract your custom code from the default cartridge

There are two types of customizations you can apply:

• Adding your custom code in a separate cartridge to customize checkout flows.
• Customizing payment methods by adding custom configuration.
• Implement your own pre-authorization checks

Add custom code in a separate cartridge

You can customize your integration by adding a separate cartridge before the Adyen cartridge to override default configurations.

This setup is available by default on v23.2.1 or later, and enables you to temporarily remove custom code when upgrading or troubleshooting your integration.

To add custom code in a separate cartridge:

1. Create a new cartridge in your /src/cartridges directory and name it, for example: int_custom_cartridge.
2. Add your custom code to the new cartridge and update metadata if needed
3. Update the name property in the package.json file to the name you chose, for example int_custom_cartridge.
4. Run the following command to make sure all unit tests are passing:

   npm install

5. Run the following command:

   npm run build

6. Add the new cartridge to your cartridge path:
   1. Go to Administration > Sites > Manage Sites > [yourSite] > Settings.
   2. In the Cartridges box, add the new cartridge before the Adyen cartridges.
   3. Select Apply.
7. Modify or add end-to-end tests as needed.
8. Run the end-to-end tests to make sure your custom code works correctly.

Watch how to customize your SFCC cartridge:

Extract custom code from the default cartridge

If you have customized the source directory or the cartridges directory, you can extract your custom code in a separate cartridge later to:

• Upgrade your integration.
• Switch to the recommended way to customize.

To extract your custom code:

1. In our GitHub releases, find the version that you currently use.
2. In your local project, locate your custom code. Your custom code may be in the /src, /cartridges or both directories.
3. Separate your custom code from the default cartridge code:
   1. Clone the public release with your current cartridge version into your local project:

      git checkout tag/YOUR_CURRENT_CARTRIDGE_VERSION

   2. Make sure that your main project has two nested folders for the cloned default Adyen cartridge and for your customized integration.
   3. Run the following command in your terminal to compare the Adyen default cartridge code and your integration code to locate all the file changes:

      diff -r FOLDER_1_NAME FOLDER_2_NAME

      If you are using Windows, use the following command instead:

      comp /r FOLDER_1_NAME FOLDER_2_NAME

      Alternatively, to view the file changes in human readable format instead of machine readable format, you can use diff tools that are available on GitHub.

   4. Extract the custom code that you located.
4. Add the custom code in a separate cartridge.

Customize payment methods

The Adyen Salesforce Commerce Cloud (SFCC) checkout configuration integrates Adyen's wide range of payment methods seamlessly into Salesforce Commerce Cloud using the Storefront Reference Architecture (SFRA).

Each payment method can be configured individually, so that you can customize the checkout flow based on your needs. The payment methods that you can add custom configuration to are:

• Amazon Pay
• Apple Pay
• Bancontact (BCMC)
• Boleto
• Card (credit/debit)
  • Stored Cards
  • Click to Pay
• Cash App
• Gift Cards
• Google Pay
• Klarna
• PayPal
• UPI (India)

Featured configuration options

Each payment method can be customized with the following featured configuration parameters.

For the full list of configuration options for each payment method, go to the Web Component page for the payment method. For example, for card, go to the Card Web Component page.

You can use these configuration options to optimize usability and compliance based on region, shopper preferences, or business rules.

How to customize

To customize the configuration for a payment method:

1. In the cartridge, go to: /src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/paymentMethodsConfiguration.
2. Open the corresponding file for the payment method. For example: card.js for card, paypal.js for PayPal, or klarna.js for Klarna.
3. Edit the configuration.

If applicable:

4. Rebuild your code.
5. Deploy the changes to your Salesforce Commerce Cloud environment.

The following example shows configuration for the card payment method.

Implement pre-authorization checks

On v25.4.0 or later versions of the cartridge, you can implement your own pre-authorization checks. This lets you, for example, to make a request to your third-party risk provider for risk checks before the Adyen cartridge makes a /payments request to authorize the payment.

To add your own pre-authorization logic:

1. In the cartridge, go to /src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/hooks/payment/preAuthorizationHandling.js.
2. Using the app.payment.pre.auth pre-authorization hook, add your custom logic.
3. To let the cartridge proceed or stop with payment authorization after your checks:
   • Return error: true to prevent the cartridge from making the payment request if your pre-authorization checks fail.
   • Return error: false to proceed with the payment request if your pre-authorization checks succeed.

Troubleshoot common issues

• Payment method display issues:
  • Make sure that you set showPayButton: true.
  • Make sure that the payment method is enabled in live Customer Area.
• API errors: make sure that your Adyen API credentials are configured correctly in your SFCC Business Manager.
• Customization issues: make sure that configuration files have been modified and deployed correctly.

See also