Install and set up the Salesforce OMS package

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

With our Salesforce OMS package, you handle captures and refunds for the payments of your Salesforce Commerce Cloud storefront. The package keeps the Adyen and Salesforce systems in sync, so that you can seamlessly manage your order and payment flows.

To set up the package:

1. Install the package.
2. Configure package components in your OMS Org.
3. Set up the payment gateway in your OMS Org.
4. Set up webhooks in your OMS Org and the Adyen Customer Area.
5. Set up alternative payment methods in your OMS Org.
6. Configure capture settings in your SFCC Business Manager.

Install the app

1. In your Salesforce OMS Org, enable multiple currencies.
2. Install the Adyen Payments for Salesforce Order Management (SOM) app with the installation key Payments@Adyen.
3. Follow the instructions on the Salesforce Application Installation Guide.

Configure package components

In your Salesforce OMS Org, configure package components:

1. Add new Adyen fields to the layout.
2. Configure Named Credentials.
3. Configure Adyen custom metadata type.
4. Configure sales channels.

Add new Adyen fields to the layout

1. From Setup, go to Object Manager.
2. Search for and click on the Sales Channel object.
3. Click on Page Layouts and select the page layout that you want the new Adyen Merchant Account field to appear in.
4. Drag and drop the field to your selected layout.
5. Click Save.

Repeat these steps for the Payment and Payment Authorization objects by adding the Adyen Override Merchant Config, Adyen Payment Method, Adyen Payment Method Variant fields.

Configure Named Credentials

The Named Credentials have the authentication details used between the Salesforce OMS and Adyen.

1. From Setup, enter Named Credentials in the search field.
2. Select Adyen Legacy Named Credential and click Edit.
3. Fill these properties:

4. Click Save.

Configure Adyen custom metadata type

1. From Setup, search for Custom Metadata Type.
2. Select Manage Records of Adyen Adapter metadata.
3. Select Edit for the Adyen Default metadata record.
4. Set the Merchant Account to the name of your Adyen merchant account. This field is case-sensitive.
5. Click Save.

Configure sales channels

1. From the App Launcher, search for Sales Channels.
2. Select the Sales Channel that you want to use.
3. Set the Adyen Merchant Account field to AdyenDefault.

   This must match the custom metadata record name from the previous step.

Set up the Payment Gateway

1. Create a Payment Gateway record.
2. Create a Payment Gateway Provider record.
3. Create a Payment Gateway record.
4. Only if you process in-person payments with endless aisle, create a payment gateway record for in-person payments.

Create the Payment Gateway Provider record

Get the Apex Adapter ID:

1. In your Salesforce OMS Org, go to Setup > Custom Code > Apex Classes
2. Choose AdyenAsyncAdapter class.
3. Get the Apex Adapter ID from the last 15 digits of the URL in your browser's address bar, for example 01pB0000004IvhM.

Add the Payment Gateway Provider record:

1. In Workbench, choose the latest API version available.

2. Select Utilities > REST Explorer.

3. Make a POST /services/data/v58.0/tooling/sobjects/PaymentGatewayProvider request with the following body:

   Copy code
   {
   "ApexAdapterId": "YOUR_APEX_ADAPTER_ID",
   "DeveloperName": "Adyen",
   "MasterLabel": "SalesforceOrderManagement-Adyen",
   "IdempotencySupported": "Yes"
   }

4. You get a confirmation in the API response if the Payment Gateway Provider record was created successfully.

Create a Payment Gateway record

1. In the App Launcher, search for Payment Gateways and select it.

2. Select New and enter the following values into the corresponding fields:

   Field	Value
   Payment Gateway Name	Adyen
   Payment Gateway Provider	Choose the Payment Gateway Provider you created.
   Merchant Credential	The Named Credential you created.
   Status	Active
   External Reference	Adyen_Component. This value must match your SFCC B2C Payment Processor ID.

3. Select Save.

Create a Payment Gateway record for in-person payments

Create a Payment Gateway record in Salesforce:

1. In the App Launcher, search for Payment Gateways and select it.

2. Select New and enter the following values into the corresponding fields:

   Field	Value
   Payment Gateway Name	AdyenPos
   Payment Gateway Provider	Select Adyen OMS Provider.
   Merchant Credential	Select AdyenCheckout.
   Status	Active
   External Reference	Adyen_POS. This value must match your SFCC B2C Payment Processor ID.

3. Select Save.

Set up webhooks

Adyen sends webhooks that contain JSON objects to your Salesforce payment gateway adapter. To receive these webhooks:

1. Expose a Salesforce site endpoint.
2. Configure webhooks in the Customer Area.
3. Test your webhook configuration.

Expose a Salesforce site endpoint

1. In your Salesforce OMS Org, go to Setup > User Interface > Sites and Domains - Sites, and then select Site.
2. Select New.
3. Enter a label, for example Adyen.
4. Enter a unique value for the default web address, for example http://dev-myorganization--sandbox.cs17.force.com/adyen.
5. Select Active.
6. Select an Active Site Home Page, for example, UnderConstruction.
7. Select Guest Access to the Payments API.
8. Select Save to save your changes and make sure the site is active.
9. Go to Public Access Settings > Custom Metadata Type Access.
10. Select Edit and enable the Adyen Adapter metadata type by moving it to the Enabled column.
11. Select Save.

12. Construct the webhook endpoint URL. For this you need:

    • The URL of your Salesforce site.
    • The Payment Gateway Provider ID you got when creating the Payment Gateway Provider record.
    Webhook endpoint URL format

    Expand view

    Copy link to code block

    Copy code

    Copy code

    SALESFORCE_SITE_URL/services/data/v58.0/commerce/payments/notify?provider=YOUR_PAYMENT_GATEWAY_PROVIDER_ID

    For example:

    Example Webhook endpoint URL

    Expand view

    Copy link to code block

    Copy code

    Copy code

    http:// dev-clientname.cs17.force.com/adyen/services/data/v49.0/commerce/payments/notify?provider=0cJ4W000000XWnuUAG

Configure webhooks in the Customer Area

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

2. Select Webhook.

3. From the list of webhooks, next to Standard webhook, select Add.

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

5. Under Server configuration, configure the following:

   Setting	Description
   URL	The webhook endpoint URL you constructed.
   Method	JSON
   Encryption protocol	The latest TLS version in the list.

6. Under Security, configure the following:

   Setting	Description
   HMAC Key	Generate the HMAC Key, copy it, and store it securely in your system. You will need your HMAC key when configuring package components.

7. Under Events, in addition to the default events that are selected, select CAPTURE, and REFUND.

8. Select Save configuration.

Test your webhook configuration

1. In your Customer Area, go to Developers > Webhooks.
2. Next to Standard webhook, select the edit webhook icon .
3. Select Test Configuration.
4. If you are on a company account, select a Merchant account from the dropdown list.
5. In the Event dropdown list, select the event code.

If your webhook configuration is correct, it shows a successful HTTP response status code, for example ResponseCode: 200.

Set up alternative payment methods

To set up alternative payment methods:

1. Add a new gateway provider payment method type.
2. Add permissions.

Add a new gateway provider payment method type

1. In your Salesforce OMS Org, go to Setup > Object Manager > Alternative Payment Method > Record Type.
2. Verify that you have a record type named Alternative Payment Method.
3. Go to Setup > Developer Console.
4. Select the Query Editor tab.

5. Run the following query:

   Copy code
   SELECT Id from RecordType where Name = 'Alternative Payment Method' Limit 1

6. From the response to the query, store the Id of the record type. If you get a parsing error, you need to remove and insert the single quotes (‘) back in the query.
7. Go to Workbench.
8. Choose the latest API version available.
9. Select Login with Salesforce and log in with your OMS sandbox credentials.
10. Select Utilities > REST Explorer.

11. Make a POST /services/data/v58.0/sobjects/GtwyProvPaymentMethodType request with the following body:

    Copy code
    {
    "DeveloperName": "AlternativePaymentMethod",
    "MasterLabel": "Alternative Payment Method",
    "GtwyProviderPaymentMethodType" : "AdyenComponent",
    "PaymentGatewayProviderId" : "YOUR_APEX_ADAPTER_ID", //Id of the Payment Gateway Provider record from step 3
    "PaymentMethodType" : "AlternativePaymentMethod",
    "RecordTypeId": "YOUR_RECORD_TYPE_ID"  //Id of your Alternative Payment Method record type
    }

    You receive the following response:

    Copy code
    {
      "id" : "1gpxxxxxxxxxxxxxxx",
      "success" : true,
      "errors" : [ ]
    }

Add permissions

1. In your Salesforce OMS Org, go to Setup > Permission Sets > Order Management B2C service > Object Settings > Alternative Payment Methods > Edit.
2. Under Record Type Assignments > Alternative Payment Method record type, select the Assigned Record Types checkbox.
3. Click Save.
4. Go back to Object Settings and go to Payment Authorizations > Edit.
5. Under Field Permissions, add Edit access for the Adyen Payment Method and Adyen Payment Method Variant fields.
6. Click Save.
7. Go back to Object Settings and go to Payments > Edit.
8. Under Field Permissions, add Edit access for the Adyen Payment Method and Adyen Payment Method Variant fields.
9. Click Save.

Configure capture settings in SFCC

With our OMS package, you can capture payments at any step in your order fulfillment flow. In Adyen, some payment methods are captured immediately after authorization. You need to specify these payment methods that you enabled in your Customer Area in your SFCC Business Manager to prevent OMS from initiating duplicate capture requests.

1. In your Salesforce Business Manager, go to Merchant Tools > Site Preferences > Adyen settings > Local payment method settings.

2. In the Payment methods without separate capture field, specify the payment methods that you added in your Customer Area, using the paymentMethodVariant for each payment method. Separate each variant with a comma, for example:

   Copy code
   ideal, paypal, applepay, visa_applepay, mc_applepay, amex_applepay, klarna_paynow, twint, sepadirectdebit, bcmc, wechatpay, multibanco, blik, mbway, pix, onlineBanking_PL

3. Select Save Changes.

Go live

When you are ready to go live, follow our SFCC go-live checklist. You do not need to follow the steps to configure the SFCC Business Manager in the checklist. Instead, you need to:

1. Configure a new Named Credential with the username and password for your live Adyen credential.
2. For the new Named Credential you created, add the live URL using your live URL prefix, for example:
   https://[YOUR_LIVE_PREFIX]-checkout-live.adyenpayments.com
   • Replace [YOUR_LIVE_PREFIX] with the live prefix in your live Customer Area under Developers > API URLs > Prefix.
3. In the Adyen Payment Gateway record you created, change the Merchant Credential value to the new Named Credential.
4. Only if you are using a different merchant account in live, change the Merchant Account for the Adyen custom metadata record to the name of your live account.

Next steps