Legacy Adyen gateway integration (previous version of the integration service)
This article is for the previous version of Adyen gateway integration. Adyen Integration v2.0 the the latest version. 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.
The Adyen payments platform provides businesses with a single solution accepting payments anywhere in the world. Built-in house, Adyen is an end-to-end infrastructure connecting you directly to Visa, MasterCard and 250 other payment methods delivering frictionless payments across online, mobile and in-store.
With Adyen you replace multiple suppliers for the gateway, risk and acquiring, with one single solution, enabling you to streamline your operations and reduce costs.
Zuora’s integration to Adyen gives you the power to manage subscription payments and increase authorization rates for both credit cards and local payment methods like SEPA direct debit.
To set up the Adyen Payment Method Updater service in Zuora, see Configure Adyen Payment Method Updater for more information.
For any subscription-based questions, contact your Zuora account representative. For transaction and settlement questions, log into your Adyen back-office, email email@example.com, or contact your account manager.
Supported Payment Methods
Zuora's Adyen gateway integration supports the following payment methods:
- Credit Card/Gift Card/Prepaid Card (Visa, MasterCard, Discover, American Express, JCB, Diners Club, and China Union Pay)
- Bank Transfer (SEPA)
- Credit Card Reference Transaction
For more information about setting up payment methods in Zuora, see Define and set up payment methods.
Configure the Adyen Gateway
- Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway.
- Select Adyen from the Gateway Type drop-down list.
- Click create gateway.
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:
- Use Gateway Test Environment
- Merchant Account, Username, and Password
For the Adyen gateway, these fields are API authentication credentials. For information on how to get these credentials, see Get Adyen Credentials for API Authentication in the following section.
- Cards Accepted
- Default Authorization Amount
Currently, the Adyen Gateway does not support customizing this field. The default value is 1.
- Verify new payment method (required)
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 Payouts
The Payout feature is integrated with Zuora through the non-referenced refund operation using the BankTransfer and the CreditCardReference payment methods. Contact Adyen support to enable the Payout feature for your merchant account. See Payouts for more information.
- Enable gateway reconciliation
The Gateway Reconciliation job for Adyen is scheduled to start at 11:00 pm (PST) every day.
See below for tips to consider when using gateway reconciliation.
For more information about this option, see Gateway Reconciliation.
Click save gateway information after entering the necessary information.
Get Adyen Credentials for API Authentication
The Adyen credentials (Merchant Account, Username, and Password) are set up in the Adyen Customer Area (CA).
Carefully note the credentials you use to create the Adyen gateway in Zuora. First, the credentials entered in Zuora are not the same as those used to access the Zuora. First, the credentials entered in Zuora are not the same as those used to access the Adyen Customer Area, please see below on how to create the required Adyen user. Second, when entered, the credentials are not validated by Zuora when the Zuora when the Adyen gateway is set up. After setup is complete, we recommend creating or updating a new payment method to make sure the configuration is correct.
Create an Adyen Username and Password
- Log in to the Adyen Customer Area.
- Click Accounts in the left pane, and then click your merchant account in the list.
- Click Settings > Users > Add New User.
- In User Account Details, click Webservice.
A user name and password is automatically generated for you. As a precaution, record the user name and password so that you can enter them correctly in the gateway setup. The password is not visible again unless you take the action of changing it.
Do not complete the Client Certificate and Client Encryption Key fields.
- In Roles and Associated Accounts, use the Roles and Accounts buttons to select the roles for the user and to associate the roles with your merchant account.
- Click Save.
The ability to process API payments is not enabled in Adyen by default. Contact the Adyen Support Team (firstname.lastname@example.org) to have the following roles enabled: API PCI Payments role, API tokenise payment details, General API Payments role, Merchant PAL Webservice role, and Merchant Recurring role. If you select the Enable Payouts check box, you also need to contact the Adyen Support Team (email@example.com) to have the Store payout detail role enabled in addition to the preceding roles.
Testing Your 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 Test card numbers and testing scenarios in Adyen Development Resources for details.
Additional Gateway Information
When enabled, this setting enables the ability to create Payment Methods which supports Adyen's Payouts using Zuora's Non-Referenced Refunds. The Payout functionality is set up as a 2-step process, with the first user initiating the action, and the second user confirming it. This means that after a payout is initiated it must be confirmed before it is executed. If a payout is not confirmed or fails, Adyen automatically reverses the request after 7 days.
Payout Merchant Requirements
To use the Payout feature, the merchant will need to contact Adyen support to provision three new users; one system user to execute the payout (submit), a second user to review the payout request (review) and an optional CA user to view and modify payouts through the Adyen Customer Area (CA).
If you already have a CA user, you can ask Adyen support to add the Payout view and modify the role for the designated CA user account.
When using the Zuora Credit Card and Bank Transfer payment methods, the user account specified in the Username field in the Credentials panel must be added with the Store payout detail role. You can contact the Adyen Support Team (firstname.lastname@example.org) to configure the settings.
The Payout API feature is not enabled by default, please contact Adyen Support to enable this feature. You will also need to configure Regular Submit workflow for your account.
Submit Payout Username and Password
The Adyen System User used to Store the Payout details and Submit a Payout request. This information is used as part of the Non-Referenced Refund transactions in Zuora.
Review Payout Username and Password
The Adyen System User used to Review and Confirm a Payout request. This information is used as part of the Non-Referenced Refund transactions in Zuora.
Supported Payment Methods for Non-Referenced Refunds
The following payment methods support non-referenced refunds:
- Credit Cards
- Credit Card Reference Transaction
- Bank Transfer
Credit Card Reference Transactions
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. Please note that the token cannot be used with another gateway, which is why we recommend storing credit card information in Zuora whenever possible.
The Token ID and Second Token ID fields are required for credit card reference transactions. Specify the following values for these fields when creating the payment method:
- Token ID: The value of the
shopperReferencefeld in Adyen
- Second Token ID: The value of the
recurringDetailReferencefield in Adyen
Adyen Gateway Reconciliation
When Enable gateway reconciliation is selected, Zuora will retrieve settlement information from Adyen on a daily basis. Before enabling gateway reconciliation in your Adyen gateway instance, you must perform the following tasks in your Adyen merchant account:
- Create report user credentials in the Adyen gateway to receive the settlement reports. The report user credentials will be entered in the Reconciliation Username and Reconciliation Password fields in the configuration page of the Adyen gateway instance. Report user credentials usually have the prefix report_ and are different from the credentials used for web service transactions. Contact support@Adyen.com if you need help creating report users and validating the credentials.
- Change your time zone setting in your Adyen merchant account:
- Change the time zone to Pacific Standard Time (including daylight savings time) if your Zuora tenant is hosted in the US Data Center.
- Change the time zone to Coordinated Universal Time (UTC) if your Zuora tenant is hosted in the EU Data Center.
- Change the time zone to Coordinated Universal Time (UTC) if your Zuora tenant is hosted in the US Cloud Data Center.
The following are tips to consider when configuring your Adyen Gateway with gateway reconciliation enabled:
- For Zuora to perform gateway reconciliation with multiple merchant accounts, each merchant accounts must be subscribed to the report 'Payment Accounting Report' in Adyen's backoffice.
- If there are two instances of the same report with the same name, Zuora gateway reconciliation job may fail. Contact support@Adyen.com to remove the duplicate report.
Adyen supports the following Gateway Reconciliation event types:
The following table describes how different transaction status is mapped to the corresponding gateway reconciliation event type:
|Status in Adyen records||Gateway reconciliation event type|
|Others||Zuora will save the event type as "unknown" and take no further reconciliation action.|
Best Practice for using Adyen Gateway Reconciliation
- For chargeback events, Zuora only supports processing the events with the same payment and settlement currency. If you use only one settlement currency for one Adyen merchant account and need to have chargeback events processed in Adyen Gateway Reconciliation, the best practice is:
- Create multiple Adyen merchant accounts with different currencies specified.
- Configure multiple payment gateway instances with different Adyen account specified.
- Assign payment gateway instances to customer accounts in different currencies.
- Configure payment gateway instances in Zuora in correspondence with different Adyen accounts.
Supported Gateway Option Fields
You can submit additional information to the Adyen gateway using gateway options. Currently, the Adyen gateway integration only supports the
shopperIP field. This field can be used in Payment Pages 2.0 or the following REST API: