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
The following payment methods are supported by the Level 2 and Level 3 card data feature of CyberSource, Payment API v2.0:
- Credit Cards, including:
- American Express
- Credit Card Reference Transactions
The processors for which CyberSource Level 2 and Level 3 processing is supported include:
- Chase Paymentech Solutions: Level II and Level III
- FDC Nashville Global: Level II and Level III
- GPN: Level II and Level III
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.
Additionally, you have to 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, you need to complete the following additional information in your CyberSource, Payment API v2.0 gateway instance for Level 2 and Level 3 processing:
- 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.
- For the Processor list, select the processor your CyberSource account is using.
- 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.
- 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.
- 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.
- Optionally specify static values for ProductCode and CommodityCode only if you notice that these fields are sent as
nullin payment requests for pre-existing subscription charges. Zuora will only use these values when an old subscription charge has null custom fields:
- Default Value for CommodityCode
- Default Value for ProductCode
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
unitPricefield 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.
- 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.