Plugin icon

SFRA customization guide

Learn how to customize your checkout for SFRA integrations.

There are different ways to customize your shoppers' checkout experience.

If 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 could be harder to upgrade and troubleshoot your integration.

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 /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:

Customize the default Adyen cartridge

Customize the source directory

You can customize your integration by modifying the default Adyen cartridge code in the source directory.

To do this, add your custom code directly into the /src directory, using JavaScript ES6.

Files in the /src directory contain modern JavaScript (ES6, MobX) code that is not supported by Salesforce Commerce Cloud. During the build process, the JavaScript ES6 code in the /src directory is converted to ES5, by transpiling, compiling, and uploading the auto-generated code to the /cartridges directory.

Customize the cartridges directory

You can customize your integration by modifying the default Adyen cartridge code in the cartridges directory.

To do this, add custom code directly into the /cartridges directory, using JavaScript ES5.

The customizations that you add to /cartridges folders will not be transpiled.

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:

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.

See also