Install and set up the 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:
   • Adyen Apex API Library package
   • B2B LWR package
2. When prompted for an installation key, enter Payment@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 Adyen in Builder mode, add the URL for the Experience Builder of your Salesforce store.
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.

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

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:
   • Name: ApiKey
   • Value: Your API key

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 Type.
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.
   • Client Key: your client key.
   • HMAC Key: your HMAC key.
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. 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 right, 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.

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:

• Check the status of a test payment under Transactions > Payments.
• Test your webhook server.
• Complete an end-to-end webhook test for the test payment.

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