{"title":"Customization guide","category":"default","creationDate":1685544480,"content":"<div class=\"additional-info-block output-inline\">\n<h5 class=\"article__heading additional-info-block__title\">Read more<\/h5><div class=\"additional-info-block__body\"><p>Read more about customizing SFRA cartridges in <a href=\"https:\/\/developer.salesforce.com\/docs\/commerce\/sfra\/guide\/b2c-customizing-sfra.html\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Salesforce documentation<\/a>.<\/p><\/div><\/div>\n\n<p>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.<\/p>\n<p>When you add custom code in a separate cartridge, you can continue to receive cartridge support from Adyen for <a href=\"\/pt\/plugins\/salesforce-commerce-cloud\/#support-levels\">supported versions<\/a> . 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.<\/p>\n<p>Therefore, we strongly discourage making changes directly to the<code>\/src\/cartridges<\/code> directory. If you have already applied customizations to these directories, we recommend to <a href=\"https:\/\/docs.adyen.com\/plugins\/salesforce-commerce-cloud\/sfra\/customization-guide\/#extract-custom-code-from-the-default-cartridge\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">extract your custom code from the default cartridge<\/a><\/p>\n<p>There are two types of customizations you can apply:<\/p>\n<ul>\n<li><a href=\"#add-custom-code-in-a-separate-cartridge\">Adding your custom code in a separate cartridge<\/a> to customize checkout flows.<\/li>\n<li><a href=\"#customize-payment-methods\">Customizing payment methods<\/a> by adding custom configuration.<\/li>\n<li><a href=\"#implement-pre-authorization-checks\">Implement your own pre-authorization checks<\/a><\/li>\n<\/ul>\n<h2 id=\"add-custom-code-in-a-separate-cartridge\">Add custom code in a separate cartridge<\/h2>\n<p>You can customize your integration by adding a separate cartridge before the Adyen cartridge to override default configurations.<\/p>\n<p>This setup is available by default on <a href=\"https:\/\/github.com\/Adyen\/adyen-salesforce-commerce-cloud\/releases\/tag\/23.2.1\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">v23.2.1<\/a> or later, and enables you to temporarily remove custom code when upgrading or troubleshooting your integration.<\/p>\n<p>To add custom code in a separate cartridge:<\/p>\n<ol>\n<li>Create a new cartridge in your <strong>\/src\/cartridges<\/strong> directory and name it, for example: <strong>int_custom_cartridge<\/strong>.<\/li>\n<li>Add your custom code to the new cartridge and update metadata if needed<\/li>\n<li>Update the <code>name<\/code> property in the <strong>package.json<\/strong> file to the name you chose, for example <strong>int_custom_cartridge<\/strong>.<\/li>\n<li>Run the following command to make sure all unit tests are passing:\n<pre><code class=\"language-bash\">npm install<\/code><\/pre><\/li>\n<li>Run the following command:\n<pre><code class=\"language-bash\">npm run build<\/code><\/pre><\/li>\n<li>Add the new cartridge to your <a href=\"\/pt\/plugins\/salesforce-commerce-cloud\/sfra\/set-up-the-cartridge?plugin=Salesforce%20SFRA&amp;integration=cartridge#step-1-set-up-the-cartridge-path\">cartridge path<\/a>:\n<ol>\n<li>Go to\u00a0<strong>Administration<\/strong>\u00a0&gt;\u00a0<strong>Sites<\/strong>\u00a0&gt;\u00a0<strong>Manage Sites<\/strong> &gt; <strong>[yourSite]<\/strong> &gt; <strong>Settings<\/strong>.<\/li>\n<li>In the <strong>Cartridges<\/strong> box, add the new cartridge before the Adyen cartridges.<\/li>\n<li>Select <strong>Apply<\/strong>.<\/li>\n<\/ol><\/li>\n<li>Modify or add end-to-end tests as needed.<\/li>\n<li>Run the end-to-end tests to make sure your custom code works correctly.<\/li>\n<\/ol>\n<p>Watch how to customize your SFCC cartridge:<\/p>\n<iframe src=\"https:\/\/player.vimeo.com\/video\/843123373\" width=\"640\" height=\"360\" frameborder=\"0\" allow=\"autoplay; fullscreen; picture-in-picture\" allowfullscreen><\/iframe>\n<h2>Extract custom code from the default cartridge<\/h2>\n<p>If you have customized the <a href=\"#customize-the-source-directory\">source directory<\/a> or the <a href=\"#customize-the-cartridges-directory\">cartridges directory<\/a>, you can extract your custom code in a separate cartridge later to:<\/p>\n<ul>\n<li><a href=\"\/pt\/plugins\/salesforce-commerce-cloud\/sfra\/upgrade\/#customized-integration\">Upgrade your integration<\/a>.<\/li>\n<li>Switch to the <a href=\"#add-custom-code-in-a-separate-cartridge\">recommended way to customize<\/a>.<\/li>\n<\/ul>\n<p>To extract your custom code:<\/p>\n<ol>\n<li>In our <a href=\"https:\/\/github.com\/Adyen\/adyen-salesforce-commerce-cloud\/releases\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">GitHub releases<\/a>, find the version that you currently use.<\/li>\n<li>In your local project, locate your custom code. Your custom code may be in the <code>\/src<\/code>, <code>\/cartridges<\/code> or both directories.<\/li>\n<li>Separate your custom code from the default cartridge code:\n<ol>\n<li>Clone the public release with your current cartridge version into your local project:\n<pre><code class=\"language-bash\">git checkout tag\/YOUR_CURRENT_CARTRIDGE_VERSION<\/code><\/pre><\/li>\n<li>Make sure that your main project has two nested folders for the cloned default Adyen cartridge and for your customized integration.<\/li>\n<li>Run the following command in your terminal to compare the Adyen default cartridge code and your integration code to locate all the file changes:\n<pre><code class=\"language-bash\">diff -r FOLDER_1_NAME FOLDER_2_NAME<\/code><\/pre>\n<p>If you are using Windows, use the following command instead:<\/p>\n<pre><code class=\"language-powershell\">comp \/r FOLDER_1_NAME FOLDER_2_NAME<\/code><\/pre>\n<p>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. <\/p><\/li>\n<li>Extract the custom code that you located.<\/li>\n<\/ol><\/li>\n<li><a href=\"#add-custom-code-in-a-separate-cartridge\">Add the custom code in a separate cartridge<\/a>.<\/li>\n<\/ol>\n<h2>Customize payment methods<\/h2>\n<p>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).<\/p>\n<p>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:<\/p>\n<ul>\n<li>Amazon Pay<\/li>\n<li>Apple Pay<\/li>\n<li>Bancontact (BCMC)<\/li>\n<li>Boleto<\/li>\n<li>Card (credit\/debit)\n<ul>\n<li>Stored Cards<\/li>\n<li>Click to Pay<\/li>\n<\/ul><\/li>\n<li>Cash App<\/li>\n<li>Gift Cards<\/li>\n<li>Google Pay<\/li>\n<li>Klarna<\/li>\n<li>PayPal<\/li>\n<li>UPI (India)<\/li>\n<\/ul>\n<h3>Featured configuration options<\/h3>\n<p>Each payment method can be customized with the following featured configuration parameters.<\/p>\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th>Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>showPayButton<\/code><\/td>\n<td>Set to <strong>false<\/strong> to hide the payment button in the checkout form.<\/td>\n<\/tr>\n<tr>\n<td><code>environment<\/code><\/td>\n<td>The front-end environment. Possible values: <br>- <strong>test<\/strong> <br>- <strong>live<\/strong><\/td>\n<\/tr>\n<tr>\n<td><code>onSubmit<\/code><\/td>\n<td>Called when the shopper selects the pay button to submit their payment information.<\/td>\n<\/tr>\n<tr>\n<td><code>onError<\/code><\/td>\n<td>Called when an error occurs during the payment.<\/td>\n<\/tr>\n<tr>\n<td><code>onAuthorised<\/code><\/td>\n<td>Called when the payment is successfully authorized.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>For the full list of configuration options for each payment method, go to the Web Component page for the <a href=\"\/pt\/payment-methods\">payment method<\/a>. For example, for card, go to the <a href=\"\/pt\/payment-methods\/cards\/web-component\">Card Web Component page<\/a>.<\/p>\n<p>You can use these configuration options to optimize usability and compliance based on region, shopper preferences, or business rules.<\/p>\n<h3>How to customize<\/h3>\n<p>To customize the configuration for a payment method:<\/p>\n<ol>\n<li>In the cartridge, go to: <code>\/src\/cartridges\/app_adyen_SFRA\/cartridge\/client\/default\/js\/adyen\/checkout\/paymentMethodsConfiguration<\/code>.<\/li>\n<li>Open the corresponding file for the payment method. For example: <code>card.js<\/code> for card, <code>paypal.js<\/code> for PayPal, or <code>klarna.js<\/code> for Klarna.<\/li>\n<li>Edit the configuration.<\/li>\n<\/ol>\n<p>If applicable:<\/p>\n<ol start=\"4\">\n<li>Rebuild your code.<\/li>\n<li>Deploy the changes to your Salesforce Commerce Cloud environment.<\/li>\n<\/ol>\n<p>The following example shows configuration for the card payment method.<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Example card configuration'\" :id=\"''\" :code-data='[{\"language\":\"javascript\",\"tabTitle\":\"\",\"content\":\"const cardConfiguration = {\\n  hasHolderName: true,\\n  holderNameRequired: false,\\n  enableStoreDetails: true,\\n  clickToPayConfiguration:  {\\n                \\\/\\\/ Settings for Click to Pay.\\n            },\\n  exposeExpiryDate: true,\\n  onChange: function(state, component) {\\n                \\\/\\\/ Handle the state change.\\n            },\\n  onSubmit: function(state, component) {\\n                \\\/\\\/ Handle submitting the payment details.\\n            },\\n  onFieldValid: function(fieldType, isValid) {\\n                \\\/\\\/ Field validation.\\n            },\\n  onBrand: function(brandObject) {\\n                \\\/\\\/ Detect the card brand.\\n            }\\n};\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2 id=\"implement-pre-authorization-checks\">Implement pre-authorization checks<\/h2>\n<p>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  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Checkout\/latest\/post\/payments\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/payments<\/a> request to authorize the payment.<\/p>\n<p>To add your own pre-authorization logic:<\/p>\n<ol>\n<li>In the cartridge, go to <code>\/src\/cartridges\/int_adyen_SFRA\/cartridge\/adyen\/scripts\/hooks\/payment\/preAuthorizationHandling.js<\/code>.<\/li>\n<li>Using the <code>app.payment.pre.auth<\/code> pre-authorization hook, add your custom logic.<\/li>\n<li>To let the cartridge proceed or stop with payment authorization after your checks:\n<ul>\n<li>Return <code>error<\/code>: <strong>true<\/strong> to prevent the cartridge from making the payment request if your pre-authorization checks fail.<\/li>\n<li>Return <code>error<\/code>: <strong>false<\/strong> to proceed with the payment request if your pre-authorization checks succeed.<\/li>\n<\/ul><\/li>\n<\/ol>\n<h2>Troubleshoot common issues<\/h2>\n<ul>\n<li>Payment method display issues:\n<ul>\n<li>Make sure that you set <code>showPayButton<\/code>: <strong>true<\/strong>.<\/li>\n<li>Make sure that the payment method is enabled in <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">live Customer Area<\/a>.<\/li>\n<\/ul><\/li>\n<li>API errors: make sure that your Adyen API credentials are configured correctly in your SFCC Business Manager.<\/li>\n<li>Customization issues: make sure that configuration files have been modified and deployed correctly.<\/li>\n<\/ul>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/plugins\/salesforce-commerce-cloud\/sfra\/troubleshooting\"\n                        target=\"_self\"\n                        >\n                     Troubleshooting your integration \n                <\/a><\/li><li><a href=\"\/plugins\/salesforce-commerce-cloud\/sfra\/upgrade\"\n                        target=\"_self\"\n                        >\n                    Upgrade your cartridge\n                <\/a><\/li><\/ul><\/div>\n<\/code><\/pre>","url":"https:\/\/docs.adyen.com\/pt\/plugins\/salesforce-commerce-cloud\/sfra\/customization-guide","articleFields":{"description":"Learn how to customize your checkout.","feedback_component":true,"filters_component":false,"last_edit_on":"19-06-2025 15:36","page_id":"9f8d037a-dcf7-4844-a5e6-c9cc6199545c","decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/plugins\/salesforce-commerce-cloud\/sfra\/customization-guide","title":"Customization guide","content":"\nRead moreRead more about customizing SFRA cartridges in Salesforce documentation.\n\nYou 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.\nWhen 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.\nTherefore, 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\nThere are two types of customizations you can apply:\n\nAdding your custom code in a separate cartridge to customize checkout flows.\nCustomizing payment methods by adding custom configuration.\nImplement your own pre-authorization checks\n\nAdd custom code in a separate cartridge\nYou can customize your integration by adding a separate cartridge before the Adyen cartridge to override default configurations.\nThis 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.\nTo add custom code in a separate cartridge:\n\nCreate a new cartridge in your \/src\/cartridges directory and name it, for example: int_custom_cartridge.\nAdd your custom code to the new cartridge and update metadata if needed\nUpdate the name property in the package.json file to the name you chose, for example int_custom_cartridge.\nRun the following command to make sure all unit tests are passing:\nnpm install\nRun the following command:\nnpm run build\nAdd the new cartridge to your cartridge path:\n\nGo to\u00a0Administration\u00a0&gt;\u00a0Sites\u00a0&gt;\u00a0Manage Sites &gt; [yourSite] &gt; Settings.\nIn the Cartridges box, add the new cartridge before the Adyen cartridges.\nSelect Apply.\n\nModify or add end-to-end tests as needed.\nRun the end-to-end tests to make sure your custom code works correctly.\n\nWatch how to customize your SFCC cartridge:\n\nExtract custom code from the default cartridge\nIf you have customized the source directory or the cartridges directory, you can extract your custom code in a separate cartridge later to:\n\nUpgrade your integration.\nSwitch to the recommended way to customize.\n\nTo extract your custom code:\n\nIn our GitHub releases, find the version that you currently use.\nIn your local project, locate your custom code. Your custom code may be in the \/src, \/cartridges or both directories.\nSeparate your custom code from the default cartridge code:\n\nClone the public release with your current cartridge version into your local project:\ngit checkout tag\/YOUR_CURRENT_CARTRIDGE_VERSION\nMake sure that your main project has two nested folders for the cloned default Adyen cartridge and for your customized integration.\nRun the following command in your terminal to compare the Adyen default cartridge code and your integration code to locate all the file changes:\ndiff -r FOLDER_1_NAME FOLDER_2_NAME\nIf you are using Windows, use the following command instead:\ncomp \/r FOLDER_1_NAME FOLDER_2_NAME\nAlternatively, to view the file changes in human readable format instead of machine readable format, you can use diff tools that are available on GitHub. \nExtract the custom code that you located.\n\nAdd the custom code in a separate cartridge.\n\nCustomize payment methods\nThe 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).\nEach 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:\n\nAmazon Pay\nApple Pay\nBancontact (BCMC)\nBoleto\nCard (credit\/debit)\n\nStored Cards\nClick to Pay\n\nCash App\nGift Cards\nGoogle Pay\nKlarna\nPayPal\nUPI (India)\n\nFeatured configuration options\nEach payment method can be customized with the following featured configuration parameters.\n\n\n\nParameter\nDescription\n\n\n\n\nshowPayButton\nSet to false to hide the payment button in the checkout form.\n\n\nenvironment\nThe front-end environment. Possible values: - test - live\n\n\nonSubmit\nCalled when the shopper selects the pay button to submit their payment information.\n\n\nonError\nCalled when an error occurs during the payment.\n\n\nonAuthorised\nCalled when the payment is successfully authorized.\n\n\n\nFor 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.\nYou can use these configuration options to optimize usability and compliance based on region, shopper preferences, or business rules.\nHow to customize\nTo customize the configuration for a payment method:\n\nIn the cartridge, go to: \/src\/cartridges\/app_adyen_SFRA\/cartridge\/client\/default\/js\/adyen\/checkout\/paymentMethodsConfiguration.\nOpen the corresponding file for the payment method. For example: card.js for card, paypal.js for PayPal, or klarna.js for Klarna.\nEdit the configuration.\n\nIf applicable:\n\nRebuild your code.\nDeploy the changes to your Salesforce Commerce Cloud environment.\n\nThe following example shows configuration for the card payment method.\n\n    \n\nImplement pre-authorization checks\nOn 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.\nTo add your own pre-authorization logic:\n\nIn the cartridge, go to \/src\/cartridges\/int_adyen_SFRA\/cartridge\/adyen\/scripts\/hooks\/payment\/preAuthorizationHandling.js.\nUsing the app.payment.pre.auth pre-authorization hook, add your custom logic.\nTo let the cartridge proceed or stop with payment authorization after your checks:\n\nReturn error: true to prevent the cartridge from making the payment request if your pre-authorization checks fail.\nReturn error: false to proceed with the payment request if your pre-authorization checks succeed.\n\n\nTroubleshoot common issues\n\nPayment method display issues:\n\nMake sure that you set showPayButton: true.\nMake sure that the payment method is enabled in live Customer Area.\n\nAPI errors: make sure that your Adyen API credentials are configured correctly in your SFCC Business Manager.\nCustomization issues: make sure that configuration files have been modified and deployed correctly.\n\nSee also\n\n\n                     Troubleshooting your integration \n                \n                    Upgrade your cartridge\n                \n","type":"page","locale":"pt","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Plugins","lvl2":"Salesforce Commerce Cloud - B2C Commerce","lvl3":"Storefront Reference Architecture (SFRA)","lvl4":"Customization guide"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/plugins","lvl2":"https:\/\/docs.adyen.com\/pt\/plugins\/salesforce-commerce-cloud","lvl3":"https:\/\/docs.adyen.com\/pt\/plugins\/salesforce-commerce-cloud\/sfra","lvl4":"\/pt\/plugins\/salesforce-commerce-cloud\/sfra\/customization-guide"},"levels":5,"category":"Plugins","category_color":"green","tags":["Customization","guide"]}}