Skip to main content

Level 2 and Level 3 Support for Adyen Integration v2.0

Zuora

Level 2 and Level 3 Support for Adyen Integration v2.0

  1. Last updated
  2. Save as PDF

The Adyen Integration v2.0 gateway integration gives you the flexibility to submit Level 2 and Level 3 credit card data. 

Supported Payment Methods

Adyen integration v2.0 supports Level 2 and Level 3 card data processing for the following payment methods:

  • Credit Cards, including:
    • Visa
    • Mastercard
    • American Express
  • Credit Card Reference Transactions

Prerequisites

  • Work with Adyen to correctly set up Level 2 and Level 3 requests in your Adyen merchant account. 
  • Configure the following custom fields in Zuora:
    • At the Product Rate Plan Charge level, configure the Commodity Code and Product Code custom fields. The maximum length for these fields is 12.  
    • At the Account level, configure the ShipFrom Postal Code custom field. The maximum length for this custom field is 10.  

    Later, the API names (without "__c") for these custom fields need to be entered on the gateway configuration page.

Enable Level 2 and Level 3 Card Data Submission

After you have enabled this feature, complete the following additional information on the Adyen Integration v2.0 gateway configuration page for Level 2 and Level 3 card data processing:

  • Select the Enable Level 2 Processing or Enable Level 3 Processing check box to enable Level 2 or Level 3 card data processing. Note that if both checkboxes are selected, then Level 3 is enabled.
  • Enter ShipFromPostalCode in the ShipFrom Postal Code API Name field. ShipFrom Postal Code must be configured as an Account level custom field in Zuora. 
  • Enter CommodityCode and ProductCode in the CommodityCode Custom Field API Name and ProductCode Custom Field API Name fields, respectively. Commodity Code and Product Code must be configured in the Zuora product catalog as ProductRatePlanCharge level custom fields. These two fields are required to qualify your merchant account for Level 2 and Level 3 interchange rates. 

    You should enter the custom field API names without the __c suffix.

    If you want to populate the preceding custom fields to existing subscriptions, you must set up the custom fields using identical API names on the Product Rate Plan Charge and Subscription Rate Plan Charge objects. Then you need to update the existing subscription rate plan charges with the custom field values you want to use.  

Field mapping and constraints

Adyen Level2/Level3 field Zuora field and constrants
enhancedSchemeData.customerReference Invoice number if it is present. The maximum length is 25 characters.
enhancedSchemeData.itemDetailLine[itemNr].productCode Must be configured in Zuora product catalog as ProductRatePlanCharge level custom fields. The maximum length is 12 characters.
enhancedSchemeData.itemDetailLine[itemNr].commodityCode Must be configured in Zuora product catalog as ProductRatePlanCharge level custom fields. The maximum length is 12 characters.
enhancedSchemeData.shipFromPostalCode Must be configured as an Account level custom field in Zuora. This value is passed to the gateway when the credit card type is not American Express. The maximum length is 10.
enhancedSchemeData.freightAmount Always set to 0.
enhancedSchemeData.dutyAmount If the credit card type is not American Express, this field is set to 0.
enhancedSchemeData.itemDetailLine[itemNr].description The description field on the InvoiceItem object in Zuora if it is present. The maximum length is 26.
enhancedSchemeData.itemDetailLine[itemNr].quantity The quantity field on the InvoiceItem object in Zuora if it is present. The maximum length is 12.
enhancedSchemeData.itemDetailLine[itemNr].unitOfMeasure The unitofmeasure field on the InvoiceItem object in Zuora if it is present. The maximum length is 3.
enhancedSchemeData.itemDetailLine[itemNr].totalAmount

Zuoraa combines the values from the amount_without_tax and tax_amount fields on the InvoiceItem object and consider it as totalAmount. If the currency is any of "BYR, CVE, DJF, GHC, GNF, IDR, JPY, KMF, KRW, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF"(zero decimal currency), the value of totalAmount is rounded to 2 decimal places. Otherwise, the value of totalAmount is rounded to 2 decimal places and multiplied by 100.

The maximum length is 12.
enhancedSchemeData.itemDetailLine[itemNr].unitPrice The unitprice field on the InvoiceItem object in Zuora and it is rounded to 2 decimal places.
enhancedSchemeData.itemDetailLine[itemNr].discountAmount The discount field on the InvoiceItem object in Zuora and it is rounded to 2 decimal places. This field is passed to the gateway when the credit card type is not American Express. If the currency is any of "BYR, CVE, DJF, GHC, GNF, IDR, JPY, KMF, KRW, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF"(zero decimal currency), discount is the same value. Otherwise, totalTaxAmount is multiplied by 100. The maximum length is 12.
enhancedSchemeData.totalTaxAmount

The tax amount field on the InvoiceItem object in Zuora. If the currency is any of "BYR, CVE, DJF, GHC, GNF, IDR, JPY, KMF, KRW, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF"(zero decimal currency), totalTaxAmount is the same value. Otherwise, totalTaxAmount is multiplied by 100. 

The maximum length is 12.
enhancedSchemeData.destinationCountryCode If the value of the SoldToContactCountry field (3-letter ISO code) is present and the credit card type is not American Express, Zuora sets this field to the value same as SoldToContactCountry. The maximum length is 3 characters.
enhancedSchemeData.destinationPostalCode If the value of the SoldToContactZip field is present, Zuora sets this field to the value same as SoldToContactZip. The maximum length is 10 characters.
enhancedSchemeData.destinationStateProvinceCode If the value of the SoldToContactState field is present and the credit card type is American Express, Zuora sets this field to the 2-letter state code if the SoldToContactState length is greater than 2 and SoldToContactCountry value is present. Otherwise, keep the value the same as SoldToContactState.
enhancedSchemeData.orderDate If the credit card type is American Express, Zuora sets the date and time in PST timezone.

Limitation

Adyen currently documents the number of invoice line items limit for a level 2 or level 3 payment request as 9. If a payment includes more than 9 invoice items, the payment is processed as usual, but is disqualified for the discounted interchange rate on the Adyen side. Therefore, Zuora includes the level 2 or level 3 fields for up to 9 invoice line items within each payment request so that you can get the interchange discount.