To take advantage of increased success rates and reduced needs for interacting with your platform, we recommend that you migrate to Adyen Integration v2.0 if you are still using the legacy Adyen gateway integration.
Zuora partners with Adyen and provides a new Adyen gateway integration called Adyen Integration v2.0. This integration supports the Adyen's Checkout API v49 and Payment API v40, and the fields for Visa mandate and stored credentials.
Supported Payment Methods and Payment Operations
The Adyen Integration v2.0 payment gateway integration supports the following payment methods and payment operations:
|Supported Payment Method||Payment Method Types||Payment Operations|
|Credit Card Reference Transaction||
Stored Credential Transactions
Adyen Integration v2.0 includes support for the Visa Stored Credential Transaction framework.
Before configuring an Adyen Integration v2.0 instance, ensure that you have met the following requirements:
- 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.
- 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.
Configure the Adyen Integration v2.0 Instance
Take the following steps to configure Adyen Integration v2.0:
- Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway.
- Select Adyen Integration v2.0 from the Gateway Type drop-down list.
- Click create gateway.
- Complete the information for the gateway instance. See below for more information on the fields.
- Click save gateway information after entering the necessary information.
Common Configuration Fields
There are some common fields you must complete for every gateway configuration. Zuora recommends reviewing Zuora recommends reviewing Setting Up Payment Gateways for information on these fields:
- 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. The Gateway Reconciliation job for Adyen is scheduled to start at 11:00 pm (PST) every day. See Adyen Gateway Reconciliation for tips to consider when using gateway reconciliation. For more information about this option, see Gateway Reconciliation.
- 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.
- Enable Idempotency: This setting is used to enable idempotent processing. If this checkbox is selected, the
Idempotency-Keyis 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
shopperStatementfield, 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.
gwOptions_shopperInteractionfield via API. See shopperInteraction for more information.
- Recurring Processing Model: Defines a recurring payment type. Allowed values include:
- 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.
Level 2 and Level 3 Card Data Fields
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.
Credit Card Reference Transactions (Tokenization)
Zuora supports Adyen tokens. Tokens are used for credit card reference transactions in Zuora. A reference transaction is simply a representation of a credit card payment method without having sensitive payment method information like the credit card number stored in Zuora. The token cannot be used with another gateway, which is why Zuora recommends storing credit card information in Zuora whenever possible. You can enter credit card information and Zuora will create tokens for you.
Apart from credit card tokens, you can also add an existing Adyen token in Zuora. To use an existing token, enter the shopperReference token in the Token Id field, and the recurringDetailReference information you want to use in the Second Token ID field when creating or updating a tokenized payment method. After recurringDetailReference is entered, it will be saved by Zuora and used for all payments made with this payment method.
Since each merchant can have multiple recurringDetailReferences per shopperReference in Adyen, the best practice is to always specify recurringDetailReference for tokenized payment methods. If you have existing tokenized payment methods without the recurringDetailsReference information, we recommend that you update all these payment methods to include recurringDetailReference in the Second Token ID field. For example, you can use Zuora's Developer Tools app to mass update all payment methods stored in Zuora.
Adyen recommends that you either use existing Adyen tokens or create tokens from Zuora by entering the credit card information for all credit card reference transactions in a consistent manner. Do not use both ways to create tokenized payment methods.
For tokenized payment methods, you must validate them in Zuora so that payments made with these payment methods are successful. To validate tokenized payment methods, enable the following settings in the Adyen Integration v2.0 gateway configuration page:
- Verify new payment method
- Verify updated payment method
Supported Gateway Option Fields
You can submit additional information to the Adyen gateway using gateway options. The following table describes the gateway option fields supported by Adyen Integration v2.0 and the corresponding description:
|Supported gateway option field||Zuora API field||Corresponding Adyen field||Description|
The shopper's IP address.
Zuora will first check the
For more information about this field, see shopperIP.
Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer. Possible values include:
You can also specify this value from the Zuora UI. See the Specific Configuration Fields section above.
For more information about this field, see shopperInteraction.
A string containing the shopper's device fingerprint.
For more information about this field, see deviceFingerprint.
- Because payments are created with 0 capture delay, all payment transactions will be in the SentForSettle status. However, Adyen can only cancel the payments in the Authorised status that is prior to the SentForSettle status. Therefore, Zuora does not support the Cancel operation for all payment method types.
- Validating the Bank Transfer and ACH payment methods is currently not supported by Adyen.
- Validating an existing mandate Id or using a mandate Id for payments are not supported by Adyen in the current version of the checkout API (version 41).