Skip to content

Cybersource

Screen card payments with Cybersource Decision Manager before they're authorised.

Cybersource Decision Manager screens card payments before Ginger sends them to the processor. Read Fraud prevention first: it explains when the check runs and what happens when Cybersource declines a payment or doesn't respond.

Before you begin

  • A Cybersource account with Decision Manager: the organisation ID, the device fingerprint organisation ID, an API key and its shared secret. Test credentials for test orders, if you have them.
  • The names of the Decision Manager profiles you want to use, if any.
  • Access to Platform settings in the Admin portal, and an admin API key or user to update projects with the Boarding API.

Add the integration to your platform

Add Cybersource

In the Admin portal, go to Platform settings › Risk & Fraud and select Add Integration. Choose Cybersource, enter the organisation ID, the fingerprint organisation ID, the API key and the shared secret, and their test counterparts. Set the status to enabled.

Choose how strict it is

SettingWhat it does
decline_transaction_if_integration_is_unavailableDecline the payment when Cybersource returns an error or no decision. Off: the payment continues without a decision.
report_onlyRun the check and record the result on the transaction, but never decline a payment. Use it to tune your Decision Manager rules on live traffic first.

Configure the project

Set fraud_prevention_integration to cybersource on every project that Cybersource should screen. Set fraud_prevention_risk_profile to the name of a Decision Manager profile to have that profile decide on the project's payments. Ask your Ginger contact which profile decides when you leave it out. Only an admin can set these fields: use the admin path of the Boarding API.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "trade_name": "Acme Coffee",
    "description": "Acme Coffee webshop",
    "status": "active-production",
    "website_url": "https://www.example.com/",
    "fraud_prevention_integration": "cybersource",
    "fraud_prevention_risk_profile": "low"
  }'

An update of the project needs its trade_name, description, status and website_url too. See Update a project in the API reference.

Merchant-defined data

Ginger sends five merchant-defined data fields with every check. Cybersource doesn't show a name for them, only a number. This is what they hold:

Field in CybersourceValue
Merchant Defined Data 1The Ginger merchant ID
Merchant Defined Data 2The Ginger project ID
Merchant Defined Data 3The external merchant ID, if set
Merchant Defined Data 4The external project ID, if set
Merchant Defined Data 5The last four digits of the card number

Use them in Decision Manager rules and case management, for example to find all payments of one merchant.

Next steps