X-Cart:CyberSource

This article describes setting up CyberSource for X-Cart 4.3.0 and above. To find out how to set up CyberSource for previous versions (4.0.0 - 4.2.x), read this article.

X-Cart 4.3or above

Overview

CyberSource is one of the largest global payment gateways and merchant services providers with headquarters in the United States, United Kingdom and Japan. CyberSource provides several different options for accepting payments online. X-Cart is currently integrated with the following solutions: CyberSource Hosted Order Page (HOP) and CyberSource SOAP toolkit API. The major difference between the two options is where you host the payment pages for you store.

CyberSource Hosted Order Page

With CyberSource Hosted Order Page you completely outsource the payment pages with CyberSource, which enables you to processes payments without the risk of handling or storing sensitive cardholder data. Since customers get redirected to the CyberSource secure website and enter their card details there, you do not need to obtain and install an SSL certificate.

CyberSource SOAP toolkit API

With CyberSource SOAP toolkit API the payment pages are hosted with the rest part of the store. The data is transmitted to CyberSource in the background mode and customers never leave your website during the purchase. Since the connection method uses SSL encryption, you must obtain and install an SSL certificate to your server/hosting account. For recommended SSL certificate providers please check the X-Cart marketplace at https://marketplace.x-cart.com/. Another requirement is that your server must provide support for any of the following HTTPS modules: Net::SSLeay, CURL, libCURL, OpenSSL or HTTPS-cli.

Obtaining a CyberSource Account

If you have not registered an account with CyberSource yet, you should do it before you start setting up CyberSource in X-Cart. For instructions on how to open an account contact a CyberSource representative using the form at https://www.cybersource.com/contact_us/. After you have registered an account, you can set up CyberSource Hosted Order Page (HOP) and CyberSource SOAP toolkit API in the X-Cart Admin area.

Setting up CyberSource Hosted Order Page

To use CyberSource Hosted Order Page as one of the payment options in the store:

1. Log in to the X-Cart Admin area.
2. Go to the Payment methods section (Administration menu -> Payment methods) and scroll down to the Payment gateways form.
3. Select CyberSource (hosted page) from the drop-down list and click the Add button.
   
   
   
   After you have clicked on Add, CyberSource Hosted Order Page will be added to the list of the available payment methods.
   
   
   
   Note: If you set up a payment method providing online credit card payment processing and do not intend to process credit card payments manually, you should disable the default "Credit Card" payment method, that requires manual payment processing, by unselecting the check-box next to the payment method's name. Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change the online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.
   The $store_cc variable in the config.php file must be set to false in case you disable the default 'Credit Card' payment method and do not intend to process credit card payments manually.
4. Click on the Configure link. This opens the configuration page for CyberSource Hosted Order Page.
   
   
5. Adjust the configuration settings for CyberSource Hosted Order Page and click the Update button to apply the changes.
   • Currency: Choose the currency in which you wish to accept payments through CyberSource Hosted Order Page.
   • Test/Live mode: Choose the mode in which the gateways must operate.
     
     The "test" mode means that you can submit test orders and perform test transaction. Money will not be withdrawn from credit cards. The "live" mode is the full functioning mode with real transactions and charges. It must be used when only you are ready to go live.
   • Action to be performed on order placement: Choose whether CyberSource Hosted Order Page must capture money automatically (Auth and Capture) or only freeze the funds until you capture the authorized amount manually through the X-Cart Admin area (Auth only).
   • Order prefix: Enter a prefix that will be automatically added to IDs of orders placed in your store and paid through CyberSource Hosted Order Page.
     
     Having a prefix ensures that orders will have unique IDs and will never coincide with orders placed in another online store of yours that also uses CyberSource as a payment option.
     
     The values of the next 4 fields are supposed to be retrieved automatically from the security PHP script. The security script can be generated in the CyberSource back-office as follows:
     - Log in to your CyberSource account at https://ebc.cybersource.com/
     - Go to Tools & Settings -> Hosted Order Page -> Security -> Generate Security Script.
     - Select a radio button PHP, which stands for the respective scripting language, click Submit, and follow the instructions on the screen.
     
     As a result, you must be able to download a file HOP.php onto your local computer. The file should then be uploaded through the "Upload security script" form on the configuration page.
     
     The fields mean as follows:
   • Merchant ID: The name of your merchant account with CyberSource.
   • Serial number: A unique code assigned to the security script to ensure its integrity.
   • Public key and Secret key: Cryptographic keys.
     
     These two keys are used to encrypt/decrypt requests and responses via the public-key cryptography method. Public-key cryptography is a cryptographic approach employed by CyberSource that uses different keys to encrypt and decrypt messages: Each party uses a pair of keys - a public key and a private key; the public key is used to decrypt messages, and it is distributed freely, the private key is used to decrypt messages encrypted with the public key, and it must be kept in secret. In CyberSource, a secret key is an implementation of a private key.
6. Return to the list of payment methods and activate CyberSource Hosted Order Page by selecting the check box next to the gateway's name.
7. Click the Update button.

After you have configured and activated the gateway, your customers will be able to choose CyberSource Hosted Order Page as a payment option.

Setting up CyberSource SOAP Toolkit API

To use CyberSource SOAP toolkit API as one of the payment options in the store:

1. Log in to the X-Cart Admin area.
2. Go to the Payment methods section (Administration menu -> Payment methods) and scroll down to the Payment gateways form.
3. Select CyberSource (SOAP toolkit) from the drop-down list and click the Add button.
   
   
   
   After you have clicked on Add, CyberSource SOAP toolkit API will be added to the list of the available payment methods.
   
   
   
   Note: If you set up a payment method providing online credit card payment processing and do not intend to process credit card payments manually, you should disable the default "Credit Card" payment method, that requires manual payment processing, by unselecting the check-box next to the payment method's name. Additionally, you can change the default "Credit Card" payment method's name to "Credit Card (offline)", and change the online payment method's name to "Credit Card". This will help you to avoid any confusion between these two payment methods.
   The $store_cc variable in the config.php file must be set to false in case you disable the default 'Credit Card' payment method and do not intend to process credit card payments manually.
4. Click on the Configure link. This opens the configuration page for CyberSource SOAP toolkit API.
   
   
5. Adjust the configuration settings for CyberSource SOAP toolkit API and click the Update button to apply the changes.
   • Merchant ID: Enter the name of your merchant account with CyberSource.
   • CyberSource security key file (full path with filename): Specify the exact location and the filename of a file with the security key for the SOAP Toolkit API.
     
     The file must be located on the file system together with X-Cart, and the location must be specified as a relative path as a relative path in the <xcart_dir>/payment/certs/ directory.
     
     If you do not yet have a file with a security key, generate it in the CyberSource back-office:
     • Log in to the CyberSource account.
     • Go to the section Account Management -> Transaction Security Keys -> Security Keys for the SOAP Toolkit API.
     • Click the Generate button.
     • Click the Download button to download a file with the key onto your local computer.
       
       After you have generated the file and downloaded it to your local computer, upload the file to the server where X-Cart is installed. The file is named like CyberSourceKey_xxxxxxxxxxxxxx.txt where x means a number. An example file is contained in <xcart_dir>/payments/certs/cybersource-demo-key.txt.
   • Currency: Choose the currency in which you wish to accept payments through CyberSource SOAP toolkit API.
   • Test/Live mode: Choose the mode in which the gateways must operate.
     
     The "test" mode means that you can submit test orders and perform test transaction. Money will not be withdrawn from credit cards. The "live" mode is the full functioning mode with real transactions and charges. It must be used when only you are ready to go live.
   • Action to be performed on order placement: Choose whether CyberSource SOAP toolkit API must capture money automatically (Auth and Capture) or only freeze the funds until you capture the authorized amount manually through the X-Cart Admin area (Auth only).
   • Order prefix: Enter a prefix that will be automatically added to IDs of orders placed in your store and paid through CyberSource SOAP toolkit API.
     
     Having a prefix ensures that orders will have unique IDs and will never coincide with orders placed in another online store of yours that also uses CyberSource as a payment option.
6. Return to the list of payment methods and activate CyberSource SOAP toolkit API by selecting the check box next to the gateway's name.
7. Click the Update button.

After you have configured and activated the gateway, your customers will be able to choose CyberSource SOAP toolkit API as a payment option.

Updating Your Certificate and Private Key

1) Update Keys and Certificates https://www.cybersource.com/support_center/management/keyupdate/

2) CyberSource instructions for updating your keys: https://www.cybersource.com/resources/collateral/pdf/20010423_Certificate_Update_UG.pdf

3) Download: Update to ECert Application https://apps.cybersource.com/cgi-bin/pages/additional.cgi?kit=Update_to_ECert_Application

Troubleshooting

CyberSource Hosted Order Page: 'orderPage_signaturePublic INVALID' error

Problem description: When placing an order via CyberSource Hosted Order Page, the following error message shows up:

An error occurred while you submitted your order. If you are trying to make a purchase, please contact the merchant.

In the table which appears below the error message, the API field 'orderPage_signaturePublic' is marked as INVALID.

Solution:

• Generate a new security script (HOP.php) in your CyberSource back-office;
• Upload the new security script through the "Upload security script" on the configuration page for CyberSource Hosted Order Page in your X-Cart X-Cart Admin area.

CyberSource Hosted Order Page: Script parse error

Problem description: Upon uploading the security script HOP.php via the admin, I am presented with the following error message:

Script parse error. The following tokens must be retrieved from the script and inserted into the corresponding fields manually:
- PublicKey
- PrivateKey

Problem source: CyberSource has changed their security script HOP.php, so as PublicKey and PrivateKey are not used anymore. Instead, SharedSecret is provided with the security script.

Solution: To solve the problem, modify "include/csrc_retrieve_keys.php" file in your X-Cart installation as follows:

- find these lines:

'param05'    => 'PublicKey',
'param06'    => 'PrivateKey',

- and change them to:

'param05'    => 'SharedSecret'

After that, you will be able to upload your security script HOP.php via the admin.

Alternatively, you can manually fill in the necessary field: just copy the value of SharedSecret from your HOP.php, and paste this value into the Public key field on the configuration page.

Here is an example of data provided with the security script HOP.php:

function getMerchantID() { return  "npc_demo73"; }
function getSharedSecret()  { return "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2jZ+a9jRVa0nbGUyaDx2A6Dd3D6bJwh5uL5KzE1KYhgXg6lhAOuI8deWEAOm2uJhd1iXL/uYyg2+8urbv3amrwodh+iVQlqTCU07/6eFS8ZGO1koq11NM3GjrZnX8QHzrZqs1LTRbbGpvXMTuvAl7tow6kcHluGpoDBeK6QeeUQIDAQAB"; }
function getSerialNumber() { return "3057126456700176056166"; }

So, the value that must be inserted into the Public key field on the configuration page is:

MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2jZ+a9jRVa0nbGUyaDx2A6Dd3D6bJwh5uL5KzE1KYhgXg6lhAOuI8deWEAOm2uJhd1iXL/uYyg2+8urbv3amrwodh+iVQlqTCU07/6eFS8ZGO1koq11NM3GjrZnX8QHzrZqs1LTRbbGpvXMTuvAl7tow6kcHluGpoDBeK6QeeUQIDAQAB

In the same way, you can manually fill in the other fields - Merchant ID and Serial number.