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.

Set up the Payment Gateway

To set up the Payment Gateway:

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

Create a Payment Gateway record

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	Adyen
   Payment Gateway Provider	Select Adyen OMS Provider.
   Merchant Credential	Select AdyenCheckout. Due to a known Salesforce issue, you may not be able to select AdyenCheckout. If you experience this, go to Setup > Named Credentials, and select Adyen Checkout. Then, go back to the Adyen Payment Gateway record, select Refresh, and try again.
   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.

Get the Payment Gateway Provider ID

Get the Payment Gateway Provider ID for the record you created. You will need this ID when you set up webhooks.

1. In the Payment Gateway record you created, select the Adyen OMS Provider hyperlink.
   This opens the Payment Gateway Provider page.
2. In the Site URL, find the ID, starting with 0cJ.
3. Save this ID for later use.

Set up webhooks

Adyen uses webhooks to send you updates on payment statuses. To enable receiving these webhooks:

1. Expose a Salesforce site endpoint. You need to expose different Salesforce site endpoints to receive default payment status updates, and updates related to payment modifications initiated from the Adyen Customer Area.
2. Configure webhooks in the Customer Area, for each of your Salesforce site endpoints.
3. Test your webhook configuration.

Expose Salesforce site endpoints

Default webhooks

1. In your Salesforce OMS Org, go to Setup > User Interface > Sites and Domains - Sites, and then select Sites.

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 your webhook endpoint URL with:

    • The URL of your Salesforce site.
    • The Payment Gateway Provider ID.
    Webhook endpoint URL format

    Expand view

    Copy link to code block

    Copy code

    Copy code

    YOUR_SALESFORCE_SITE_URL/services/data/v60.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

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

13. Save the endpoint URL in your system, you will need it when you configure webhooks in the Customer Area.

Webhooks for modifications initiated from the Customer Area

Expose an additional Salesforce site endpoint to receive webhooks related to captures or refunds initiated from the Adyen Customer Area. Our OMS package creates a payment gateway log under the Salesforce Order Payment Summary. This lets you track the status of payments that are modified through the Customer Area.

1. In your Salesforce OMS Org, go to Setup > User Interface > Sites and Domains - Sites, and then select Sites.
2. From the site list, select Adyen.
3. Select Public Access Settings.
4. Under Apps, select Apex Class Access.
5. Select Edit, and from the Available Apex Classes list, select adyen_payment.NonPaymentWebhookHandler.
6. Select Add to move it to the Enabled Apex Classes list.

This exposes an additional site endpoint to receive webhooks:

YOUR_SALESFORCE_SITE_URL/adyen/services/apexrest/adyen_payment/nonPaymentWebhook/v1

Configure webhooks in the Customer Area

Configure webhooks for each of the Salesforce site endpoint URLs you exposed.

To configure a webhook:

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 under a company account, or only to specific merchant accounts.

5. Under Server configuration, configure the following:

   Setting	Description
   URL	The webhook endpoint URL for either: - Default webhooks - Webhooks for modifications initiated from the Customer Area.
   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 need to enter the HMAC key when you configure package components. You only have to generate the HMAC key once, if you are setting up the second webhook, use the HMAC key that you already generated.

7. Under Events, in addition to the default events that are selected, select the following events:

   • For default webhooks, select CAPTURE, CAPTURE_FAILED, REFUND, and REFUND_FAILED.
   • For webhooks for modifications initiated from the Customer Area, select AUTHORISATION, CAPTURE, and REFUND.

8. Select Save configuration.

Test your webhook configuration

Before you can test your webhook configuration, you have to add your HMAC key in your Salesforce custom metadata 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.

Configure package components

In your Salesforce OMS Org, configure package components:

1. Add new Adyen fields to the layout.
2. Set up the Principal Credential.
3. Configure Adyen custom metadata type.
4. Optionally, configure a merchant account for a sales channel.

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 Payment Method and Adyen Payment Method Variant fields.

Set up the Principal Credential

The package uses Named Credentials to perform authentication between the Salesforce OMS and Adyen. When you install the app, the Named Credential is set up automatically.

You must also set up a Principal Credential.

These steps below are based on the Salesforce Enhanced Profile User Interface. If you use the old view, the steps you have to take may differ.

In addition to the Named Credential, you need to set up a Principal Credential. To do this, in your OMS Org:

1. Go to Setup > Security > Named Credentials.
2. Under External Credential, select Adyen API.
3. Under Principals, next to the AdyenParameterKey, select the Actions button, and then select Edit.
   This opens a modal window.
4. Select Add, and add an authentication parameter with the following properties:
   • Name: ApiKey
   • Value: Your API key

After setting up the Principal, give access to this Principal with a permission set:

1. Go to Setup > Users > Permission Sets.
2. Select New.
3. In the Label field, enter a name, and select Save.
4. Select External Credential Principal Access.
5. Select Edit and enable the Principal you have set up by moving it from the Available to the Enabled column.
6. Go back to the permission set, and select Object Settings.
7. Select User External Credentials, and select Edit.
8. Next to Read, select the checkbox to give read access.

9. Assign the permission set you have created to the Automated Process user. This user is a hidden Salesforce user that runs scheduled flows and other automated processes, including the payment flows. If you have modified your process automation settings , this user may differ.

   1. Select Manage Assignments, and then select Add Assignment.
   2. In the user list, select the Automated Process user, and select Next.
      If the user is not visible in the list, switch to the All Users list view and search for auto,
   3. Select Assign.

   Alternatively, you can assign also assign the permission set to the Automated Process user by:

   1. In your Developer Console, query the Profile Id for this user with the following:

      Expand view

      Copy link to code block

      Copy code

      Copy code

      SELECT ProfileId FROM User WHERE Alias = 'autoproc'

   2. Construct a URL to access the page where you can edit permissions.

      Expand view

      Copy link to code block

      Copy code

      Copy code

      YOUR_SF_ORG_URL/_ui/system/user/ProfileExternalCredentialPrincipalPermissionEdit/e?profile_id=PROFILE_ID

      • YOUR_SF_ORG_URL: Your Salesforce Org Url.
      • PROFILE_ID: The profile Id you received as a result to the query.

   3. Navigate to the URL that you constructed.

   4. Select Edit and enable the Principal you have set up by moving it from the Available to the Enabled column.

   5. Select Save.

Configure Adyen custom metadata type

1. In your OMS Org, go to Setup > Custom Code > Custom Metadata Types.
2. Next to Adyen Adapter, select Manage Records.
3. Next to Adyen Default, select Edit.
4. Fill the following fields:
   • Merchant Account: your Adyen merchant account name. This field is case-sensitive.
   • HMAC Key: your HMAC key.
5. Select Save.

After you have added your HMAC key in Salesforce, test your webhook configuration.

(Optional) Configure sales channels

Optionally, you can link your sales channels to use specific Adyen merchant accounts. Sales channels that are not linked to a specific merchant account use the merchant account you configured in the Adyen Default custom metadata record.

Before you can link an Adyen merchant account to a sales channel, make sure that:

• The merchant account has API permissions.
• There is a custom metadata record with the merchant account name in the Adyen Adapter custom metadata object.

To link an Adyen merchant account to a sales channel:

1. In your OMS Org, go to the App Launcher, , search for Sales Channels.
2. Select the Sales Channel that you want to configure a merchant account for.
3. Set the Adyen Merchant Account field to the name of the merchant account that you want to link to this sales channel.

Set up alternative payment methods

To set up alternative payment methods, add permissions in Salesforce:

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

With our OMS package, you can capture payments at any step in your order fulfillment flow. The steps you need to follow to configure captures in SFCC depends on your capture setting in the Adyen Customer Area:

• Manual capture : you can capture payments from the OMS after they have been authorized.
• Automatic capture : payments are captured automatically after authorization. You do not have to manually capture payments from the OMS. Our OMS package handles the automatic captures without disrupting the payment flow. If you have set up automatic capture in your Customer Area, follow the steps to enable automatic captures with OMS.

Regardless of your setting, payments for some payment methods are captured immediately after authorization. You must specify these payment methods in your Salesforce Business Manager to prevent duplicate capture requests.

Enable automatic captures

To prevent OMS from making duplicate capture requests to Adyen when you have set up automatic captures in your Adyen Customer Area, follow the steps below.

1. In your Salesforce OMS Org, go to Setup > Custom Code > Custom Metadata Types.

2. Select Adyen Adapter.

3. Scroll down to Adyen Adapter Layout, and select Edit.

4. Drag and drop the Auto Capture Enabled and Manual Capture Payment Methods fields to the Adyen Adapter Layout.

5. Select Save.

6. Select Manage Adyen Adapters.

7. Next to Adyen Default, select Edit.

8. Select the checkbox next to Auto Capture Enabled.
   When you have set this up, OMS will process the payment record without an additional capture request, and the following payment gateway log will be created:

   Copy code
   [capture-complete] Auto Capture enabled

9. For some payment methods, manual captures are required even when you have set up automatic captures in your Adyen Customer Area. In the Manual Capture Payment Methods field, specify the payment methods that require manual capture, using the paymentMethodVariant for each payment method. Separate each variant with a comma, for example:

   Copy code
   klarna, klarna_account

10. Select Save.

Specify payments without separate captures in SFCC

Payments for some payment methods are captured immediately after authorization regardless of your capture settings. You need to specify these payment methods that you enabled in the Adyen Customer Area in your Salesforce Business Manager. This prevents 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. 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, apply for a live account. Review the process to start accepting payments on Get started with Adyen.

When you get your live account:

1. Follow our SFCC go-live checklist. You do not need to follow the steps to configure the SFCC Business Manager in the checklist.
2. Update the Adyen credentials you used to set up your Salesforce OMS Org:
   • In the custom metadata record:
     1. Update your HMAC key.
     2. If you are using a different merchant account in the live environment, update the merchant account name.
3. Switch the URL for the Adyen Checkout named credential to your live URL:
   1. In your OMS Org, go to Setup > Security > Named Credentials.
   2. Select the Adyen Checkout named credential.
   3. Replace the test URL with https://[YOUR_LIVE_PREFIX]-checkout-live.adyenpayments.com/checkout. Get your live prefix from the live Customer Area.
4. Switch your test API key to your live API Key:
   1. Select the External Credential linked to your Adyen Checkout named credential.
   2. Under Principals, update your API key authentication parameter to your live API key.

Next steps