Feedback Edit

Set up Dynamics 365 Payment Connector for Adyen

  • Article
  • 20 minutes to read

This article describes how to sign up with Adyen and set up the Microsoft Dynamics 365 Payment Connector for Adyen. For an overview of the Dynamics 365 Payment Connector for Adyen, see Dynamics 365 Payment Connector for Adyen overview.

Sign up with Adyen

To use the Dynamics 365 Payment Connector for Adyen, you must have a separate agreement with Adyen. To learn more about Adyen's services, or to create a test merchant account, visit the Adyen website.

Setup and configuration

Note

These instructions assume that you've already signed up for a merchant account with Adyen, and that you have access to the Adyen merchant dashboard.

Prerequisites

The following prerequisites must be completed before payments can be configured in any channel.

Configure your Adyen account settings for Dynamics 365 Commerce

In addition to the instructions below, you must also configure your Adyen account settings for Dynamics 365 Commerce. For instructions on setting up Adyen for Dynamics 365 Commerce, see Set up the Adyen payment connector for Dynamics 365.

Set up a processor for new credit cards

To process payments across point of sale (POS) terminals, a call center, or Commerce, you must configure a new default payment processor for new credit cards. Follow these steps to configure a default payment processor.

  1. Sign in to Commerce headquarters and go to Accounts receivable > Payments setup > Payment services.

  2. On the Action Pane, select New, and then, on the Setup tab, enter the following information.

    Field Description Sample value
    Payment service Enter the name of the payment service to configure. Adyen Payment Service
    Payment connector Select the payment connector to use for new credit card payments. Dynamics 365 Payment Connector for Adyen
    Test mode For the Adyen connector, in production and test environments you should set this field to false. false
    Default processor for credit cards Specify whether this payment processor should be the default processor that's used for new credit cards. Yes
    Bypass payment processor for zero transactions Specify whether this payment processor should be skipped for transactions that have a 0 (zero) amount. Yes

  3. On the Payment service account tab, enter the following information.

    Field Description Required Automatically set Sample value
    Assembly Name Auto populated name of the assembly for the Dynamics 365 Payment Connector for Adyen. Yes Yes Binary name
    Service account ID Auto populated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes (such as invoicing) should use. Yes Yes Guid
    Version Enter the version of the Dynamics 365 Payment Connector for Adyen to use. "V002" should be used for all new implementations, as it leverages a newer Adyen API for card not present payments and is required for SCA support. Yes Yes "V001"/"V002"
    Gateway environment Enter the Adyen gateway environment to map to. The possible values are Test and Live. You should set this field to Live only for production devices and transactions. Yes Yes Live
    Optional Domain The optional domain is required for Live environments and should be obtained by contacting Adyen. This is the unique identifier for your Live environment in the form [random]-[company name]. This is present as the prefix inside the API URLs under Account > API URLs in your company's Live account on the Adyen Customer Area portal. For additional details, see Live endpoints. Live only No Contact Adyen
    Merchant account ID Enter the unique Adyen merchant identifier. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No MerchantIdentifier
    Terminal architecture This field must be set to Cloud for the Payment service account. Yes Yes Cloud
    Local Password phrase This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Key Identifier This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Key Version This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Cryptor Version Enter the Adyen cryptor version to use when you interact with the Adyen gateway. You should set this field to 1. Yes Yes 1
    Cloud API Key Enter the Adyen cloud API key. You can obtain this key by following the instructions on the How to get the API key page on the Adyen website. Yes No abcdefg
    Supported Currencies Enter the currencies that the connector should process. In card-present scenarios, Adyen can support additional currencies through Dynamic Currency Conversion after the transaction request is sent to the payment terminal. Contact Adyen support to get a list of supported currencies. Yes Yes USD;EUR
    Supported Tender Types Enter the tender types that the connector should process. Yes Yes Visa;MasterCard;Amex;Discover;Debit
    Gift card provider Enter the gift card provider that the connector should use to process gift cards. This field is case-sensitive. No No "svs" or "givex"
    Terminal gift card entry (POS only) Allows the customer to select between Manual or Swipe. Yes Yes True/False
    Allow saving payment information in e-commerce (E-commerce only) Gives signed-in users the option to save payment details for future online purchases. Yes Yes True/False
    Authorization stale period (days) (POS only) Number of days before an authorization is considered stale and should decline before going to the processor for capture. Yes Yes "7"
    Origin Key Required when "V002" is designated for the version. You can obtain this key by following the instructions on the How to get an origin key page on the Adyen website.
    EnableRequestProtection Adds retry logic to "card not present" payment calls, reducing potential for duplicate calls using a correlation ID. When "True", a correlation ID is added to provider requests to prevent duplicates. If "False", calls are sent to the provider without the correlation ID or duplicate protection logic. No No True/False
    Non-incremental capture payment methods Names of the payment method variant or card types used by Adyen to identify card types in authorization responses which do not support incremental capture. Value entered should match the payment method variant/card type string used in Adyen to reference, as noted in Adyen PaymentMethodVariant. No No "amexcommercial"

  4. On the Card verification value tab, leave Prompt for card verification value and Allow blank card verification value set to No.

POS payment terminal

Onboard and configure an Adyen payment terminal

Note

These instructions assume that you have access to an Adyen payment terminal.

Go to the Point of sale page on the Adyen website and follow the instructions to onboard your Adyen payment terminal. Skip any steps that instruct you to download Adyen-specific apps. During the onboarding process, make a note of the following information for each payment terminal. You will need this information in the Configure the payment terminal IP address and EFT POS register number section later in this article.

  • IP address of the payment terminal
  • POIID (POIID is composed of the serial number and model number of the device. It is used to uniquely identify the device.)

After the payment terminal is onboarded, sign in to the Adyen Customer Area, go to the terminal that you want to configure, and make a note of the following information for each payment terminal. You will need this information in the EFT service for local network communication section later in this article.

  • Key identifier
  • Key passphrase
  • Key version

Set up a Dynamics 365 POS hardware profile

  1. Sign in to Commerce headquarters and go to Retail and Commerce > Channel setup > POS setup > POS profiles > Hardware profiles.
  2. Select the hardware profile to add the Dynamics 365 Payment Connector for Adyen for.
  3. Follow the steps in the EFT service and PIN pad sections that follow.

EFT service

The Adyen payment connector can be configured to communicate with devices via the local network or through Adyen's cloud backend. For environments with unreliable internet service, or where offline mode is required, the Local setup should be used. For environments with strong internet connections, or if a static IP address can't be assigned to the payment terminal, the Cloud architecture may work best.

EFT service for local network communication

  1. On the EFT service FastTab, in the EFT Service field, select Payment Connector.

  2. On the Connectors tab, select New, and then, in the Connector field, select Dynamics 365 Payment Connector for Adyen. Make sure that the value in the Sequence number field is lower than the value for all other connectors.

  3. In the Connector properties section, enter the following information.

    Field Description Required Automatically set Sample value
    Assembly Name Auto populated name of the assembly for the Dynamics 365 Payment Connector for Adyen. Yes Yes Binary name
    Service account ID Auto populated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes (such as invoicing) should use. Yes Yes Guid
    Version Set to V001 for EFT settings in the hardware profile. V002 is required for call center and storefront only. Yes Yes "V001"
    Gateway environment Enter the Adyen gateway environment to map to. The possible values are Test and Live. You should set this field to Live only for production devices and transactions. Yes Yes Live
    Optional Domain The optional domain is required for Live environments and should be obtained by contacting Adyen. This is the unique identifier for your Live environment in the form [random]-[company name]. This is present as the prefix inside the API URLs under Account > API URLs in your company's Live account on the Adyen Customer Area portal. For additional details, see Live endpoints. Live only No Contact Adyen
    Merchant account ID Enter the unique Adyen merchant identifier. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No MerchantIdenfier
    Terminal architecture This must be set to Local for local communications. For more information about the different Terminal API architectures, see the Introducing the Terminal API page on the Adyen website. Yes Yes Local
    Local Password phrase Enter the Adyen key passphrase for the payment terminal. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No keypassphrase123
    Local Key Identifier Enter the Adyen key identifier for the payment terminal. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No mykey
    Local Key Version Enter the Adyen key version for the payment terminal. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No 0
    Local Cryptor Version Enter the Adyen cryptor version to use when you interact with the Adyen gateway. You should set this field to 1. Yes Yes 1
    Cloud API Key Enter the Adyen cloud API key. You can obtain this key by following the instructions on the How to get the API key page on the Adyen website. Yes No abcdefg
    Supported Currencies Enter the currencies that the connector should process. In card-present scenarios, Adyen can support additional currencies through Dynamic Currency Conversion after the transaction request is sent to the payment terminal. Contact Adyen support to get a list of supported currencies. Yes Yes USD;EUR
    Supported Tender Types Enter the tender types that the connector should process. These values are case-sensitive. Yes Yes Visa;MasterCard;Amex;Discover;Debit
    Gift card provider Enter the gift card provider that the connector should use to process gift cards. This field is case-sensitive. No No "svs" or "givex"
    Terminal gift card entry (POS only) Allows the customer to select between Manual or Swipe. Yes Yes True/False
    Allow saving payment information in e-commerce (E-commerce only) Gives signed-in users the option to save payment details for future online purchases. Yes Yes True/False
    Authorization stale period (days) (POS only) Number of days before an authorization is considered stale and should decline before going to the processor for capture. Yes Yes "7"
    Origin Key (Card not present only)
    EnableRequestProtection Adds retry logic to "card not present" payment calls, reducing potential for duplicate calls using a correlation ID. When "True", a correlation ID is added to provider requests to prevent duplicates. If "False", calls are sent to the provider without the correlation ID or duplicate protection logic. No No True/False
    Non-incremental capture payment methods Names of the payment method variant or card types used by Adyen to identify card types in authorization responses which do not support incremental capture. Value entered should match the payment method variant/card type string used in Adyen to reference, as noted in Adyen PaymentMethodVariant. No No "amexcommercial"

  4. On the Action Pane, select Save.

EFT service for cloud communication

  1. On the EFT service FastTab, in the EFT Service field, select Payment Connector.

  2. On the Connectors tab, select New, and then in the Connector field, select Dynamics 365 Payment Connector for Adyen. Make sure that the value in the Sequence number field is lower than the value for all other connectors.

  3. In the Connector properties section, enter the following information.

    Field Description Required Automatically set Sample value
    Assembly Name Autopopulated name of the assembly for the Dynamics 365 Payment Connector for Adyen. Yes Yes Binary name
    Service account ID Autopopulated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes (such as invoicing) should use. Yes Yes Guid
    Version Set to V001 for EFT settings in the hardware profile. V002 is required for call center and storefront only. Yes Yes "V001"
    Gateway environment Enter the Adyen gateway environment to map to. The possible values are Test and Live. You should set this field to Live only for production devices and transactions. Yes Yes Live
    Optional Domain The optional domain is required for live environments and should be obtained by contacting Adyen. This is the unique identifier for your live environment in the form [random]-[company name]. This is present as the prefix inside the API URLs under Account > API URLs in your company's live account on the Adyen Customer Area portal. For additional details, see Live endpoints. Live only No Contact Adyen
    Merchant account ID Enter the unique Adyen merchant identifier. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No MerchantIdenfier
    Terminal architecture This must be set to Cloud for cloud communication with the payment terminal. For more information about the different terminal API architectures, see the Introducing the Terminal API page on the Adyen website. Yes Yes Cloud
    Local Password phrase This setting is used for local payment terminal communication only. No No leave blank
    Local Key Identifier This setting is used for local payment terminal communication only. No No leave blank
    Local Key Version This setting is used for local payment terminal communication only. No No leave blank
    Local Cryptor Version This setting is used for local payment terminal communication only. You can leave the default as-is, set to 1. Yes Yes 1
    Cloud API Key Enter the Adyen cloud API key. You can obtain this key by following the instructions on the How to get the API key page on the Adyen website. Yes No abcdefg
    Supported Currencies Enter the currencies that the connector should process. In card-present scenarios, Adyen can support additional currencies through Dynamic Currency Conversion after the transaction request is sent to the payment terminal. Contact Adyen support to get a list of supported currencies. Yes Yes USD;EUR
    Supported Tender Types Enter the tender types that the connector should process. These values are case-sensitive. Yes Yes Visa;MasterCard;Amex;Discover;Debit
    Gift card provider Enter the gift card provider that the connector should use to process gift cards. This field is case-sensitive. No No "svs" or "givex"
    Terminal gift card entry (POS only) Allows the customer to select between Manual or Swipe. Yes Yes True/False
    Allow saving payment information in e-commerce (E-commerce only) Gives signed-in users the option to save payment details for future online purchases. Yes Yes True/False
    Authorization stale period (days) (POS only) Number of days before an authorization is considered stale and should decline before going to the processor for capture. Yes Yes "7"
    Origin Key (Card not present only)
    EnableRequestProtection Adds retry logic to "card not present" payment calls, reducing potential for duplicate calls using a correlation ID. When "True", a correlation ID is added to provider requests to prevent duplicates. If "False", calls are sent to the provider without the correlation ID or duplicate protection logic. No No True/False
    Non-incremental capture payment methods Names of the payment method variant or card types used by Adyen to identify card types in authorization responses which do not support incremental capture. Value entered should match the payment method variant/card type string used in Adyen to reference, as noted in Adyen PaymentMethodVariant. No No "amexcommercial"

  4. On the Action Pane, select Save.

Configure the PIN pad
  1. On the PIN pad FastTab, in the PIN pad field, select Network.
  2. In the Device name field, enter MicrosoftAdyenDeviceV001.

Set up a Dynamics 365 register

Note

These instructions assume that there is a dedicated mapping between a POS register and an Adyen payment terminal. For a hardware station that is based on Microsoft Internet Information Services (IIS), go to Retail and Commerce > Channels > Stores > All stores, and select the store that you're setting up. Then, on the page for that store, on the Hardware Stations FastTab, follow the same instructions.

Payment terminals may not be used by multiple hardware stations. If a payment terminal must be shared by multiple POS devices, an IIS hardware station must be deployed to manage communications with the payment terminal.

Configure the payment terminal IP address and EFT POS register number
  1. In Commerce headquarters, go to Retail and Commerce > Channel setup > POS setup > Registers.
  2. Select the register to link to the Adyen payment terminal.
  3. On the POS Registers page, on the General FastTab, in the EFT section, in the EFT POS register number field, enter a unique number.
  4. In the Profiles section, in the Hardware profile field, select the hardware profile that you configured earlier.
  5. Save your changes.
  6. On the Action Pane, on the Register tab, in the Hardware group, select Configure IP addresses.
    1. If using the "Local" architecture: On the IP address configuration page, on the PIN pad FastTab, in the IP address field, enter the IP address of the terminal in the following format: https://<IP address>:8443/nexo/<POIID>. Here, <IP address> and <POIID> are the values that you made a note of when you onboarded the Adyen payment terminal. Here is an example: https://192.168.1.3:8443/nexo/MX925-123456789. The values in this URL are case-sensitive.
    2. If using the "Cloud" architecture: On the IP address configuration page, on the PIN pad FastTab, in the IP address field, enter the POIID value that you made a note of when you onboarded the Adyen payment terminal. Here is an example: MX925-123456789. The values in this field are case-sensitive.
  7. If the payment terminal includes an onboard printer and you want to print receipts from the processor using that printer, enter 123 in the Port field that is separate from the IP address field in the PIN pad FastTab.

Update the Modern POS or IIS Hardware Station configuration

If you're packaging your own version of Modern POS by using the Retail SDK, you must follow these steps only one time in the SDK code before the installer is packaged. Otherwise, you must follow these steps after the standard Modern POS or IIS Hardware Station is installed.

  1. Open the dllhost.exe.config file (for Modern POS) or the web.config file (for IIS Hardware Station).

  2. Update the PreloadedComposition section as shown here, to switch from the legacy payment device adapter to the standard payment device adapter.

    <PreloadedComposition>
    <composition>
        <add source="assembly" value="Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.PaymentDeviceAdapter" />
        <!-- Switch from legacy to standard Payment Device Adapter.
        <add source="assembly" value="Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.Legacy.PaymentDeviceAdapter" />
        -->
    </composition>
</PreloadedComposition>

  3. Update the appSettings variable "PrintReceiptsOnCardDeclineOrVoid" value to True to print decline or void responses from the processor.

Configure the connector for call center payments

To configure the Dynamics 365 Payment Connector for Adyen for call center payments, follow the instructions in the Set up a processor for new credit cards section earlier in this article.

Configure additional information for the connector

To configure additional information for the connector in Commerce headquarters, follow these steps.

  1. Go to Retail and Commerce > Channels > Online stores.

  2. Select the online store to add the Dynamics 365 Payment Connector for Adyen.

  3. On the Online store page, on the Payment accounts FastTab, select Add.

  4. In the Connectors field, select Dynamics 365 Payment Connector for Adyen.

  5. Enter the following additional information.

    Field Description Required Automatically set Sample value
    Assembly Name Auto populated name of the assembly for the Dynamics 365 Payment Connector for Adyen. Yes Yes Binary name
    Service account ID Auto populated unique identifier for the setup of the merchant properties. This identifier is stamped on payment transactions and identifies the merchant properties that downstream processes (such as invoicing) should use. Yes Yes Guid
    Version Enter the version of the Dynamics 365 Payment Connector for Adyen to use. "V002" should be used for all new implementations, as it leverages a newer Adyen API for card not present payments and is required for SCA support. Yes Yes "V001"/"V002"
    Gateway environment Enter the Adyen gateway environment to map to. The possible values are Test and Live. Yes Yes Live
    Optional Domain Enter the domain to use when payment requests are made to Adyen. This is the unique identifier for your Live environment in the form [random]-[company name]. This is present as the prefix inside the API URLs under Account > API URLs in your company's Live account on the Adyen Customer Area portal. For additional details, see, Live endpoints. Live only No Contact Adyen
    Merchant account ID Enter the unique Adyen merchant identifier. This value is provided when you sign up with Adyen as described in the Sign up with Adyen section. Yes No MerchantIdenfier
    Terminal architecture This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Password phrase This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Key Identifier This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Key Version This field is used only for the POS payment terminal integration and should be left blank. No Yes Leave this field blank.
    Local Cryptor Version Enter the Adyen cryptor version to use when you interact with the Adyen gateway. You should set this field to 1. Yes No 1
    Cloud API Key Enter the Adyen cloud API key. You can obtain this key by following the instructions on the How to get the API key page on the Adyen website. Yes No The full cloud API key
    Supported Currencies Enter the currencies that the connector should process. Yes Yes USD;EUR
    Supported Tender Types Enter the tender types that the connector should process. Yes Yes Visa;MasterCard;Amex;Discover;Debit
    Gift card provider Enter the gift card provider that the connector should use to process gift cards. The possible values are SVS and GIVEX. No No SVS
    Terminal gift card entry (POS only*) Allows the customer to select between Manual or Swipe. Yes Yes True/False
    Allow saving payment information in e-commerce (E-commerce only) Gives signed-in users the option to save payment details for future online purchases. Yes Yes True/False
    Authorization stale period (days) (POS only) Number of days before an authorization is considered stale and should decline before going to the processor for capture. Yes Yes "7"
    Origin Key (E-commerce only) Only required when "V002" is designated for the version. You can obtain this key by following the instructions on the How to get an origin key page on the Adyen website.
    EnableRequestProtection Adds retry logic to "card not present" payment calls, reducing potential for duplicate calls using a correlation ID. When "True", a correlation ID is added to provider requests to prevent duplicates. If "False", calls are sent to the provider without the correlation ID or duplicate protection logic. No No True/False
    Non-incremental capture payment methods Names of the payment method variant or card types used by Adyen to identify card types in authorization responses which do not support incremental capture. Value entered should match the payment method variant/card type string used in Adyen to reference, as noted in Adyen PaymentMethodVariant. No No "amexcommercial"

  6. On the Action Pane, select Save.

Next steps

For answers to frequently asked questions regarding the Dynamics 365 Payment Connector for Adyen, see Dynamics 365 Payment Connector for Adyen FAQ.

Additional resources

Dynamics 365 Payment Connector for Adyen overview

Dynamics 365 Payment Connector for Adyen FAQ

Troubleshoot Dynamics 365 Payment Connector for Adyen

Payments FAQ

Help us understand

We want to learn more about how people use Microsoft's custom Help toolkit. Take the survey (in English) and help us understand: https://forms.office.com/r/A4cUJgjkD1.