Plugins-2 icon

Install and set up the Salesforce OMS package

Learn how to install and set up your Adyen Salesforce OMS package.

Start integrating with Salesforce OMS package

Choose your version
3.1.0

Requirements

Before you install the Adyen Salesforce Order Management (OMS) package, make sure that you:

  1. Have created a Salesforce OMS Org.
  2. Install the base dependent API Library Apex Adyen package with the installation key Payments@Adyen..

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

Step 2: Set up the Payment Gateway

To set up the Payment Gateway:

  1. Create a Payment Gateway record.
  2. 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.

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.

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

    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.

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 need to enter the HMAC key when you configure package components.
  7. Under Events, in addition to the default events that are selected, select CAPTURE, CAPTURE_FAILED, REFUND, and REFUND_FAILED.

  8. Select Save configuration.

Although rare, a refund or capture can fail after you have received a REFUND or CAPTURE webhook with success: true. After a payment is processed in Salesforce, the status cannot be changed. Therefore, we recommend to monitor these cases in the GatewayResultCode field of the PaymentGatewayLog object in Salesforce. When a refund or capture fails, the GatewayResultCode is marked with CAPTURE_FAILED, or REFUND_FAILED. Learn more in our Capture and Refund documentation.

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.

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

Legacy Named Credentials are deprecated by Salesforce and are not used in our package from this version onwards.

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:

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

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.

Step 5: 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.

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.