Skip to main content

Set up and configure an Adyen Integration v2.0 gateway instance

Zuora

Set up and configure an Adyen Integration v2.0 gateway instance

Set up and configure an Adyen Integration v2.0 gateway instance by using the information in this article, including prerequisites, configuration procedure, descriptions of the configuration fields and additional metadata, and reference for testing the payment gateway.

Prerequisites

Before setting up and configuring an Adyen Integration v2.0 instance, ensure that you have met the following requirements:

  • Enable the Adyen Integration v2.0 payment gateway integration for your tenant. See Enable payment gateway integrations for your tenant for instructions.
  • Generate an Adyen API Key for your merchant account. See How to get the API key for instructions on how to obtain the API key.
  • You must obtain the live-URL prefix from your Adyen merchant account for production. This setting will be saved as a gateway setting in Zuora. Failure to specify this prefix will result in that requests cannot be processed in production.
  • The setting for recurring fields in the API response must be enabled for your Adyen merchant account to obtain the Shopper Reference token. To enable this setting in your merchant account, navigate to Settings > API URL and Response and click Recurring Details in the Payments section. The Shopper Reference token will then be included in the payment results.

  • To ensure the network transaction ID (NTI) is returned from Adyen and saved in Zuora for processing recurring payments, you must enable the Network transaction reference setting at the Adyen side.

  • For Bank Transfer transactions, you must send a request to enable “Separate Direct Debit with authorization type AUTH” for your Adyen merchant account when setting up SEPA with Adyen.
  • To enable ACH payment processing, you must enable ACH payment processing for your Adyen merchant account.  

  • For ACH credit (non-referenced refunds) processing, the storeDetailAndSubmitThirdParty and confirmThirdPartyAdyen endpoints from the Adyen Payout API v30 are used. Before ACH refunds without payment reference can be successfully made, Adyen needs to enable payouts and set up payouts to work with both endpoints on your Adyen merchant account. As required by Adyen, you must have two separate Adyen user accounts provisioned and set up: one for submitting payouts, and the other for reviewing and confirming payouts.

Procedure

Take the following steps to set up and configure an Adyen Integration v2.0 gateway instance:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway
  2. On the Configure Gateway Instance tab, select Adyen Integration v2.0 from the Gateway Type drop-down list.
  3. Click Create Gateway.
  4. Complete the information for the gateway instance. See below for more information on the fields.
  5. Click Save Gateway Information after entering the necessary information.

Configuration fields

Common configuration fields

There are some common fields you must complete for every gateway configuration. Zuora recommends reviewing Setting Up Payment Gateways for information on these fields: 

  • Type
  • Name
  • Use Gateway Test Environment
  • Merchant Account
  • Cards Accepted
  • Default Authorization Amount: Defaults to 1 in Zuora, but can be customized as needed. If you enter 0, you can verify card details without being charged.
  • Verify new payment method (required)

    Enable this setting to validate tokenized payment methods in Zuora so that the payments made with these payment methods are successful.

    The Shopper Reference token is required in the payment transactions. You must select the Verify new payment method check box in the configuration so that a Shopper Reference token is generated by Adyen during the payment method verification.
  • Verify updated payment method (optional)

    Enable this setting to validate tokenized payment methods in Zuora so that the payments made with these payment methods are successful.

  • Enable gateway reconciliation (Optional): Select to enable gateway reconciliation on this instance. For more information, see Gateway Reconciliation on Adyen.
  • Reconciliation Username (Optional): The username needed to retrieve Adyen reports to perform gateway reconciliation. This field is required if you select the Enable gateway reconciliation check box.
  • Reconciliation Password (Optional): The password needed to retrieve Adyen reports to perform gateway reconciliation. This field is required if you select the Enable gateway reconciliation check box.

Specific configuration fields

The following fields are specific to Adyen Integration v2.0:

  • API Key: The API Key generated for your merchant account in Adyen.
  • Merchant Account for Payouts User Account: This field is required for ACH credits (non-referenced refund) processing. To process ACH credits, you must enter the payouts merchant account that is set up for submitting payouts.
  • API Key for Payouts User Account: This field is required for ACH credits (non-referenced refund) processing. To process ACH credits, you must enter the payouts API Key associated with your Adyen user account that is set up for submitting payouts.
  • Merchant Account for Review & Confirm Payouts User Account: This field is required for ACH credits (non-referenced refund) processing. To process ACH credits, you must enter your merchant account that is set up to review and confirm payouts.
  • API Key for Review & Confirm Payouts User Account: This field is required for ACH credits (non-referenced refund) processing. To process ACH credits, you must enter the API Key associated with your Adyen user account that is set up to review and confirm payouts.
  • Live URL Prefix: The live-URL prefix associated with your Adyen merchant account. This prefix is required to form the production Adyen endpoint. The format for the prefix is the combination of the [random ID] and [company name] from the live endpoint. For example, abc123-Zuora.
    For test gateway instances, you can enter a dummy value for this field.
  • Enable Idempotency: This setting is used to enable idempotent processing. If this checkbox is selected, the Idempotency-Key is included in the header of all requests sent from Zuora to Adyen. See Adyen API idempotency for more information about this setting.
  • Skip Risk Rules: With this check box selected, the risk check for payment transactions is skipped. Therefore, the associated risk score for these transactions will not be generated. See Skip risk rules for more information.
  • Soft Descriptor: This field is mapped to Adyen's shopperStatement field, which is used to describe the transaction. The value for this field will appear on the cardholder's bank statement. See shopperStatement for more information.
  • Shopper Interaction: Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer. The following values are available:
    • ContAuth - Card on file and/or subscription transactions, where the cardholder is known to the merchant (returning customer).
    • Default - If this field is not set, Zuora will include the Adyen's default value (Ecommerce) in the request. 
    • Ecommerce - Online transactions where the cardholder is present (online).
    • Moto - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone.
    • POS - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal.

    In Zuora, you can set the Shopper Interaction field through either of the following ways:

    • The Shopper Interaction configuration option on the gateway settings page
    • The gwOptions_shopperInteraction field in the APIs or the client parameters of hosted payment pages

      The value set through the gwOptions_shopperInteraction field takes precedence over the value of the gateway configuration. If the gwOptions_shopperInteraction field is not set through the API or hosted payment page and the Shopper Interaction gateway configuration is set to a value other than Default, the gateway configuration value is used. If the gwOptions_shopperInteraction field is not set and the gateway configuration is set to Default, Zuora will set the appropriate value for this field based on Adyen gateway’s requirements in different business process stages. Usually Adyen requires the shopperInteraction field to be Ecommerce when creating a payment method and requires it to be ContAuth when processing a payment.

      It is recommended that you set Default to the Shopper Interaction gateway configuration. Zuora will then set and process the value in the request to the Adyen gateway correctly.

      For more information about setting this field through APIs or client parameters of hosted payment pages, see Gateway Option fields supported by Adyen Integration v2.0

  • Recurring Processing Model: Defines a recurring payment type. Allowed values include: See recurringProcessingModel for more information.
    • CardOnFile – With a card-on-file (CoF) transaction, card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction.
    • Default - If the field is not set, Zuora will include the default value in the request to Adyen. 
    • Subscription – A transaction for a fixed or variable amount, which follows a fixed schedule.
    • UnscheduledCardOnFile – An unscheduled card-on-file (UCoF) transaction is a transaction that occurs on a non-fixed schedule and/or have variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.
  • Auto-capture IP Address: With this checkbox selected, Zuora will automatically capture shoppers’ IP addresses from Payment Pages for Adyen Integration v2.0 and send them to the gateway if the IP addresses have not been passed through existing fields. 
  • Submit Card Payments with RecurringDetailReference: With this setting enabled, in Credit Card payment requests, the shopperReference and recurringDetailReference tokens retrieved from the gateway will be submitted to Adyen instead of the primary account number (PAN) if these tokens are available. If the recurringDetailReference token is not returned from the gateway, the primary account number will be used for payments. 

    Submitting the recurringDetailReference token instead of the primary account number has inherent benefits with Adyen in several use cases. Consult your Adyen account representative before enabling this setting to learn more about those benefits and see if enabling this setting fits your business needs. Before enabling the Submit Card Payments with RecurringDetailReference setting in Zuora, ensure that the following additional data settings are enabled in your Adyen's account:

    • For Payment, enable Recurring details.
    • For Acquirer, enable Network transaction reference.

    Note that if this setting is enabled, the tokens submitted cannot be custom. To pass your custom shopperReference and recurringDetailReference tokens, use Credit Card Reference Transaction payment methods other than Credit Card payment methods.

  • Tokenize payment method: With this setting enabled, tokens will be generated for the SEPA payment method when it is used to process payments through UI, API, or hosted payment page. For more information about tokenizing SEPA payment methods, see Tokenize SEPA payment methods on Adyen Integration v2.0.

Fields related to Level 2 and Level 3 card data processing

The following fields are related to Level 2 and Level 3 card data processing:

  • Enable Level 2 Processing
  • Enable Level 3 Processing
  • ShipFrom Postal Code API Name
  • ProductCode Custom Field API Name
  • CommodityCode Custom Field API Name

See Level 2 and Level 3 card data support for Adyen Integration v2.0 for details. For more information about Zuora's support for Level 3 and Level 2 data, see Level 2 and Level 3 Card Data.

Additional metadata

You can define your customized metadata in the Additional Metadata section for the following objects when you configure an Adyen v2.0 gateway instance in Zuora. Your self-defined metadata will be added to the metadata tag in the request body and passed to the gateway. If 3D Secure 2.0 is enabled for your hosted payment page, when a payment is triggered from the hosted payment page, your customized metadata for the Payment Method object will be sent to the gateway. You can use the customized metadata for further analysis, reporting, or building custom rules to enhance your fraud protection.

  • Payment object
    • Customized metadata of the following payment transaction types are supported:
      • Credit Card
      • CC Reference Transaction
      • Bank Transfer
      • ACH
      • Apple Pay
      • Google Pay
  • Payment Method object
    • Customized metadata of the following transaction types are supported for the payment method validation operation:
      • Credit Card
      • CC Reference Transaction
      • Apple Pay
      • Google Pay
    • Customized metadata of the following transaction types are supported for authorizing the availability of funds for a transaction through the Create authorization API operation:
      • Credit Card
      • Google Pay

To add a customized field, complete the following steps:

  1. When creating or configuring an Adyen v2.0 gateway instance, click Add New Metadata in the Additional Metadata section.
  2. In the Metadata Key field, enter the metadata field name by following these rules:
    • The field name must be unique. 
    • Only alphanumeric characters and underscores are allowed. 
    • A maximum of 20 metadata fields can be defined. See Adyen documentation for details about the field and character limits.
  3. Select a field from the list to indicate the metadata value.

Test the configuration  

We recommend that you test your payment gateway using both your payment gateway's test and production (live) environments. Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

You can use the test card information and testing scenarios provided by the gateway vendor to test your integration. See Adyen's Test payment methods for details.

For more information about troubleshooting payment errors in Zuora Central Sandbox, see Test payment gateways.