Knowledge Center

Knowledge Center > Billing and Payments > Payment Gateways > Supported Payment Gateways > CyberSource Payment Gateway

CyberSource Payment Gateway

CyberSource is a leading payment gateway that offers fraud management and payment security services. Zuora is pre-integrated with both the CyberSource payment gateway and their Account Updater product.

Supported Versions

Zuora supports the following CyberSource Gateway versions:

  • CyberSource Enterprise Gateway, API v 1.97 (recommended)
  • CyberSource Enterprise Gateway, API v 1.28 (legacy)

If multiple instances of CyberSource v1.28 or CyberSource v1.97 are active at the same time, all certificates must be valid or payments may fail if an expired certificate is used.

Configure the CyberSource Gateway

To set up CyberSource as your gateway, enter your CyberSource credentials in the Z-Payments Settings > Setup Payment Gateway page. When selecting a Gateway Type, choose CyberSource.

Configuration Fields

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

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount
  • Verify new credit card (optional)
  • Verify updated credit card (optional)
  • Default bill to e-mail.

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.

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. 

CyberSource Credentials

Your credentials will be obtained from CyberSource and configured in Zuora. 

cybersource_dropdown.png

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

The Private Key is a .p12 file and can be obtained from CyberSource's Business Center following the Simple Order API instructions for retrieving the file.

  1. In the CyberSource Business Center, click on the Account Management tab (on the bottom of the left navigation bar).
  2. Click the Transaction Security Keys link. 
  3. Select the Security Keys for the Simple Order API which provides instructions for generating the key.
  4. On the Security Keys for the Simple Order API page, click Generate Key
  5. To create and activate a new security key, click Generate Certificate Request. You will be prompted to save the file.  This file represents your security key.

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. 

Commerce Indicator

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

Select one of the following values from the list:

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

eCheck SEC Code

Standard Entry Codes (SEC) 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

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 blacklisted countries or persons. If you have this featured enabled in your CyberSource merchant account, make sure to select this feature when configuring your CyberSource gateway.

With this feature enabled, when a create PaymentMethod()is made in Zuora, Zuora makes an exportService_run() to CyberSource to check export compliance. If the exportService_run()is successful (the customer is not on blacklist), Zuora will do an Auth call using the CyberSource ccAuthService_run(). If ccAuthService_run() fails, the call returns an error to say that the PaymentMethod creation failed.

View these CyberSource resources for more Information on export compliance

1. Article on "What are the features of the Export Compliance Check?"
2. Verification Services Implementation Guide (see Simple Order API)

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

Ability to control whether to pass optional fields to Cybersource

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

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 on 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:

  • billTo_city
  • billTo_country
  • billTo_email
  • billTo_firstname
  • billTo_lastname
  • billTo_postalCode: if you include this field in your request, you must also include billTo_country.
  • billTo_state
  • billTo_street1
  • card_expirationMonth: if you include this field in your request, you must also include card_expirationYear.
  • card_expirationYear: if you include this field in your request, you must also include card_expirationDate.

This feature is only available for the CyberSource Enterprise Gateway v1.97.

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.

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's support documentation to understand the difference between test and live modes.

You should perform all testing in Test mode before going to Live Mode. Once 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.

    CyberSource Test Config.jpg

 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

View CyberSource's Simple Order API Testing Information for test credit cards 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

Troubleshooting Gateway Errors

There are several ways to obtain information on gateway errors:

  1. Search for the error in CyberSource's Support Center accessible via their Business Center. Also, review their support article: "For the Simple Order API, what do the various reason codes indicate?"
  2. Look up the transaction by the transaction ID number (in the Zuora payment detail page, this is the Reference ID and Secondary Reference ID numbers) in your business center to see if more information is provided; often you will see more than just the response (reasons) code and response message in Zuora.
  3. If you require additional information, you can contact CyberSource Support by logging a case in their Business Center > Support Center. All CyberSource merchants have access to online support, and depending on your support package with CyberSource, you may also have access to phone support. Please work with your CyberSource contacts to understand your options for contacting CyberSource Support.

For failed payments processed using the CyberSource payment gateway, Z-Payments will provide the gateway Response Reason Code (for example, 203) and Response Reason text (for example, general decline of the card).

To find more information on CyberSource payment gateway errors, refer to CyberSource's Reason Codes in their Simple Order API User’s Guide.

If you require additional information, you can submit a question to the CyberSource Support Center.  Be sure to have your reason code as well as your Transaction ID (in Z-Payments this is the Reference ID) for the failed payment. This Transaction ID is an alphanumeric number (for example, CLEF4CGE8AB8). 

Make Sure You Are Not Re-Trying an Invalid Card Too Many Times

We recommend that you check the payment in Zuora to see how many times the same payment method has been retried for payment and failed. If there have been several retries, check the error messages from the beginning with the first failure and the more recent failures to determine if the error message is the same. If a merchant tries to process a payment against the same credit card too many times despite receiving errors, this could trigger warnings to the card issuing bank. The card issuing bank may place an alert on the account and not allow any further transactions from the merchant using that payment method. When a mechant has been flagged, the error received on the payment may be not state the reason why, instead it might be a generic decline error. In this case, the merchant (Zuora customer) should work with their merchant acquirer/processor to see if they can identify the problem with the payment method. If the processor does not know, then the merchant and/or the card holder can try calling their card issuing bank to look into the issue.

Cannot reach the payment server. 150 - Error: General system failure

This error is returned by CyberSource, and means that they cannot process transactions at this time. However, it also indicates that there was a successful connection between Zuora and CyberSource.

If you were testing in a CyberSource test environment when you received this error, wait for a few minutes and try again. CyberSource does not guarantee the stability of their test servers. 

Submit a request at Zuora Global Support if you require additional assistance.

If you are testing in a CyberSource production environment and encounter this error, we can help determine the root cause and fix the issue.

Additional Gateway Information

How to Use CyberSource in Canada

If you are using the CyberSource gateway with First Data processor and you would like to process American Express credit card transactions which settle in Canadian currency, you will ensure you are using a First Data platform that supports your requirements. First Data has several payment processing platforms, including a legacy platform called First Data South and a more current platform called OmniPay (based out of First Data in Ireland). The OmniPay platform can process and settle in multi-currency. 

In order to process and settle in Canadian dollars for American Express payments, you must either: 

  • Use the OmniPay platform
  • Have CyberSource submit all American Express payment transactions directly to American Express (to clarify, American Express payments will not go through First Data and will be processed directly by American Express).  

Please work with both CyberSource and First Data to discuss your requirements and suitable options. 

Field Mappings

These sections describe the object and field mappings between Zuora and CyberSource for credit card and ACH payment methods. 

Credit Card Field Mappings

API field passed to CyberSource Source of this information in Zuora (object.field) Zuora PaymentMethod API field
card_accountNumber PaymentMethod.CreditCardNumber CreditCardNumber
card_cvNumber PaymentMethod.CreditCardSecurityCode CreditCardSecurityCode
card_expirationMonth PaymentMethod.CreditCardExpirationMonth CreditCardExpirationMonth
card_expirationYear PaymentMethod.CreditCardExpirationYear CreditCardExpirationYear
purchaseTotals_currency Account.Currency Currency
item_0_unitPrice Payment.Amount Amount
purchaseTotals_grandTotalAmount Payment.Amount Amount
billTo_email PaymentMethod.Email field WorkEmail
billTo_phoneNumber PaymentMethod.Phone Phone
billTo_ipAddress PaymentMethod.IPAddress IPAddress
billTo_firstName PaymentMethod.CreditCardHolderName CreditCardHolderName
billTo_lastName PaymentMethod.CreditCardHolderName CreditCardHolderName
billTo_street1 PaymentMethod.CreditCardAddress1 CreditCardAddress1
billTo_street2 PaymentMethod.CreditCardAddress2 CreditCardAddress2
billTo_city PaymentMethod.CreditCardCity CreditCardCity
billTo_customerID Account.AccountNumber AccountNumber
billTo_company Account.Name Name
billTo_state PaymentMethod.CreditCardState CreditCardState
billTo_postalCode PaymentMethod.CreditCardPostalCode CreditCardPostalCode
billTo_country PaymentMethod.CreditCardCountry CreditCardCountry

ACH Field Mappings

API field passed to CyberSource Source of this infomation
in Zuora (object.field)
Zuora PaymentMethod
API field
check_bankTransitNumber PaymentMethod.AchAbaCode AchAbaCode
check_accountNumber PaymentMethod.AchAccountNumber AchAccountNumber
purchaseTotals_currency Account.Currency Currency
item_0_unitPrice Payment.Amount Amount
purchaseTotals_grandTotalAmount Payment.Amount Amount
billTo_email PaymentMethod.Email field WorkEmail
billTo_phoneNumber BillToContact.WorkPhone WorkPhone
billTo_firstName PaymentMethod.AchAccountName AchAccountName
billTo_lastName PaymentMethod.AchAccountName AchAccountName
billTo_street1 BillToContact.Address1 Address1
billTo_street2 BillToContact.Address2 Address2
billTo_city BillToContact.City City
billTo_customerID Account.AccountNumber AccountNumber
billTo_company Account.Name Name
billTo_state BillToContact.State State
billTo_postalCode BillToContact.PostalCode PostalCode
billTo_country BillToContact.Country Country

 

Credit Card Reference Transactions

Zuora supports a CyberSource token for credit card reference transactions. A reference transaction is a representation of a credit card payment method without having sensitive payment method information like the credit card number stored in Zuora. Support for tokens with CyberSource requires a gateway type called CyberSource Tokenization.

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

Please note that the token cannot be used with another gateway, which is why we recommend storing credit card information in Zuora whenever possible.

See the following topics for more information about setting up credit card reference transactions in Zuora.

The following SOAP API call can be used to create a payment method that represents a CyberSource-stored credit card.

<ns1:create>
  <ns1:zObjects xsi:type="ns2:PaymentMethod">
    <ns2:AccountId></ns2:AccountId>
    <ns2:TokenId></ns2:TokenId>
    <ns2:Type>CreditCardReferenceTransaction</ns2:Type>
  </ns1:zObjects>
</ns1:create> 
Last modified

Tags

This page has no custom tags.

Classifications

(not set)