Skip to main content

Level 2 and Level 3 Support for CyberSource


Level 2 and Level 3 Support for CyberSource

The CyberSource, Payment API v2.0 gateway integration gives you the flexibility to submit Level 2 and Level 3 credit card data.

Supported Payment Methods

CyberSource v2.0 supports Level 2 and Level 3 card data on Credit Card and Credit Card Reference Transaction payment methods. The following table shows the processors and card types that are supported.

Processor Card Types Supported by Level 2 Card Types Supported by Level 3
Chase Paymentech Solutions
  • Visa
  • Mastercard
  • American Express
  • Visa
  • Mastercard
FDC Nashville Global
  • Visa
  • Mastercard
  • American Express
  • Visa
  • Mastercard
  • Visa
  • Mastercard
  • Visa
  • Mastercard


  • Some processors, such as Chase Paymentech Solutions, do not automatically downgrade Level 2 or Level 3 requests for consumer cards, which might result in payment failures for transactions processed through CyberSource. To mitigate the risk of payment failures, it is suggested not to enable Level 2 and Level 3 card data processing on the CyberSource gateway instance.

  • CyberSource and the supported processors do not accept negative invoice item amounts and negative tax amounts for a Level 2 and Level 3 request. For this reason, if the payment invoices contain any negative amount, the payment will be sent as a regular non-Level 2 or non-Level 3 payment, and none of the Level 2 and Level 3 request fields will be included in the payment request.
  • For multiple invoice line items, CyberSource supports up to 98 items in a single payment capture request for Level 2 and Level 3 processing. Note that you must enter the CyberSource limit in the Invoice Items Limit gateway setting.
  • For all processors supported by this integration, the level 2 and level 3 fields are processed only for Visa, Mastercard, and American Express payment transactions.


You must determine which processor you are using with CyberSource. For payment processing with Level 2 and Level 3 through Zuora, you must be on one of the three processors listed above. If you want to enable Level 3 processing to your contract or account setup, contact CyberSource Customer Support to have the merchant account configured to process Level 3 data. If your account is not enabled and you try to make Level 3 transactions, you will receive an error for the invalid data.

If you are using the FDC Nash Global processor to process non-US Visa Level 2 transactions, the PurchaserVATRegistrationNumber is required and it must come from the VATId field in your Zuora account. The VATId field on Zuora account is in Limited Availability. Contact Zuora Global Support to get the VAT ID.

You have to configure the following custom fields in Zuora:

  • You can specify the gateway settings described in Step 5 below to save static values for the Commodity Code and Product Code custom fields that are required by Level 3 processing. If you do not specify the static values, you have to configure these two custom fields at the Product Rate Plan Charge level. The maximum length for these fields is 15.
  • 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 Processing

After you have enabled this feature, you need to complete the following additional information in your CyberSource, Payment API v2.0 gateway instance for Level 2 and Level 3 processing:

  1. Select the Enable Level 2 Processing or Enable Level 3 Processing checkboxes to enable Level 2 or Level 3 processing. Note that if both checkboxes are selected, then Level 3 is enabled.
  2. For the Processor list, select the processor your CyberSource account is using.
  3. For Chase Paymentech Solutions or FDC Nashville Global processor, the ShipFrom Postal Code Custom Field API Name field must be included for each payment request. ShipFromPostalCode must be configured in Zuora as an Account level custom field. Enter the API name for this custom field as a gateway setting. The postal code consists of 5 to 9 digits.
    • If the billing country is the U.S., the 9-digit postal code must follow this format: [5 digits][dash][4 digits]. For example, 12345-6789.
    • If the billing country is Canada, the 6-digit postal code must follow this format: [alpha][numeric][alpha][space][numeric][alpha][numeric]. For example, A1B 2C4.   
  4. If you do not specify the settings described in Step 5, enter the CommodityCode API name and ProductCode API name in the CommodityCode Custom Field API Name and ProductCode Custom Field API Name fields, respectively. CommodityCode and ProductCode 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 rate. 

    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.  

  5. If you specify the following fields, you do not need to configure the preceding charge level custom fields:
    • Static Value for commodityCode
    • Static Value for productCode
    Zuora will then use the specified values for all invoice charges, and level 2 and level 3 capture requests, instead of getting values from charge level custom fields. You can also choose to specify only one field, or leave both fields empty. If you do not specify a static value, you must configure a corresponding charge level custom field and enter the API name for this custom field in the gateway settings described in Step 4, to avoid payment failures. 
  6. Enter the Invoice Items Limit gateway setting for Level 2 and Level 3 requests. Currently, CyberSource documents this limit as 98. Therefore, you need to enter 98 in the Invoice Items Limit field in the gateway instance configuration page.

Level 3 Processing

CyberSource requires that the unit price of invoice items for Level 3 transactions must not be zero. To ensure that you can successfully collect payments, Zuora does the following processing for Level 3 payments:

  • Removes 0 (zero) amount invoice items from Level 3 Mastercard payments.
  • When the unit price on the product rate plan charge is zero but the corresponding invoice item amount is non-zero, Zuora uses the non-zero invoice item amount for the unitPrice field of CyberSource in Level 3 Mastercard payments.

For more information about Level 2 and Level 3 payment processing for CyberSource, see CyberSource's Level 2 and Level 3 Processing.