Set up and configure a CyberSource payment gateway instance

Merchant ID

The Merchant ID is a unique value that identifies a merchant in the CyberSource system. CyberSource merchants have access to a CyberSource business center, and this ID is used to log into the Business Center. The ID is also submitted with every payment transaction sent from Zuora to CyberSource.

Private Key / Security Key

The private key or security key is used to access the CyberSource system for the provided Merchant ID. You must copy the key content of CyberSource SOAP Toolkit Key in text and paste it to the Security Key field. To obtain the CyberSource SOAP Toolkit Key, follow the instructions in CyberSource documentation.

API Reporting Identifier and API Reporting Key

The following two fields are used to authenticate with the CyberSource gateway for Gateway Reconciliation. You need to log in to your CyberSource account, generate these credentials, and provide the information in the following fields in Zuora.

• API Reporting Identifier: An identifier of who is issuing the shared secret Key for CyberSource reporting. Obtain this value from 
• API Reporting Key: The shared secret key to be used to sign the HMAC encryption for CyberSource reporting. 

Commerce Indicator

The Commerce Indicator specifies the source channel of the transaction request (that is, the environment that the cardholder used to provide the payment card details to the merchant) and the type of transaction being processed. 

The following options are available. It is strongly recommended to select Recurring to prevent the high payment decline rate due to the error code 478.

• Installment
• Internet
• MOTO
• MOTO (Call Center)
• None (defer to gateway): This will be used as the default value for any existing CyberSource gateway that you have already configured. 
• Recurring: This is the default value for new CyberSource gateways. Zuora recommends that you use this value. 
• MasterCard SecureCode
• MasterCard SecureCode authentication failed
• Successful VBV
• VBV attempted but not authenticated
• VBV authentication failed

3DS related fields

The following fields are only available on CyberSource, Payment API v2.0 and when you have the 3D Secure 2.0 feature enabled in the Payment Pages settings. To enable 3DS2, see Enable 3DS2 for CyberSource gateway integration and Zuora’s implementation of 3D Secure 2.0 for more information. The "Best practices" section in Zuora’s implementation of 3D Secure 2.0 also provides best practices for reducing the possibility of failed transactions due to 3DS2 authentication errors.

• Organization ID - The SSO organization unit ID of your merchant account. Contact CyberSource Merchant Support to get the value for this field.
• API Identifier - The identifier of who is issuing the JSON Web Token (JWT) for 3DS session. Contact CyberSource Merchant Support to get the value for this field.
• API Key - The key used to sign the JWT and to verify of JWT signature during 3DS session. Contact CyberSource Merchant Support to get the value for this field.
• Force SCA Challenge on 3DS Requests - By selecting this field, if 3DS2 is enabled in the Payment Pages settings, the challengeCode=04 indicator will be passed to the CyberSource gateway to request the cardholder challenge. The 3DS2 authentication challenge will be enforced if possible. Ultimately, it is the issuing bank that determines whether a card needs to be authenticated through a challenge.

Gateway endpoint

This setting is only available on the CyberSource, Payment API v2.0 gateway integration for selecting the CyberSource endpoint that Zuora will connect to.

Select CyberSource India if you intend to use this gateway instance to process payment methods originating from India. The transaction request is processed through the CyberSource Indian specific endpoint. Non-Indian payment methods processed through this endpoint will fail. 

Select Default to process the transaction request through the CyberSource standard endpoint.

eCheck SEC Code

Standard Entry Class (SEC) codes are used by CyberSource to specify the authorization method of an ACH transaction.

Select one of the following values from the list:

• Internet-initiated Entry (WEB). This is the default authorization method.
• Account Receivable Conversion (ARC).
• Corporate Cash Disbursement (CCD).
• Point of Purchase Conversion (POP).
• Prearranged Payment and Deposit Entry (PPD).
• Telephone-Initiated Entry (TEL).
• None (defer to gateway). Selecting None defers to the default CyberSource settings.

For additional details, reference the documentation for CyberSource Electronic Check Services for the Simple Order API.

Atos processor settings - use recurring indicator 

Select this option only when the Commerce Indicator is set to Recurring. Atos is a French payment processor to which CyberSouce can connect. If you select this option, the Atos recurring feature is used. Atos receives the following values in the "payment pattern" field of the pre-authorization request when the following occurs:

Use Export Compliance

This setting is only available on the CyberSource, Payment API v2.0 gateway integration.

Export Compliance is an added security feature provided by CyberSource, which ensures online merchants comply with the U.S. Government export regulations by not accepting any orders from the blocklisted countries or persons. If you have this feature enabled in your CyberSource merchant account, you must configure the Use Export Compliance setting for the CyberSource, Payment API v2.0 gateway instance.

You can select from one of the following options:

• Disable Export Compliance: It is the default value. The Export Compliance feature will be disabled if you select this option. The exportService_run field will not be included in requests sent to CyberSource.
• Enable for Auth & Payment Capture: With this option selected, Zuora will set the exportService_run field to true and it will be included in payment method validation and authorization, and payment capture calls. If the customer information is in the blocklist, the transaction will be declined.
• Only Enable for Auth: With this option selected, Zuora will set the exportService_run field to true and it will be included in only payment method validation and authorization calls.

Refer to the following CyberSource resources for more Information about Export Compliance:

• What are the features of the Export Compliance Check?
• Verification Services Implementation Guide (see Simple Order API)

 These guides are available in CyberSource Support Center, accessible from Business Center. 

Ability to control whether to pass optional fields to CyberSource

Zuora allows you to control whether or not you want to pass the following optional fields to the CyberSource payment gateway:

• billTo_customerID 
• billTo_company 
• billTo_phoneNumber 
• billTo_ipAddress 

Skip optional fields

By default, these fields are passed by Zuora to CyberSource, but you can control whether they want to discontinue passing these optional fields.

CyberSource recently deployed new front-end validation rules that prohibit the use of special characters in several fields; these validation rules impact the fields listed above. With the ability to control whether to pass these four fields, merchants can proactively choose to not pass these fields if there is a likelihood that data in these fields contain special characters that can cause their payments transactions and payment method authorizations from failing.

Skip Credit Card Expiry Details

CyberSource has introduced a new merchant account setting called Relaxed Requirements for Address Data and Expiration Date. This setting allows merchants to stop passing the credit card expiry details to this specific payment gateway. When enabled, the following information can optionally be passed through the gateway:

• card_expirationMonth
• card_expirationYear

Ignore AVS Result when Verifying Card

This feature is only available for the CyberSource, Payment API v2.0.

This checkbox determines if Zuora ignores the AVS response from the gateway when verifying a payment card. With this check box selected, Zuora will automatically set the businessRules_ignoreAVSResult field to true in your request to CyberSource.

Ignore AVS Result during Payment with Card

This feature is only available for the CyberSource, Payment API v2.0.

This checkbox determines if Zuora ignores the AVS response from the gateway when processing a payment with a card. With this check box selected, Zuora will automatically set the businessRules_ignoreAVSResult field to true in your request to CyberSource.

Soft Descriptor

This field is only available for CyberSource, Payment API v2.0. 

The specified value for this field will be presented on customers’ credit card statements. It corresponds to the merchantDescriptor field on the CyberSource side.

Enable Gateway Reconciliation

This field is only available for CyberSource, Payment API v2.0. Select this checkbox to enable the Gateway Reconciliation feature. Ensure that credentials to access the Gateway Reconciliation service are provided in the API Reporting Identifier and API Reporting Key fields.

The following two Gateway Reconciliation reports are currently supported:

• Processor Events Details Report
• Event Detail Exception report

The generated Gateway Reconciliation reports available to you are dependent on the processor you use. See Supported processors for CyberSource Gateway Reconciliation for more information.

Note that the first run on the first day after the Gateway Reconciliation feature is enabled might not result in any reconciliation reports depending on your CyberSource merchant account setup. CyberSource will check if the reports are available. If the reports are not available, CyberSource will automatically generate the reports and set the reconciliation job to fail. On the second day, everything runs normally. If the job does fail on the first day and works on the second day, you should go back to the first job and click the retry button.

Decision Manager fields

The following fields are specific to the Decision Manager feature of CyberSource, Payment API v2.0:

• Enable Decision Manager on new payment method
• Enable Decision Manager on payment capture
• Enable Decision Manager for new authorizations (includes Invoice Items)
• Decision Manager 'Review' statuses processed as Success

Decision Manager is a fraud detection service that Cybersource offers to its merchants. Zuora integrates with the Decision Manager service and gives you the flexibility to enable this service for different requirements. Zuora's Decision Manager integration provides:

• Support for enabling Decision Manager in authorization and payment requests.
• Support for submitting merchantDefinedData_mddField, ipAddress and deviceFingerprintID to the Decision Manager service in authorization or capture requests through gateway option fields.

Through this integration, you can set custom rules about which payment and billing information is allowed to be processed so that the fraudulent payments can be reduced.

Take the following steps to enable this feature:

1. Log in to the CyberSource console to enable Decision Manager for your CyberSource merchant account:
   • CyberSource console production environment: https://ebc.cybersource.com/ebc2
   • CyberSource console test environment: https://ebctest.cybersource.com/ebc2
2. In your CyberSource account, set up the Example profile under the Configuration tab to establish the initial fraud ruleset. You can also add additional profiles to configure custom rulesets based on your business needs.
3. In Zuora, select one or more of the following checkboxes on the configuration page of the gateway instance. Without any of these checkboxes selected, the Decision Manager service will not run even if the Example profile has been set to run Decision Manager by default.
   • Enable Decision Manager on new payment method: If this option is selected, CyberSource Decision Manager will be activated and it will monitor the fraudulent activity when creating new payment methods.
   • Enable Decision Manager on payment capture: If this option is selected, CyberSource Decision Manager will be activated and it will monitor the fraudulent activity when processing payments.
   • Enable Decision Manager for new authorizations (includes Invoice Items): If this option is selected, CyberSource Decision Manager will be activated. Zuora will send InvoiceItem data in the pre-sale authorization so that CyberSource Decision Manager can use the data to monitor the fraudulent activity.
4. (Optional) Select the Decision Manager 'Review' statuses processed as Success check box.

   For transactions in Review status in CyberSource Merchant Dashboard, Zuora does not handle the review of transactions. The review occurs out side of Zuora. Hence, Zuora does not update the transaction status in Zuora according to the status in CyberSource. For orders in Review status, you need to manually review the order in your CyberSource merchant console.

   By default, Zuora rejects payments and payment methods left in the Review status to avoid accepting invalid payments or payment methods. With the Decision Manager 'Review' statuses processed as Success setting enabled, Decision Manager will reconcile all transactions in the Review status to be processed as Success transactions.

Level 2 and Level 3 fields

The following fields are specific to the Level 2 and Level 3 card data feature of CyberSource, Payment API v2.0:

• Enable Level 2 Processing
• Enable Level 3 Processing
• Processor
• ShipFrom Postal Code Custom Field API Name
• CommodityCode Custom Field API Name
• ProductCode Custom Field API Name 
• Static Value for productCode
• Static Value for commodityCode
• Invoice Items Limit

To learn more about these fields, see Level 2 and Level 3 Support for CyberSource for details. For more information about Zuora's support for Level 3 and Level 2 data, see Level 2 and Level 3 Card Data.

Send Extra CIT Fields

By selecting this setting, when validating credit card and Apple Pay payment methods for cardholder-initiated transactions (CITs), the following fields will be sent to the payment gateway:

• firstRecurringPayment
• subsequentAuthStoredCredential

Initial CyberSource Account is in Test Mode

When your company signs up with CyberSource, your account is initially set up in test mode only and enabled for live mode shortly after. 

Access Test or Live Mode from the CyberSource Business Center

View CyberSource support documentation to understand the difference between test and live modes.

You should perform all testing in Test mode before going to Live Mode. After you have gone live, you can still access the testing environment from your Business Center at: https://ebctest.cybersource.com. From the Business Center, you can view all your transactions. 

Access Test or Live Mode from Zuora

When configuring the CyberSource payment gateway in Zuora, you can indicate whether you would like to use the CyberSource test environment or the CyberSource (Live) environment. 

• If you select Use Gateway Test Environment, Zuora will direct payment transactions to your CyberSource account in test mode.
• If you do not select Use Gateway Test Environment, Zuora will direct payment transactions to your CyberSource account in live mode.

Integration testing

Performance and volume testing

In general, gateway testing environments are intended to give merchants the opportunity to test their gateway and integrations to their gateway, in order to work out any bugs before going to the production environment. Some gateway test environments are shared amongst multiple merchants, and other gateways provide unique testing environments for each merchant. Additionally, gateway test environments (also referred to as certification or sandbox environments) do not have the same high availability or performance capability as production environments. As such, they are not intended for load testing. Merchants performing high volumes of load testing that puts a stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended.