---- dataentry gateway ----
type                             : gateway # do not change this line
name                             : Cybersource
countries                        : US, GB, JP
support-added                    : 0.3.0
support-removed                  : 
supports-3dsecure                : yes
supports-multicurrency           :  # enter "yes" or "no" (without quotes)
supports-transaction-id-override : yes
gateway_url                      : http://www.cybersource.com/
----




====== Cybersource ======
===== Setting Up Cybersource for FoxyCart =====
These are instructions for setting up your Cybersource gateway on a Live store. If you don't have a FoxyCart store subscription, you can start one by going to **Settings—>Billing** in the admin dashboard and clicking the **I'm ready to take my store live** link and follow the prompts.

  - Set up your CyberSource account - [[http://www.cybersource.com/register/]]
  - Login in to your Cybersource account [[https://businesscenter.cybersource.com/ebc2/]]
  - In the dashboard, under **Security Keys**, click **Generate new key**.
  - Select **REST - Shared Secret**
  - Scroll down and click **Generate Key**
  - You will see the key generated. Copy out the **Key** and **Shared Secret** for entry into the Foxy admin, and securely store it if desired as it won't be shown again.
  - Log into your Foxy admin (https://admin.foxy.io) and go to **Settings—>Payments** and click the Payment Method Set you wish to use for Cybersource. A box should pop up.
  - If the gateway is not already set to Live mode, toggle the switch for **Use live credentials**. If it's disabled you'll need to start your FoxyCart subscription by closing the current window and selecting Billing (under Settings) and click the **I'm ready to take my store live** link (you can then come back and start over at the **Settings—>Payments** step).
  - Click **Add payment method** and select **Cybersource REST**.
  - Enter the **Merchant ID**, **Key**, and **Shared Secret** that you generated from the Cybersource site, turn on tokenization if you are using it, then click **Create** to save the new gateway.
  - If your store needs to verify that the credit card is valid for certain amounts, please [https://foxy.io/contact|contact] our support team about how to set that up.
  - Click the **Save** button.
  - Go back to your CyberSource account. Click "Account Management" -> "SmartAuth Settings". Set your checkboxes to look like this:\\ {{:docs:paymentgateways:cybersource-smartauth-settings-cvv2.png|CyberSource CVN settings}}
    * UK users skip the above step. CVN is not available and is covered by the Decision Manager settings. \\ {{:docs:paymentgateways:cybersource_business_center_-_global_velocity_settings.jpg?200|Decision Manager Settings}}
    * Cybersource by default has already put in place basic fraud screening via the Decision Manager even in the basic set up package.
    * Don't worry. FoxyCart always sends the CVN //unless// the customer is using a saved card (or it's processing a subscription). This is very common; the first transaction between your store and your customer validates using the CVN, but subsequent transactions validate using other services (like address verification).
  - **TEST.** Your account may already be in test mode. Contact CyberSource support to make sure everything's ready to go.
  - **TEST MORE.** Test with a real credit card and make sure everything (all the way up to the money actually getting deposited into your merchant account) works as expected.
<note important>**NOTE:** Using a test card on a live account will generate account configuration errors. We're noting that here because this is unusual behavior. (Typically the cards would just be rejected with a normal "declined"-style error message.)</note>

===== Payment Tokenization =====

In order to have an ability to charge a customer again you need to create a customer profile at CyberSource.

You will get the subscription ID as ''paySubscriptionCreateReply__subscriptionID'' in your data feed application.
The customer profile will be created at CyberSource so you can access it using [[https://ebc.cybersource.com/|CyberSource Business Center]].

==== Activation ====
=== Version 1.1 ===
  - Choose **Cybersource.com (Payment Tokenization)** as your payment gateway.
  - Activate the option "Payment Token Required".

=== Version 2.0+ ===
  - Choose **Cybersource.com** as your payment gateway.
  - Activate the option "Payment Token Required".


===== Overriding the Merchant Reference Number =====
As of Foxy v2.0, the "Merchant Reference Number" that Foxy passes to CyberSource (which is normally the Foxy transaction ID) can be overridden. This is considered advanced functionality, and is only relevant for very specific use cases (such as complex fulfillment processes where multiple authorizations and captures may need to be grouped by the Merchant Reference Number).

To override the default Foxy transaction ID, add [[https://api.foxycart.com/rels/attributes|an ''attribute'' via the API]] named ''fx_transaction_id_gateway_override'', to the ''cart'' resource. The value of that attribute will be passed to CyberSource as the Merchant Reference Number (aka Merchant Reference Code).

For reference, here's the field in the CyberSource portal:
{{ :gateways:cybersource-merchant-reference-code-override.png?400 |An image showing the CyberSource admin with the Merchant Reference Number column header circled.}}
===== Testing =====
==== Obtaining a Test Account ====
  * [[http://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_IG/html/testing.htm|CyberSource testing documentation]]
  * [[http://www.cybersource.com/support_center/support_documentation/quick_references/|CyberSource Quick References]]

==== Test Card Numbers ====
  * [[http://www.cybersource.com/developers/develop/cybersource_services/quick_references/test_cc_numbers/|CyberSource test credit card numbers]]
  * [[http://www.cybersource.com/developers/getting_started/test_and_manage/simple_order_api/|Simulating error responses]] by using specific order total amounts


===== Important Notes and Caveats =====
Cybersource limits the number of characters we can send in the requests for payment, while Foxy's character limits on the checkout are more permissive. Therefore, when the customer fills out the checkout form, some of the information may be cut off or special characters removed before sending to Cybersource. Note though that <wrap tip>the original data remains in Foxy</wrap>. Our opinion is that it's more important to allow the customer to checkout (with data intact in Foxy) than to reject on an error because the customer put "ext" instead of "x" in their phone field, or included a disallowed character in their company name field.

If you wish to validate the checkout data entry instead of automatically replacing and/or truncating input values, you can do so using [[v:2.0:checkout#adding_custom_validation_to_your_checkout|JavaScript validation]]. 

===== User Notes and Experiences =====
<wrap tip>If you have tips, experience, or helpful notes related to this gateway that would benefit others, please add them below, including your name and the date. We at FoxyCart reserve the right to edit or remove comments that don't add value to this page.</wrap>