Skip to main content

Overview of Adyen Integration v2.0

Zuora

Overview of Adyen Integration v2.0

  1. Last updated
  2. Save as PDF

Zuora partners with Adyen and provides Adyen Integration v2.0 as the latest version of Adyen gateway integration service. If you are still using the legacy Adyen gateway integration, it is highly recommended that you migrate to Adyen Integration v2.0 to take advantage of increased success rates and reduced needs for interacting with your platform.

Supported features

The following table provides a quick reference for the supported features. For details about each feature, see the later sections in this article.

Supported payment methods
  • ACH
  • Apple Pay
  • BACS
  • Credit Card/Gift Card/Prepaid Card
  • Credit Card Reference Transaction
  • Google Pay
  • iDEAL
  • SEPA
  • Payment method types requested through the Specialized Payment Connections service:
    • UPI
    • GCash
    • KaKaoPay
    • MoMo
Supported payment operations

Validate, Payment, Payment cancel, Referenced refund, Non-referenced refund

The supported payment operations vary by payment method types. See Supported payment operations for details.
Support 3D Secure 2.0 Yes
Support Delayed Capture Yes
Support Level 2 and Level 3 card data Yes
Support stored credential transactions Yes
Support Gateway Options fields Yes
Gateway provider’s API version

Adyen Checkout API v70

Payout API v68 (for ACH non-reference refunds)
Adyen production endpoint used for Zuora gateway integration service

https://checkout-live.adyen.com/v70/payments

https://pal-live.adyen.com/pal/servlet/Payment/v68
Support Batch Gateway Reconciliation Yes
Support Real-Time Reconciliation

Yes
Adyen production endpoint used for Batch  Gateway Reconciliation service https://ca-live.adyen.com/reports/download/
Support Payment Method Updater Yes (Visa, MasterCard)
Adyen production endpoint used for PMU service sftp://sftp-live.adyen.com:5631
Support idempotency for retrying a transaction request Yes. See Electronic payment processing for details.

Supported payment methods

Adyen Integration v2.0 supports the following payment method types. For more information about setting up payment methods in Zuora, see Define and set up payment methods.

ACH

ACH payment method verification is supported through the ValidiFi account validation service. See Enable the support for ValidiFi account validation for ACH for details.

To improve payment success rates on Adyen Integration v2.0, Zuora passes the billing address information to Adyen in ACH payment transactions only if all of the following fields are specified:

  • Address1
  • AchCity
  • AchCountry
  • AchState
  • AchCode

These address fields can be specified through the Gateway Options field. See Gateway Options fields supported by Adyen Integration v2.0 for more information.

Apple Pay

You can set up Apple Pay on Adyen Integration v2.0 through the following approaches:

  • Apple Pay shown as Credit Card

    Add Apple Pay to your checkout flow and process payments by integrating with a JavaScript SDK provided by Zuora. The Apple Pay payment method created through this approach is shown as a Credit Card payment method type in Zuora. 3D Secure is supported. This is the recommended approach for setting up Apple Pay.

  • Adyen Apple Pay

    Create an Adyen Apple Pay payment method through the REST API operation. The payment method created through this approach is shown as an Adyen Apple Pay payment method type in Zuora and an Adyen token for Apple Pay is saved. You need to implement your own UI and payment processing integration.

For more information on supported payment operations, see Supported payment operations.

For more information on implementation instructions, see Set up Apple Pay.

Direct Debit UK (BACS)

The BACS payment methods created through the Zuora UI or hosted payment page are automatically tokenized. Tokens are generated and stored for the payment method. To tokenize a BACS payment method when creating it through the Create a payment method API operation, set tokenize to true. Passing in existing tokens is not supported for now.

To support processing recurring BACS payments, the following requirements must be met. The BACS payment method tokens, including shopperReference and recurringDetailReference, will be stored in Zuora and will be used to process recurring payments.

For more information about field mappings for BACS transactions, see Field mappings for BACS transactions through Adyen.

Credit Card

The following card brands are supported:

  • Visa
  • MasterCard
  • Discover
  • American Express
  • JCB
  • Diners Club
  • China Union Pay

To tokenize Credit Card payment methods,  enable Submit Card Payments with RecurringDetailReference in the configuration settings of the payment gateway instance. See Set up and configure an Adyen Integration v2.0 gateway instance for details. For now, Zuora supports Credit Card tokenization on Adyen only through this approach.

To improve payment success rates on Adyen Integration v2.0, Zuora passes the billing address information to Adyen in Credit Card payment transactions only if all of the following fields are specified.

Country of card Address Field
USA or Canada
  • CreditCardCity
  • CreditCardCountry
  • CreditCardState
  • CreditCardPostalCode
  • CreditCardAddress1
Other countries
  • CreditCardCity
  • CreditCardCountry
  • CreditCardPostalCode
  • CreditCardAddress1

These address fields can be specified through the Gateway Options field. See Gateway Options fields supported by Adyen Integration v2.0 for more information.

Credit Card Reference Transaction

See Credit Card Reference Transactions on Adyen Integration v2.0 for more information.

Google Pay

You can set up Google Pay on Adyen Integration v2.0 through the following approaches:

  • Google Pay shown as Credit Card

    Add Google Pay to your checkout flow and process payments by integrating with a JavaScript SDK provided by Zuora. The Google Pay payment method created through this approach is shown as a Credit Card payment method type in Zuora. 3D Secure is supported. This is the recommended approach for setting up Google Pay.

  • Adyen Google Pay

    Create an Adyen Google Pay payment method through the REST API operation. The payment method created through this approach is shown as an Adyen Google Pay payment method type in Zuora and an Adyen token for Google Pay is saved. You need to implement your own UI and payment processing integration.

For more information on supported payment operations, see Supported payment operations.

For more information on the implementation instructions, see Implement Google Pay.

iDEAL

iDEAL is the leading online bank transfer payment method in the Netherlands. iDEAL works with all the major Dutch banks. When customers pay with iDEAL, they are presented with a list of banks and then redirected to the selected bank's website or application, where they confirm the payment with a second factor of authentication. The payment is processed instantly and the customer is notified of the outcome. 

To enable the iDEAL payment method on your tenant, submit a request at Zuora Global Support.


iDEAL payment methods on Adyen v2.0 can be created through the one-time payment flow of Payment Pages 2.0. The created iDEAL payment methods are automatically tokenized. The creation of iDEAL payment methods through Zuora UI or API operations is not supported. 

To support processing subsequent recurring payments, the following requirements must be met. The iDEAL payment method tokens, including shopperReference and recurringDetailReference, will be stored in Zuora and will be used to process recurring payments through SEPA Direct Debit.

Delayed Capture is not supported by iDEAL payment methods on Adyen v2.0.

For more information about field mappings for iDEAL transactions, see Field mappings for iDEAL transactions through Adyen.

SEPA

You can create non-tokenized SEPA payment methods with IBAN through the UI, API operation, or hosted payment page.

To create tokenized SEPA payment methods, see Tokenize SEPA payment methods on Adyen Integration v2.0.

For payment transitions with IBAN from the UK, Iceland, Norway, Switzerland, Andorra, Liechtenstein, Monaco, San Marino, and the Vatican City State / Holy See, to improve payment success rates on Adyen Integration v2.0, Zuora passes the billing address information to Adyen only if all of the following fields are specified:

  • City
  • Country
  • StreetName
  • StreetNumber
  • Code

These address fields can be specified through the Gateway Options field. See Gateway Options fields supported by Adyen Integration v2.0 for more information. For payment transactions with IBAN from other regions, Zuora does not pass the billing address information to Adyen, regardless of whether the address fields are specified or not. 

Payment method types on request

The following payment method types on Adyen Integration v2.0 can be requested at an additional cost through the Specialized Payment Connections service:

Supported payment operations

The following table describes the supported payment operations for each supported payment method:

Supported Payment Method Payment Operations
ACH
  • Payment
  • Referenced refund
  • Non-referenced refund
BACS
  • Validate
  • Payment
  • Payment cancel
  • Referenced refund
SEPA
  • Validate
  • Payment
  • Referenced refund
  • Non-referenced refund
Credit Card
  • Validate
  • Payment
  • Referenced refund
  • Non-referenced refund
Credit Card Reference Transaction
  • Validate
  • Payment
  • Referenced refund
  • Non-referenced refund
Apple Pay shown as Credit Card
  • Validate
  • Payment
  • Referenced refund
  • Non-referenced refund

Adyen Apple Pay 
  • Validate
  • Payment
  • Referenced refund
Google Pay shown as Credit Card
  • Validate
  • Payment
  • Referenced refund
  • Non-referenced refund

Adyen Google Pay
  • Validate
  • Payment
  • Referenced refund
iDEAL
  • Payment
  • Referenced refund

Support for 3D Secure 2.0

With 3D Secure 2.0 enabled, the value of the authorization amount will be used as the authentication amount, and the authorization amount is always 0.

See Enable 3DS2 for Adyen gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information.

Support for Delayed Capture

The Delayed Capture feature allows you to authorize the availability of funds for a transaction but delay the capture of funds until a later time. Adyen Integration v2.0 supports Delayed Capture for Credit Card transactions, including those processed as Credit Card transactions through Apple Pay and Google Pay.

For how to use the Delayed Capture feature, see Payment Authorization in Zuora API Reference.

The following table lists the mapping of reference fields that are used in the delayed capture process.

Zuora Field Adyen Field
Transaction ID pspReference
Payment Number reference
Payment Number merchantReference

Support for Level 2 and Level 3 card data processing

The Adyen Integration v2.0 gateway integration supports processing Level 2 and Level 3 credit card data. For more information, see the following articles:

Support for stored credential profiles

Adyen Integration v2.0 includes support for the Stored Credential Transactions framework and the sharing NTI feature. For details, see Support for stored credential transactions overview.

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 .

Support for Batch Gateway Reconciliation

The following event types are supported for Batch Gateway Reconciliation:

  • Settlement
  • Rejection
  • Chargeback

For more information, see Batch Gateway Reconciliation on Adyen.

Support for Real-Time Reconciliation

Adyen v2.0 supports the Real-Time Reconciliation feature. With this feature enabled, the payment gateway can submit notifications to Zuora for various event types on gateway objects, and the corresponding records can be automatically updated in real-time. For more information, see the following articles:

Support for Payment Method Updater

You can configure Adyen Payment Method Updater to keep Zuora and you informed about the changes to the credit card information. For more information, see Configure Adyen Payment Method Updater.

Supported Gateway Options fields

You can submit additional information to the Adyen gateway by using Gateway Options fields. For details about the fields supported by Adyen Integration v2.0, see Gateway Options fields supported by Adyen Integration v2.0.

Limitations

Except for SEPA transactions, validating existing tokens is not supported.