Plugin icon

Install and set up the package

Install and set up the Adyen Salesforce B2B Commerce Lightning package.

Before you begin

Before you begin setting up the Adyen B2B LWR Commerce package, make sure that you:

  • Set up your Salesforce B2B LWR Store.
  • Activate multiple currencies for your Salesforce B2B store:
    1. In your Salesforce B2B Org, go to Setup > Company Settings > Company Information.
    2. Select Activate Multiple Currencies.

Step 1: Install the packages

  1. Install the following Adyen packages from the Salesforce App Exchange:
  2. When prompted for an installation key, enter Payments@Adyen.

Step 2: Generate an API key and client key

To connect your Salesforce store to the Adyen API, you need to generate an API key in your Customer Area.

To authenticate requests from your payment environment, the package also needs a client key. You need to generate a client key in your Customer Area.

Generate an API key in your 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 your 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. You will need your client key when configuring package components.
  6. Under Add allowed origins, enter the URL of your Salesforce store, and select Add.
  7. To render the Adyen checkout component in Builder mode, add the builder URLs. For example:
    • https://YOUR-ORG.develop.live-preview.salesforce-experience.com
    • https://YOUR-ORG.develop.builder.salesforce-experience.com
  8. Select Save changes.

Step 3: Set up webhooks

Adyen uses webhooks to inform your Salesforce B2B store of payment status changes. To receive these webhooks:

  1. Expose a Salesforce site endpoint.
  2. Set up webhooks in the Customer Area.
  3. Configure a webhook job.

After you have set up webhooks, Salesforce creates a Gateway Log each time your Salesforce B2B Org receives a webhook from Adyen.

Expose a Salesforce site endpoint

  1. In your Salesforce B2B Org, go to Setup > User Interface > Sites and Domains - Sites.
  2. Select your store site.
  3. Select Public Access Settings, and then select Apex Class Access.
  4. Select Edit and enable the adyen_payment.AdyenAuthWebhookHandler class by moving it from the Available column to the Enabled column.
  5. Select Save.

Set up webhooks in the Customer Area

  1. In your Customer Area, go to Developers >  Webhooks. If you want to configure webhooks for a merchant account, switch to that merchant account.

  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.
  5. Under Server configuration, configure the following:

    Setting Description
    URL Construct your webhook endpoint URL by adding /services/apexrest/adyen_payment/authWebhook/v1 to the end of the site endpoint you exposed, for example: http://dev-myorganization--sandbox.cs17.force.com/adyen/services/apexrest/adyen_payment/authWebhook/v1.
    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. Select Save configuration.

Configure a webhook job

To process the webhooks you receive from Adyen, schedule a job in your B2B Org. The way to configure the job depends on how frequently you want the job to run:

  • For a job that runs multiple times a day, you must configure the job using the Developer Console.
  • For a job that runs once a day or less frequently, you can configure the job using the UI.
  1. In your B2B Org, go to the Developer Console.

  2. Select Debug and Open Execute Anonymous Window.

  3. Construct a for loop to run the AdyenSchedulableWebhookJob as frequently as you want. For example, to run the job every five minutes, your code should look like this:

  4. Select Execute.

To view the jobs that you have created, go to Setup > Environments > Jobs > Scheduled Jobs.

Gateway Logs

When your Salesforce B2B Org receives an Adyen webhook, a Gateway Log is created to record the event. To view the logs for a payment:

  1. In the Commerce app, go to App Launcher.
  2. Search for and select Order Payment Summaries.
  3. In the list view, select the order payment method for the order you want to view the logs for.
  4. Under Related, check the Gateways Logs list.

The handling of these logs depends on when Salesforce creates the payment authorization. If Salesforce creates a payment authorization before the Adyen webhook reaches your store, Salesforce processes the webhook synchronously. If Salesforce hasn't yet created the payment authorization, Salesforce processes the webhook asynchronously when the webhook job you configured runs.

After a webhook is processed, the payment authorization status is updated to Processed, or Failed.

Step 4: Configure package components

In your Salesforce B2B Org, configure package components:

  1. Set up the Principal Credential.
  2. Create a payment gateway.
  3. Configure custom metadata .

Set up the Principal Credential

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

When you install the packages, the Named Credential is set up automatically.

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

  1. Go to Setup > Security > Named Credentials.
  2. Under External Credential, select Adyen Auth.
  3. Under Principals, next to the AdyenApiKey, 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:

  1. Go to Setup > Users > Permission Sets.
  2. Next to Adyen Checkout Access, select Clone.
  3. In the Label field, enter a name, and select Save.
  4. Select the permission set you have cloned.
  5. Select External Credential Principal Access.
  6. Select Edit and enable the Principal you have set up by moving it from the Available to the Enabled column.
  7. Go back to the permission set, and select Object Settings.
  8. Select User External Credentials, and select Edit>
  9. Next to Read, select the checkbox to give read access.
  10. Assign the permission set you have created to the users of your Salesforce B2B Store:
    1. Select Manage Assignments, and then select Add Assignment.
    2. In the user list, select the users that you want to assign, and select Next.
    3. Select Assign.

Create a Payment Gateway

  1. In the Commerce app, select App Launcher and type Payment Gateways.
  2. Select New, and enter the following values:

    Field Value
    Payment Gateway Name Adyen
    Payment Gateway Provider CommercePaymentsAdyenAsyncAdapter
    Merchant Credential AdyenCheckout
    Status Active
    External Reference Leave blank.
  3. Select Save.
  4. In your store administration section, select Payments.
  5. Select Select Provider, and choose the gateway you have created to link it to your store.

Configure custom metadata

  1. In your B2B 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.

Step 5: Set up the Adyen Lightning Web Component

To process payments with Adyen in your Salesforce B2B store:

  1. Add the Adyen Lightning Web Component to your store.
  2. Enable tokenization (optional).
  3. Add Adyen to your trusted URL list.

Add the Adyen Lightning Web Component to your store

  1. In your B2B Org, go to Setup > Feature Settings > Digital Experiences > All Sites.
  2. Next to your site, select Builder.
  3. On the top left, in the Pages menu, select Checkout.
  4. Scroll to the Payment section.
  5. Delete the standard Salesforce payment component.
  6. Select the Components icon, and search for Adyen Checkout.
  7. Drag the Adyen Checkout component to the place you deleted the Salesforce payment component from.
  8. Verify that the billing address component is present on the page and in the same checkout section as the Adyen Checkout.
  9. In the Pages menu, select Payment Processing.
  10. Add the Adyen Checkout component to the Payment Processing page.
  11. Select Publish.

Enable tokenization

To allow shoppers to store their payment details and use them later, enable tokenization.

  1. In your B2B Org, go to Setup > Feature Settings > Digital Experiences > All Sites.
  2. Select the Enable Save Payment Methods checkbox.
  3. Next to your site, select Builder.
  4. On the top left, in the Pages menu, select Checkout.
  5. Under Payment, select the Adyen Checkout component.
    This opens the Adyen Checkout modal window.
  6. Under Settings, select Enable Save Payment Methods.
  7. Select Publish.

Add Adyen to your trusted URL list

  1. In your B2B Org, go to Setup > Security > Trusted URLs.
  2. To add a new trusted URL, select New trusted URL.
  3. Add the Adyen URL, specifying the following fields:
    • API Name: select a descriptive name, for example, Adyen.
    • URL: https://*.adyen.com
      Make sure that the Active checkbox is selected.
  4. Under CSP Directives, select all checkboxes.
  5. Select Save.
  6. To render the Adyen 3D Secure component in the Live environment, add new trusted URLs for all card schemes that you want to offer in your checkout. Follow the steps above for each card scheme, and use the scheme URL for the URL field, for example:

    Scheme URL
    Mastercard https://*.mastercard.com
    Visa https://*.checkout.visa.com
    American Express https://*.americanexpress.com

Error handling

Redirect errors

The package uses Native 3D Secure in most cases. For some payment methods, the redirect flow may be triggered. We recommend setting up an error page for cases where an error occurs during the redirect flow to offer a better shopping experience.

The package redirects shoppers to the standard error page with the URL parameter paymentError, and value not_authorized, for example: https://your.site.com/mystore/error?paymentError=not_authorized. You can customize the page and the error message displayed to your shoppers.

Override error message labels contents

If you want to override or translate error message labels, follow the steps in the Salesforce documentation.

Troubleshooting errors

When an error occurs during checkout or while processing webhooks, a Log Entry object is created with the Exception record type. Monitor these records to take action in case of errors.

When a payment attempt fails, a Log Entry object is created with the Information record type.

To view Log Entries:

  1. In your Commerce App, go to App Launcher.
  2. Search for and select Log Entries.

Test your integration

Before you go live with your integration, we recommend to test your integration to verify everything works correctly.

Test the following scenario:

  • Log in to your store as a shopper, and pay for an order using one of Adyen's test cards.

In your Salesforce B2B Org:

  • Verify that the order has the correct billing address.
  • Verify that the log entries are free of errors.
  • Verify that the webhook job you scheduled was executed after the payment, and the payment authorization status moved from Pending to Processed.

In your Adyen Customer Area:

Go live

  1. Apply for a live account. Review the process to start accepting payments on Get started with Adyen.
  2. Configure your live account:
    1. Set up your live account.
    2. Set up finances.
    3. Generate an API key and a Client key in your live Customer Area.
    4. Add allowed origins to your live API credential.
    5. Set up webhooks in the live Customer Area in your live account.
  3. Submit a request to add payment methods in your live Customer Area .
  4. Update the Adyen credentials you used to set up your Salesforce B2B Org:
    • In the custom metadata record:
      1. Update your HMAC key and Client key.
      2. If you are using a different merchant account in the live environment, update the merchant account name.
  5. Switch the URL for the Adyen Checkout named credential to your live URL:
    1. In your B2B 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.
  6. 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.
  7. Change the Adyen Environment value of the Adyen Lightning Web Component you added to your Checkout and Payment Processing pages to match your live endpoint region:

    Endpoint region Web
    EU live
    APSE live-apse
    AU live-au
    US live-us
    IN live-in