Skip to main content

Set up and configure a CyberSource payment gateway instance

Zuora

Set up and configure a CyberSource payment gateway instance

Set up and configure a CyberSource payment gateway instance by using the information in this article, including configuration procedure, descriptions of the configuration fields, and references for testing the payment gateway.

Procedure

Take the following steps to set up and configure a CyberSource gateway instance:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway
  2. Select one of the following types for Gateway Type:
    • CyberSource, Payment API v2.0
    • CyberSource Enterprise Gateway API v1.97
    • CyberSource Enterprise Gateway API v1.28
  3. Click Create Gateway.
  4. Complete the configuration for the gateway instance. For more information about the configuration fields, see "Configuration fields".
  5. Click save gateway information after entering the necessary information.

Configuration fields

Common configuration fields

There are some common fields you must complete for every gateway configuration. We recommend you review Setting Up Payment Gateways for information on these fields including: 

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
  • Verify new payment method (optional)
  • Verify updated payment method (optional)
  • Default bill to email
    This field requires a valid email address. This value is used in credit card and ACH transactions if the Bill To email address is not specified for the credit card payment method or the billing account. This field is used for reporting and fraud screening for both credit card and ACH payments. If you do not have an email value for a given transaction, we recommend using null@cybersource.com as the value.

Specific configuration fields

In addition to the common fields, every gateway has unique requirements and information (such as credentials and certain rules) that you must provide to configure the gateway in Zuora. 

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. 

You can use the same Merchant ID and Private Key for both versions of the CyberSource gateway. You may need a new merchant ID from CyberSource to take advantage of some of the v1.97 features.

Private Key / Security Key

The private key or security key is used to access the CyberSource system for the provided Merchant ID. 

For CyberSource Enterprise Gateway API v1.28 and v1.97, the Private Key is a .p12 file and this file can be obtained from CyberSource Business Center. For CyberSource Payment API v2.0, you must copy the key content in text and paste it to the Security Key field.

  • To obtain the private key file for CyberSource Enterprise Gateway API v1.28 and v1.97, complete the following steps:
  1. Log in to Cyber Source Business Center.
  2. In the left navigation pane, click Payment Configuration > Key Management.
  3. Click GENERATE KEY.
  4. Select the Transaction Processing key type.
  5. Select the Simple Order key subtype.
  6. Read the instruction displayed, then click Submit
  7. Open the downloaded file and run the program. 
  8. Click Generate Certificate Request and locally save the file.

    You must save the file using the .p12 file extension. If you save the file with a different file extension, you will receive a file format error. 

  9. Select the .p12 file for the Private Key field on the New Gateway page.
  • To obtain the security key for CyberSource Payment API v2.0, complete the following steps:
  1. Log in to Cyber Source Business Center.
  2. In the left navigation pane, click Payment Configuration > Key Management.
  3. Click GENERATE KEY.
  4. Select the Transaction Processing key type.
  5. Select the SOAP key subtype.
  6. Click Submit and you can view the content of the key.
  7. Copy the whole key string and paste it to the Security Key field on the new gateway configuration page.

More detailed and up-to-date instructions about how to obtain the private key can be found from the Simple Order API & SOAP Toolkit API page on the CyberSource website.

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.
  • API Identifier - The identifier of who is issuing the JSON Web Token (JWT) for 3DS session.
  • API Key - The key used to sign the JWT and to verify of JWT signature during 3DS session.
  • 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:

  • RECURRING_1, if the CVV code is entered for the transaction.
  • RECURRING_N, when there's no CVV code entered.

Contact CyberSource for additional information on the purpose and benefits of this option.

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:

 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

This feature is only available for the CyberSource Enterprise Gateway v1.97 and CyberSource, Payment API v2.0. You must contact CyberSource to enable this feature for your merchant account. Merchants that choose not to include one or more of these fields increase their risk of declined transactions and have an increased risk for possible fraud.

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.

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

See the Enable Decision Manager section below for more information.

Enable Decision Manager

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.
  • Support for handling Decision Manager review and reject status.

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:
  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. By default, Zuora rejects payments and payment methods left in the Review status to avoid accepting invalid payments or payment methods. With this check box selected, 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.

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

In December 2022, we plan to remove this setting from Zuora UI and enforce passing the preceding two fields to payment gateways.

Test your configuration

We recommend testing your CyberSource payment gateway using both your payment gateway's test and production (live) environments.  Once you have completed testing in the gateway's test environment, Zuora recommends that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

Access your gateway test environment

Some payment gateways provide separate credentials for merchants to access their testing environment, some gateways use the same credentials for testing as for the production (live) environment but direct test transactions to a different URL, and other gateways do a little of both. CyberSource uses the same credentials for test and live transactions, however, you have to make sure your account is in test mode for testing and live mode for production. 

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.

 Your credentials will be the same for both test and production environments. Zuora ensures your payment transactions are routed to the right environment (mode) based on whether the Use Gateway Test Environment is selected.

Test credit cards and testing scenarios

See the following documentation for test payment methods and general testing information: 

General testing information

Integration testing

Zuora has been certified with CyberSource as an integration partner and maintains the integration on an ongoing basis, thoroughly testing the integration with every new release. The CyberSource integration documentation is helpful if you are integrating CyberSource directly with your website, however, you do not need to perform any integration or certification testing to submit transactions to CyberSource via the Zuora application. The intended audience for the integration guides are technical integrators, however, these documents can be helpful to non-technical integrators who can refer to it for information on testing and troubleshooting gateway errors (as described below). 

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.