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.

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 http://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 http://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.
   
   
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.
   
   
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 http://www.cybersource.com/support_center/management/keyupdate/

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

3) Download: Update to ECert Application http://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 blow the error message, the API field 'orderPage_signaturePublic' that was sent in the request 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" form on the configuration page for CyberSource Hosted Order Page in your X-Cart X-Cart Admin area.