CyberSource Gateway Integration
The CyberSource integration allows UltraCart merchants to securely process credit and debit card transactions through the CyberSource (a Visa solution) payment gateway. UltraCart connects to CyberSource using the Simple Order API, authenticated with a transaction security key you generate in the CyberSource Business Center.
This guide walks you through:
Generating a Simple Order API security key (.p12) in the CyberSource Business Center
Configuring the CyberSource gateway in UltraCart
Testing and validating your integration
This guide replaces the older key-generation process that relied on a Java applet. CyberSource now generates and downloads the security key directly from the Business Center — no Java is required.
Capabilities
The CyberSource gateway supports the following functionality within UltraCart:
Capability | Supported |
|---|---|
E-Check / ACH | No |
Multi-Currency | Yes |
Refunds | Yes |
Auth then Capture | Yes |
Zero Dollar Authorization | No |
3rd Party Processor (hands off to processor website) | No |
Supported card types: Visa, Mastercard, American Express, Discover, Diners Club, and JCB.
Prerequisites
Before configuring CyberSource in UltraCart, ensure you have the following:
An active CyberSource merchant account and your CyberSource Merchant ID.
Access to the CyberSource Business Center with permission to manage keys.
UltraCart administrative access to the payment gateway configuration.
Generate your key in the environment you will process in. Keys created in the Test Business Center do not work in Production, and vice versa.
Step 1: Generate a Simple Order API Security Key
UltraCart authenticates to CyberSource with a Simple Order API security key, downloaded as a PKCS #12 (.p12) file.
Sign in to the CyberSource Business Center for the environment you process in (Test or Production).
In the navigation pane, select Payment Configuration → Key Management.
Select + Generate Key.
Choose Simple Order API as the key type.
Select Generate Key.
Review the on-screen instructions and select Download Key.
When the Set Password page appears, enter and confirm a password for the key.
Save the downloaded
.p12file to a secure location.
Record the password you set in step 7. You must enter this exact password into UltraCart (Step 2) for UltraCart to open the .p12 file. If the password does not match, the key cannot be used.
Step 2: Configure CyberSource in UltraCart
Navigate to the UltraCart payment gateway configuration:
Main Menu → Configuration → Checkout → Payments → Transaction Gateways
Create or edit a Single Transaction Gateway.
Select CyberSource as the gateway type.
Complete the configuration fields described below.
Configuration Fields
Field | Description |
|---|---|
CyberSource Merchant ID | Your CyberSource Merchant ID (the same ID you use to sign in to the Business Center). |
CyberSource P12 Password | The password you set when downloading the |
Upload CyberSource Key File | Click this link and upload the |
Methods | Check each card type you are approved to process through CyberSource: AMEX, Diners Club, Discover, JCB, Mastercard, Visa. |
After entering the Merchant ID and P12 Password, uploading the key file, and selecting your card types, click Save at the bottom of the page.
Rotating Transaction Gateways
CyberSource can also be configured under Rotating Transaction Gateways for merchants who distribute volume across multiple gateway accounts:
Main Menu → Configuration → Checkout → Payments → Rotating Transaction Gateways
The fields are identical — enter the Merchant ID and P12 Password, upload the .p12 key file, select the card types, and save.
Step 3: Save and Test the Configuration
Click Save.
Place a test order in your storefront.
While testing, use a key generated in the Test Business Center environment.
Verify:
The transaction completes successfully
No gateway errors appear in the order logs
The correct card types are accepted
Once testing passes, generate a Production key, upload it, and enter the matching Production Merchant ID and P12 Password.
Security Best Practices
Follow these practices to protect your integration:
Store the
.p12key file in a secure location with restricted access, and delete local copies once uploaded to UltraCart.Treat the P12 password like any other credential — do not share it or store it in plain text.
Generate separate keys for the Test and Production environments.
Rotate your security key periodically, and immediately if you suspect it has been exposed.
Troubleshooting
Key Cannot Be Opened / Password Error
Symptoms: Transactions fail with an authentication error, or UltraCart reports it cannot read the uploaded key.
Solution:
Confirm the CyberSource P12 Password in UltraCart exactly matches the password you set when downloading the
.p12(Step 1, no leading or trailing spaces).Re-upload the
.p12file to be sure the correct file was selected.
Environment Mismatch
Symptoms: Credentials appear correct, but every transaction is rejected.
Solution: Confirm the key was generated in the same environment you are processing in. A Test key will not authenticate against Production, and vice versa. Generate a new key in the correct environment if needed.
Card Type Declined
Symptoms: A specific card type (for example, JCB or Diners Club) is declined at checkout.
Solution:
Confirm the card type is checked under Methods in the UltraCart gateway configuration.
Confirm your CyberSource merchant account is approved to process that card type.
Currency Mismatch
Symptoms: Multi-currency orders fail.
Solution: Confirm your CyberSource account is enabled for the currencies you are charging, and review the UltraCart order logs for the gateway response.
FAQ
Q: Do I still need Java to generate the key?
No. The older CyberSource console generated keys with a Java applet. The current CyberSource Business Center generates and downloads the .p12 file directly — no Java required.
Q: Which API does UltraCart use?
UltraCart uses the CyberSource Simple Order API. When generating your key, be sure to select Simple Order API as the key type.
Q: Where do I set the P12 password?
You set it in the CyberSource Business Center when you download the key (Step 1). You then enter that same password into the CyberSource P12 Password field in UltraCart.
Q: Do I need separate keys for testing and going live?
Yes. Generate a key in the Test Business Center for testing and a separate key in the Production Business Center for live transactions. The selected key must match the environment you are processing in.