Set up the cartridge

Before you begin

Before you begin, make sure that you have performed the following steps:

1. 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.
2. Finish the metadata import.

3. 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.
   

    

Step 1: Set up the cartridge path

To set up the cartridge path in the Business Manager: 

1. Go to Administration > Sites > Manage Sites > [yourSite] > Settings. 

2. In the Cartridges box: 

   • If you are using SFRA, enter:
     int_adyen_SFRA:int_adyen_overlay:app_storefront_base
   • If you are using a controller-based SiteGenesis, enter:
     int_adyen_controllers:int_adyen_overlay:app_storefront_controllers:app_storefront_core
   • If you are using any form of customizations, make sure to follow our customization guide on best practices around customizations.

3. Select Apply.

Step 2: Set up the Business Manager

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.

   Account structure
   
   With Adyen, you have a single company account, together with one or more merchant accounts.
   However, you can only have one merchant account for each storefront.

2. In the merchantCode box, enter the name of your Adyen merchant account for which the payments will be processed. You can find this in the upper-left corner of your Customer Area.

3. Set Test/Production mode to (TEST).

4. Select Save in the upper-right corner of the screen.

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 the Adyen Customer Area. To authenticate requests from your payment environment, the cartridge also needs a client key.

You need to generate the keys in the Adyen Customer Area and add them to the Business Manager.

Generate an API key in the Adyen Customer Area

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
3. Under Server settings > Authentication select the API key tab.
4. Select Generate API key.
5. Select the copy icon and store your API key securely in your system.
6. Select Save changes.

Generate a client key in the Adyen Customer Area

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the credential username for your integration, for example ws@Company.[YourCompanyAccount].
3. Under Client settings > Authentication select the Client key tab.
4. Select Generate client key.
5. Select the copy icon and store your client key securely in your system.
6. Under Add allowed origins, enter your domains and select Add.
7. Select Save changes.

Step 4: Add the keys to the Business Manager

To add the keys that you generated in the Adyen Customer Area in the Business Manager:

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. In the X-API-KEY of Web service box, enter the API key from your Adyen Customer Area.
3. In the ClientKey box, enter the client key from your Adyen Customer Area.
4. Select Save in the upper-right corner of the screen.

Step 5: Receive payment status updates

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 Adyen Customer Area, and add the webhooks credentials to the Business Manager.

Set up webhooks in the Adyen Customer Area

1. Log in to your Customer Area. Switch to your merchant account.
2. Select Developers > Webhooks.
3. Select + Webhook.
4. Under Recommended webhooks > Standard webhook select Add.
5. Select the toggle to make the standard webhook Enabled.
6. Select the edit icon for Server configuration.
7. Enter:
   • 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: Select HTTP POST.
   • Encryption Protocol: Select TLSv1.3.
8. Select Apply.
9. Under Security > Basic authentication, select the edit icon . Enter your server's username and password. Select Apply.
10. Select Save changes.

Add webhook credentials to the Business Manager

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. In the Adyen Notifications User and Adyen Notifications Password box, enter the username and password for notifications from your Adyen Customer Area.
3. Select Save in the upper-right corner of the screen.

Test webhooks

Test whether webhooks have been configured correctly:

Your server must acknowledge webhooks with a response message.

1. Log in to your Customer Area.
2. Select Developers > Webhooks.
3. Select the edit icon for the webhook to test. You can test only the event codes you configured for this webhook.
4. Select Test configuration.
5. If you're on a company account, select a Merchant account from the dropdown list.
6. 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.

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 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.

We recommend that you set the frequency of this scheduled job to 1 minute: 

1. Go to the Schedule and History tab for the Process scheduled job.
2. Set Trigger to Recurring Interval.
3. In the Run Time pane, set Amount to 1, and Interval to Minutes. 

Step 6 (optional): Store shopper details

With Adyen's tokenization, you can securely store payment details of your shoppers. This allows you to offer subscription payments, automatic top-ups to shopper accounts, and give your shoppers a faster checkout experience by using their stored card.

To set this up:

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. Store shopper details: recurring. Select Yes to enable stored payment methods for recurring transactions, where you can complete the payment without the shopper being present.
3. Store shopper details: one-click. Select Yes to enable stored payment methods for one-click transactions, where the shopper needs to enter their CVC/CVV to complete the payment.
4. Enable the Guest user shopper reference, when storing shopper details of guest users. Go to Site Preferences > Order > Generate Customer No. for Guest Orders > Yes.

Step 7 (optional): Enable 3D Secure 2

The cartridge supports native 3D Secure 2 authentication by default. To configure this:

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. Set 3DS2 Enabled to Yes.
3. Select Save in the upper-right corner.

Step 8 (optional): Accept donations

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:

1. Onboard with Adyen Giving.
2. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen and set the following configurations:

Field	Description
Enable Adyen Giving	Set to True to enable Adyen Giving.
Charity name	Name of the charity displayed on the Adyen Giving component.
Charity merchant account	Merchant account name for charity.
Amounts for donation	Suggested amounts that the shopper can choose to donate, in whole numbers.
Description of charity	Description of the charity.
Website from charity	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.

3. In the Adyen Customer Area, go to Developers > Additional data.
4. In the Card section, select the Variant checkbox.

Step 9 (optional): Basket fields

You can use Basket fields for custom risk rules. To include the Basket fields in your payment request:

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. Set Basket fields to true.

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.

To send Level 2/3 data:

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. Set Level 2/3 Data Authorisation Enabled to true.
3. In the Commodity code box, enter the UNSPSC commodity code for your products or services.

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.

1. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences > Adyen.
2. In the System integrator box, enter the name of your system integrator.

Step 12 (optional): Set up point of sale (POS)

Adyen's Terminal API allows your Salesforce Commerce Cloud stores to process payments via point-of-sale (POS) devices.

Before you begin to set up POS, make sure that you have imported the metadata, and set up the cartridge.

Step 1: Enable POS payments

1. In the Business Manager, go to Merchant Tools > Ordering > Payment methods.
2. Select AdyenPOS.
3. Select Yes in the Enabled column.
4. From the Payment Processor drop-down in the AdyenPOS Details section, select Adyen_POS.

Step 2: Configure services

1. In the Business Manager, go to Administration > Operations > Services.
2. In the Profile column next to AdyenPosPayment, select Adyen.  
3. In the Name box, enter Adyen.
4. In the Connection Timeout (ms) box, enter 100.000.
5. Ensure that the Enable Circuit Breaker checkbox is not selected.

Step 3 (optional): Create Store ID

1. Create a Store ID.
2. In the Business Manager, go to Merchant tools > Site Preferences > Custom Preferences and set the StoreId value.

See also