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.

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

• 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: In Zuora, you can set the Shopper Interaction field through either of the following ways:

  • 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 automatically captures the shopper's IP address from Payment Pages for Adyen Integration v2.0 and sends it to the gateway if the IP address has not been passed through existing fields. For 3DS2 transactions, IP address information is always sent to the gateway, regardless of whether this setting is selected.

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

  • For Payment , enable Recurring details .

  • For Acquirer , enable Network transaction reference .

• Tokenize payment method : With this setting enabled, tokens are generated for the ACH and SEPA payment methods when they are used to process payments through UI, API, or Payment Pages 2.0. For more information about tokenizing ACH and SEPA payment methods, see Tokenize 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: