Skip to main content

Legacy Adyen gateway integration (previous version of the integration service)

Zuora

Legacy Adyen gateway integration (previous version of the integration service)

  1. Last updated
  2. Save as PDF

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 support@adyen.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

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway. 
  2. Select Adyen from the Gateway Type drop-down list.
  3. 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: 

  • Type
  • Name
  • 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

  1. Log in to the Adyen Customer Area.
  2. Click Accounts in the left pane, and then click your merchant account in the list.
  3. Click Settings > Users > Add New User.
  4. 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.
  5. 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.
  6. Click Save.

The ability to process API payments is not enabled in Adyen by default. Contact the Adyen Support Team (support@adyen.com) 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 (support@adyen.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

Payouts

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 (support@adyen.com) 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 shopperReference feld in Adyen
  • Second Token ID: The value of the recurringDetailReference field in Adyen

Adyen Gateway Reconciliation 

See Gateway Reconciliation on Adyen.

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: