Start integrating with Salesforce SFRA cartridge
Choose your versionAdyen Salesforce on GitHub
View the latest version of the cartridge in the Adyen Salesforce Commerce Cloud repository.
Requirements
Before you begin, make sure that you have performed the following steps:
- Create a test account with Adyen. With this, you will be able to access the test Customer Area, and apply for a live account. While you wait for your live account credentials, you can start integrating by using your test account.
- Finish the metadata import.
-
In Salesforce Commerce Cloud, enforce HTTPS.
To be compatible with the Chrome v80 Cookie policy, you need to enforce the use of HTTPS for all sites.
Account structure
With Adyen, you have a single company account, and one or more sub-accounts called merchant accounts. However, in Salesforce, you can only have one merchant account for each storefront.
Step 1: Set up the cartridge path
To set up the cartridge path in the Business Manager:
-
Go to Administration > Sites > Manage Sites > [yourSite] > Settings.
-
In the Cartridges box, enter:
app_adyen_SFRA:int_adyen_SFRA:app_storefront_base- If you are using any form of customizations, make sure to follow our customization guide on best practices around customizations.
-
Select Apply.
Step 2: Enable the Salesforce Business Manager configuration page
To show the Adyen Settings menu item in your Salesforce Business Manager:
- Go to Administration > Sites > Manage Sites > Business Manager - Settings.
- In the Cartridges box, enter bm_adyen:int_adyen_SFRA:app_storefront_base. Select Apply.
- Go to Administration > Organization > Roles & Permissions > Administrator - Business Manager Modules.
- In the dialogue box, select the site you want to enable Adyen for or select the Sites box to select all. Select Apply.
- Under Site Preferences, find Adyen Settings in the list and select the checkbox in the right column. At the bottom of the page, select Update.
Step 3: Generate an API key and client key
To connect your Commerce Cloud store to the Adyen API, you need to generate an API key in your Customer Area and add it to your Salesforce Business Manager.
To authenticate requests from your payment environment, the cartridge also needs a client key. You need to generate a client key in your Customer Area and add it your Salesforce Business Manager.
Generate an API key in your Customer Area
- Log in to your Customer Area.
- Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
- Under Server settings > Authentication select the API key tab.
- Select Generate API key.
- Select the copy icon and store your API key securely in your system.
- Select Save changes.
Generate a client key in your Customer Area
- Log in to your Customer Area.
- Go to Developers > API credentials, and select the credential username for your integration, for example ws@Company.[YourCompanyAccount].
- Under Client settings > Authentication select the Client key tab.
- Select Generate client key.
- Select the copy icon and store your client key securely in your system.
- Under Add allowed origins, enter your domains and select Add.
- Select Save changes.
After generating both keys, add them to your Salesforce Business Manager:
- In your Salesforce Business Manager, go to Merchant Tools > Site Preferences > Adyen settings > Account settings.
- Under Adyen Client Key, enter the client key that you generated.
- Under API key of webservice, enter the API key that you generated.
- Select Save Changes.
Step 4: Set up account settings
-
In your Salesforce Business Manager, go to Merchant Tools > Site Preferences > Adyen settings > Account settings, and fill the following fields:
Field Description Environment Select Test for setting up and testing your integration. When going live, you need to change this setting to Live. Adyen Client Key The client key that you generated. Storefront Reference Architecture
(SFRA) - version 6 or 7Only if you are using SFRA version 6 or 7, select Enable. Merchant Account The name of your Adyen merchant account. API key of webservice The API key that you generated. The Adyen Live Prefix and Front-end resources region fields are only relevant after you have set up and tested your integration, and are ready to go live. Find the information for these fields in our go-live checklist.
-
Select Save Changes.
Step 5: Set up webhooks
To inform your Commerce Cloud store of payment status changes, Adyen uses webhooks, sent as HTTP callbacks to endpoints on your server. To receive webhooks, you need to enter your server's details in the Customer Area, and add the webhooks credentials to the Salesforce Business Manager.
1. Set up webhooks in the Customer Area
-
In your Customer Area, go to Developers > Webhooks.
We recommend to configure webhooks for your company account. This ensures that you do not have duplicate webhook configurations, and improves performance.
-
Select Webhook.
-
From the list of webhooks, next to Standard webhook, select Add.
-
Under General, configure the following:
Setting Description Enabled Select the toggle to enable or disable the webhook. Version The webhook version. Description Your description of the webhook. Merchant accounts You can apply the webhook to all merchant accounts for a company account, include only specific merchant accounts, or exclude specific merchant accounts for your company account. -
Under Server configuration, configure the following:
Setting Description URL - URL: Your webhook server's URL, adding /Adyen-Notify at the end, for example: https://zzft-xx.sandbox.XXXX.dx.commercecloud.salesforce.com/on/demandware.store/Sites-RefArch-Site/default/Adyen-Notify
.Method HTTP POST Encryption protocol TLSv.1.3 Under Security, configure the following:
Setting Description Basic authentication Enter your server's username and password. You need to enter these credentials in the Salesforce Business Manager later. HMAC Key Generate the HMAC Key, copy it, and store it securely in your system. You need to enter the HMAC key in the Salesforce Business Manager later. We strongly recommend that you use HMAC signatures to protect your server from unauthorised webhook events. -
Under Events settings, select the event codes for this webhook. Some webhook types do not support more than one event code, so this setting does not appear.
-
If the Additional settings section is available, optionally select the additional information you want to receive in this webhook. Some webhook types do not support more than one event code, so this section does not appear.
-
Select Save configuration.
2. Add webhook credentials to the Salesforce Business Manager
- In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen Settings > Webhook settings.
- Enter the Webhook username and Webhook password from your Customer Area.
- Optionally, enter your HMAC Key.
- Select Save changes.
3. Test webhooks
To test your webhooks:
Your server must acknowledge webhooks with a successful HTTP response status code (like 202).
- Log in to your Customer Area.
- Select Developers > Webhooks.
- Select the webhook to test.
The Webhook details panel includes information about the configuration. Under Events, you can find the configured event codes that you can test for this webhook. - Select the edit icon
- Select Test configuration.
- If you are on a company account, select a Merchant account from the dropdown list.
- In the Event dropdown list, select the event code to test webhooks for.
If the test webhook failed, you get an error message with the reason. Troubleshoot the problem.
4. Configure scheduled jobs
Webhooks are stored in Commerce Cloud as custom object instances to be processed by scheduled jobs.
After the metadata import, a scheduled job with ID Process is added to the Salesforce Business Manager: Administration > Operations > Jobs. This scheduled job has two steps (you can check this in the Job Steps tab):
- Process – Processes the webhook and updates the payment status of the order.
- Clean – Deletes the custom object instance, once it has been processed.
To optimize the processing of your instances, we recommend that you set the frequency of this scheduled job to 1 minute:
- Go to the Schedule and History tab for the Process scheduled job.
- Set Trigger to Recurring Interval.
- In the Run Time pane, set Amount to 1, and Interval to Minutes.
Step 6 (optional): Store shopper details
With Adyen tokenization, you can securely store payment details of your shoppers. This allows you to offer a faster checkout experience by using their stored card.
To set this up:
- In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen Settings.
- In the Additional settings section, under Tokenisation, select Enable.
- In the Local payment method settings section, under Store shopper details: one-click, select Enabled to securely store the payment details of your shoppers for later payments, where the shopper needs to enter their CVC/CVV to complete the payment.
- Select Save Changes.
- To store payment details of guest users, go to Site Preferences > Order > Generate Customer No. for Guest Orders, and select Yes.
- Select Apply.
Payment details are stored in shopper accounts in the Salesforce platform. To be able to delete saved payment details from a shopper's account, you have to configure an additional setting. To set this up, contact our Support Team.
Step 7 (optional): Set up in-person payments
To process payments in your Commerce Cloud stores using payment terminals:
1: Enable in-person payments
- In the Salesforce Business Manager, go to Merchant Tools > Ordering > Payment methods.
- Select AdyenPOS.
- Select Yes in the Enabled column.
- From the Payment Processor drop-down in the AdyenPOS Details section, select Adyen_POS.
2: Configure services
- In the Salesforce Business Manager, go to Administration > Operations > Services.
- Under Services, select AdyenPosPayment.
- In the Name box, enter AdyenPosPayment.
- In the Profile dropdown, select AdyenPOS.
- Under Profiles, select AdyenPOS.
- In the Connection Timeout (ms) box, enter 100.000.
- Make sure that the Enable Circuit Breaker checkbox is not selected.
3: Create Store ID
- Create a Store ID.
- In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen Settings > In-person payments settings.
- Set the StoreID for Terminal API to your store ID.
Step 8 (optional): Set up donations with Adyen Giving
If you enable Adyen Giving in your Salesforce Business Manager settings, you also need to configure it in your Customer Area:
With Adyen Giving, your shoppers can seamlessly donate to charities of your choice at the checkout page of your website. To learn more about Adyen Giving, see Donations.
To use Adyen Giving with your Salesforce Commerce Cloud cartridge:
-
In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen settings > Adyen Giving and set the following fields:
Field Description Adyen Giving Enable the toggle to offer your shoppers the option to donate. Charity name Name of the charity displayed on the Adyen Giving component. Charity's merchant account Merchant account name for charity. Amounts for donation Suggested amounts that the shopper can choose to donate, in whole numbers. Charity's description Description of the charity. Charity website Link to the charity website. Background image for Adyen Giving component Background image of the Adyen Giving component. Logo in Adyen Giving component Logo displayed on the Adyen Giving component. -
Select Save Changes.
Test and go live with Giving
Test
You must have the Merchant admin user role.
- In your test Customer Area, go to Settings > Account Settings.
- Under Giving, select the Online donations toggle to enable it.
- In your Salesforce Business Manager, use the test account MyCharity_Giving_TEST for Charity merchant account.
- Make test donations using our test cards.
When testing Visa payments, use the test card which has the security code as optional.
- Verify the outcome of your test donations in a Giving report or dashboard:
In your Customer Area, go to Reports > Giving Overview, which shows the successful donations the next day.
If an issue occurs with your test donation requests, you can find more details in the API logs.
Go live
- Contact your Adyen Account Manager or our Support Team and ask them to set up your live account for Giving, connecting it to the right nonprofit account.
- In your live Customer Area, enable the Adyen Giving merchant webhook.
- In your Salesforce Business Manager, use the account name that we give you after choosing your nonprofit for Charity merchant account.
- Verify the outcome of live donations by either:
- Finding the donation in a Giving report or dashboard.
- Getting the DONATION webhook for the donation.
Step 9 (optional): Basket fields
You can use Basket fields for custom risk rules. To include the Basket fields in your payment request:
- In the Business Manager, go to Merchant tools > Site Preferences > Adyen Settings > Additional Settings.
- Under Basket fields, select Enable.
- Select Save Changes.
Step 10 (optional): Send Level 2/3 data for cards
Sending Level 2 or Level 3 Enhanced Scheme Data allows you to cut your interchange rates on US domestic transactions by up to 90 basis points. At the same time, your shoppers will see additional information about their purchase on their credit card statement.
Not all businesses can submit Level 2/3 data. Refer to What is Enhanced Scheme Data? for more information.
Sending Level 2/3 data is supported from v20.1.3 of the cartridge.
To send Level 2/3 data:
- In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen Settings > Additional settings.
- Under Level 2/3 Data, select Enabled.
- Under Commodity code, enter the UNSPSC commodity code for your products or services.
- Select Save Changes.
Step 11 (optional): Add system integrator info
If your integration with Adyen is built by a system integrator let us know their name, so that we can offer you better support.
Adding system integrator info is supported from v20.1.3 of the cartridge.
- In the Salesforce Business Manager, go to Merchant tools > Site Preferences > Adyen Settings > Additional Settings.
- Under System integrator, enter the name of your system integrator.