Cybersource
Configure Cybersource Decision Manager as a DEUNA anti-fraud engine, map risk decisions and custom fields, and validate the integration before production.
On this page
- Understand how Cybersource works with DEUNA
- Prerequisites
- 1. Set up the test environment in Cybersource
- 2. Configure device fingerprinting
- 3. Connect Cybersource in DEUNA Admin
- 4. Map Merchant custom fields (MDDs) in DEUNA
- 5. Add Cybersource to your payment strategy
- 6. Use REVIEW as a 3DS recommendation
- 7. Test the integration
- 8. Deploy to production
Cybersource Decision Manager returns an ACCEPT, REVIEW, or REJECT decision and a risk score from 0 to 99. DEUNA maps these results to its standard Low, Medium, and High risk tiers. This guide takes you from a Cybersource account to an active anti-fraud engine in eight steps.
Understand how Cybersource works with DEUNA#
Cybersource, a Visa solution, provides Decision Manager, a global fraud-management platform that uses insights from transactions across major card brands.
Capabilities
- Visa global data network: Uses cross-merchant and cross-industry data to detect fraudulent patterns.
- Advanced rules engine and machine learning: Combines merchant-specific business rules with machine-learning models.
- Device fingerprinting and IP geolocation: Analyzes device, network, and location data to flag spoofing, proxies, and known fraudulent devices.
- Omnichannel protection: Applies one fraud policy across web, mobile, in-app, and call-center transactions.
DEUNA standardizes Decision Manager decisions and scores as follows:
ACCEPTmaps to Low Risk, and the transaction is processed immediately.REVIEWmaps to Medium Risk, and DEUNA triggers a 3-D Secure (3DS) step-up, waits for manual review in Cybersource, or both, depending on your configuration.REJECTmaps to High Risk, and the transaction is halted.
These are the default mappings. You can customize what triggers each tier to match your risk appetite.
| Cybersource response | DEUNA risk level | Default routing strategy |
|---|---|---|
Decision ACCEPT and score 0-9 | 🟢 Low Risk | Process through the preferred gateway. |
Decision REVIEW and score 10-79 | 🟡 Medium Risk | Wait for manual review, trigger 3DS, or both. |
Decision REJECT and score 80-99 | 🔴 High Risk | Deny the transaction or route it to a specialized high-risk gateway. |
Prerequisites#
You need an active Cybersource account with Decision Manager and a DEUNA Admin account with access to the test environment. Gather these values before you start:
| Source | Item | Used in |
|---|---|---|
| Cybersource | Key | Step 3 |
| Cybersource | Merchant ID | Steps 2 and 3 |
| Cybersource | Shared secret | Step 3 |
| Cybersource | Control Panel username, password, and organization name | Step 1 |
| DEUNA | Admin access to the test environment | Steps 3-7 |
1. Set up the test environment in Cybersource#
Complete this step in the Cybersource test Control Panel.
Create test users
- Go to Accounts and select Users.
- Select Create user.
- Create the users needed for testing.
Create simulation lists
Decision lists let you force an outcome by email address.
- Go to Decision Manager > Shared Configuration > Custom Lists.
- Create three lists:
- Positive list: Emails that must always be accepted.
- Review list: Emails that must go to manual review.
- Negative list: Emails that must always be rejected.
- Add the test emails used in Test the integration to the corresponding lists.
:::info Mercado Pago tests
The following testuser.com addresses are also accepted and are required for Mercado Pago tests:
test_aprove@testuser.comfor the positive listtest_review@testuser.comfor the review listtest_reject@testuser.comfor the negative list :::
Create a profile
- Go to Decision Manager > Configuration > Profiles.
- Add a profile with centralized rules.
A preselected profile named A-Test is usually available and can be used instead.
Create and configure decision rules
Create one rule for each outcome:
- Go to Decision Manager > Configuration > Custom Rules.
- Select Add Rule.
- Configure the rules as follows:
| Field | Accept | Reject | Review |
|---|---|---|---|
| Rule Name | Accept Always | Reject Always | Review Always |
| Description | Accept Always | Reject Always | Review Always |
| Category | Other Tests | Other Tests | Other Tests |
| Core Rule | Selected | Selected | Selected |
| Decision | Accept | Reject | Review |
| Execution Timing | Before Auth | Before Auth | Before Auth |
| This rule is true if | All conditions true | All conditions true | All conditions true |
| Order Element | Email address | Email address | Email address |
| Comparison Op | is equal to | is equal to | is equal to |
| Comparison val | Positive List | Negative List | Review List |
- Return to Custom Rules, select Edit Rule for each rule, and configure its profile behavior:
| Field | Accept | Reject | Review |
|---|---|---|---|
| Monitor | |||
| Accept | Selected | ||
| Review | Selected | ||
| Reject | Selected | ||
| Priority | 1 | 1 | 1 |
| Execution Timing | Before Auth | Before Auth | Before Auth |
- Select Update.
Configure the manual-review notification URL
Cybersource uses this URL to send manual-review decisions to DEUNA.
- Go to Decision Manager > Configuration > Extended settings > Developer settings.
- Turn on Enable order status notification.
- In Notification URL to receive notification, enter
https://api.sandbox.deuna.io/post-transactions/cybersource. - Select TEST URL.
- Under Notify for, select Reviewer decisions.
- Select UPDATE SETTINGS.
Create custom fields
Merchant-defined data (MDD) fields send order context to Decision Manager.
- Go to Decision Manager > Shared Configuration > Custom Fields.
- Select Add Custom Field.
- Create the fields that your rules use:
| MDD | Name | Type | Description | Example |
|---|---|---|---|---|
| 1 | Business Line | string | Pharmacy, restaurant, retail, or another line of business | |
| 2 | Merchant | string | Merchant name | |
| 3 | Customer First Name | string | First name or names, without last names | Mario Alejandro |
| 4 | Customer Last Name | string | Last name or names | Hernandez Gutierrez |
| 5 | Customer State | string | State | Tabasco |
| 6 | Customer City or Municipality | string | Delegation or municipality | Centro |
| 7 | Customer Neighborhood/Locality | string | Neighborhood or settlement | Atasta |
| 8 | Customer Street and Number/Floor | string | Street and number, including the floor for buildings or interiors | Cerrada de Revolucion 377 |
| 11 | Customer Postal Code | string | Postal code | 86100 |
| 12 | Customer Mobile Phone | number | Mobile phone number | 529932065236 |
| 13 | Store Registration Month | string | Month when the customer registered in the store | January |
| 17 | Store Registration Year | number | Year when the customer registered in the store | 2022 |
| 18 | Guest or registered? | string | YES for a guest or NO for a registered customer | NO |
| 19 | Customer Registration Time | number | Number of days the customer has been registered | 90 |
| 21 | Items Purchased-Num Items | number | Number of items in the cart | 1 |
| 22 | Most Expensive Item SKU | string | Most expensive model in the cart | ROLEX 231 |
| 25 | Interest-free months purchase? | string | YES for interest-free installments or NO otherwise | NO |
| 26 | How many interest-free months? | number | Number of months; use 0 for a single payment | 3 |
| 28 | Discount Percentage | number | Discount percentage on the total purchase | 0.2 |
| 29 | Discount code used? | string | YES when a promotional code was used or NO otherwise | NO |
| 31 | Loyalty points used? | string | YES when points were used or NO otherwise; the value must come from the merchant's web or checkout | NO |
| 32 | Delivery First Name | string | First name or names | Alejandro Daniel |
| 34 | Delivery Last Name | string | Last name or names | Valle Haya |
| 35 | Delivery State | string | Delivery state | Tabasco |
| 36 | Delivery City or Municipality | string | Delivery delegation or municipality | Centro |
| 37 | Delivery Neighborhood/Locality | string | Delivery neighborhood or settlement | Atasta |
| 39 | Delivery Street and Number/Floor | string | Delivery street and number, including the floor | Cerrada de Revolucion 377 |
| 40 | Delivery Postal Code | string | Delivery postal code | 86100 |
| 41 | Delivery Mobile Phone | string | Mobile phone number | 529932065236 |
| 43 | Delivery Date | date | Date in DD-MM-YYYY format | 30-11-2023 |
| 44 | Sales Channel | string | Web, mobile, call center, or another channel | web |
| 45 | Merchant Affiliation | string | Unique merchant ID provided by the acquiring bank | |
| 46 | Order Day of Week | string | Purchase day | Monday |
| 47-62 | Product 1-8: Brand and Model (subbrand) | string | Brand in odd-numbered fields 47-61 and model in even-numbered fields 48-62 | ROLEX / 231 |
2. Configure device fingerprinting#
The device fingerprint is generated by a script that runs during checkout. It lets Cybersource identify the customer's device. The setup depends on how you connect to DEUNA.
- For the Payment Widget or a payment link, follow the Payment Widget instructions.
- For Direct API, follow the Direct API instructions.
- Add Cybersource to the
providersobject:
CYBERSOURCE: {
cs_orgId: '<org_id>',
cs_merchantId: '<merchant_id>'
}Use the following values:
| Variable | Description | Sandbox | Production |
|---|---|---|---|
cs_orgId (org_id) | Cybersource organization ID; it changes by environment | 1snn5n9w | k8vif92e |
cs_merchantId (merchant ID) | Assigned by Cybersource for each store | Your merchant ID | Your merchant ID |
- For API integrations, send the output to DEUNA in
anti_fraud_info.device.idwhen you create the payment.
3. Connect Cybersource in DEUNA Admin#
Complete this setup once per environment.
- In DEUNA Admin, turn on Test mode.
- Go to Connections, search for Cybersource, and select Connect.
- Enter the credentials and settings:
| Field | Value |
|---|---|
| Key | Key provided by Cybersource |
| Merchant ID | Your Cybersource merchant ID |
| Shared Secret | Shared secret provided by Cybersource |
| Environment (test, live) | test for sandbox or live for production |
| Use "Review" status for 3DS (Yes or No) | No, unless a REVIEW result should trigger 3DS; see Use REVIEW as a 3DS recommendation |
| Deactivate "ShipTo" object (Yes or No) | Yes to remove ShipTo from the data sent to Cybersource; leave it empty or enter No to send ShipTo |
- Select Connect.
Cybersource appears as a connected anti-fraud engine in the Connections list.
Connections
Discover and manage payment, wallet, and anti-fraud integrations.
| Connections | Type | Status | Action |
|---|---|---|---|
| Adyen | Payment gateway | Connected | |
| Worldpay | Payment gateway | Connected | |
| PayPal | Payment method | Connected | |
| Mercado Pago | Payment method | Not connected | |
| Riskified | Anti-fraud engine | Not connected |
:::info Manual review To hold Medium Risk orders for manual review, ask your DEUNA Technical Account Manager to confirm that manual review and automatic operation execution are enabled for the store and environment. :::
4. Map Merchant custom fields (MDDs) in DEUNA#
After creating the MDDs in Cybersource, map the corresponding order data to each MDD number. The mapping is stored in the merchant profile under merchant_custom_information.
Available sources include the billing_address, shipping_address, and items objects, metadata fields, constant values, and calculated values.
Set constant values
Use merchant_information for values that do not change between orders:
curl --location --request PUT 'https://api.stg.deuna.io/merchant/<merchant_id>/profile' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"merchant_information": {
"business_line": "ecommerce"
}
}'const response = await fetch("https://api.stg.deuna.io/merchant/<merchant_id>/profile", {
method: "PUT",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
},
body: JSON.stringify({
"merchant_information": {
"business_line": "ecommerce"
}
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"PUT",
"https://api.stg.deuna.io/merchant/<merchant_id>/profile",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
},
json={
"merchant_information": {
"business_line": "ecommerce"
}
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.stg.deuna.io/merchant/<merchant_id>/profile",
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer <YOUR_ACCESS_TOKEN>"
],
CURLOPT_POSTFIELDS => json_encode([
"merchant_information" => [
"business_line" => "ecommerce"
]
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.stg.deuna.io/merchant/<merchant_id>/profile"))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer <YOUR_ACCESS_TOKEN>")
.method("PUT", HttpRequest.BodyPublishers.ofString("{\n \"merchant_information\": {\n \"business_line\": \"ecommerce\"\n }\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("PUT", "https://api.stg.deuna.io/merchant/<merchant_id>/profile", strings.NewReader("{\n \"merchant_information\": {\n \"business_line\": \"ecommerce\"\n }\n }"))
if err != nil { panic(err) }
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Authorization", "Bearer <YOUR_ACCESS_TOKEN>")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}Declare the MDD mapping
Send a second PUT request to the same endpoint. Each key is a DEUNA field, and each value is the corresponding Cybersource MDD number.
:::info Replacement behavior
The request replaces the stored merchant_custom_information value. Always send the complete object, not only the fields you changed.
:::
{
"merchant_custom_information": {
"installments": "37",
"items_0_title": "22",
"items_1_brand": "25",
"items_1_title": "26",
"billing_address": {
"city": "4",
"phone": "8",
"zipcode": "7",
"address2": "5",
"last_name": "2",
"first_name": "1",
"state_name": "3"
},
"shipping_amount": "9",
"shipping_address": {
"city": "46",
"phone": "50",
"zipcode": "49",
"address2": "47",
"last_name": "44",
"first_name": "43",
"state_name": "45"
},
"payment_method": {
"network_token_data": {
"source": "97"
}
},
"is_coupon_applied": "40",
"is_installments_msi": "36",
"get_total_quantity_products": "18",
"get_max_unit_price_product_name": "19"
}
}Item fields follow the pattern items_<n>_title, items_<n>_brand, and items_<n>_description, where <n> is the item position starting at 0.
:::info APM and wallet orders For orders paid with APMs and wallets such as Google Pay or Apple Pay, it is very important to map this information as an MDD.
{
"payment_method": {
"network_token_data": {
"source": "50"
}
}
}:::
Map calculated values
You can map the following DEUNA-calculated keys to an MDD:
| Key | Description | Example |
|---|---|---|
is_coupon_applied | YES when a promotional code was used or NO otherwise | NO |
is_installments_msi | YES for interest-free installments or NO otherwise | NO |
get_spanish_day_of_week | Order day of the week | Monday |
get_full_billing_address | Billing street and number, including the floor for buildings or interiors | Cerrada de Revolucion 377 |
get_full_shipping_address | Delivery street and number, including the floor | Cerrada de Revolucion 377 |
get_channel_from_user_agent | Sales channel, such as web, mobile, or call center; read from the user agent for web and mobile | web |
get_total_quantity_products | Number of items in the cart | 1 |
get_total_discount_percentage | Discount percentage on the total purchase | 0.2 |
get_full_name_shipping_address | Concatenated first and last name from the shipping address | Diego Lora |
get_full_name_billing_address | Concatenated first and last name from the billing address | Santiago Yepes |
get_full_name_billing_address_uppercase | Billing full name in uppercase | SANTIAGO YEPES |
get_max_unit_price_product_name | Name of the most expensive item in the cart | ROLEX 231 |
Send and map metadata fields
To send your own fields as MDDs:
- Send the fields in the order's
metadataobject using theadditional_data.prefix:
{
"metadata": {
"additional_data.account_name": "Nelson",
"additional_data.identity_type": "DNI"
}
}- Map each field to its MDD number under
merchant_custom_information.metadata. You can combine metadata with other sources such asmerchant_information,email, andshipping_options:
{
"merchant_custom_information": {
"merchant_information": {
"business_line": "22",
"merchant_identifier": "1"
},
"metadata": {
"additional_data.merchant_terminal": "2",
"additional_data.account_name": "4",
"additional_data.total_discount": "25"
},
"installments": "17",
"billing_address": {
"identification_type": "18",
"identification": "19",
"phone": "21"
},
"email": "20",
"shipping_options": {
"type": "26"
},
"get_full_name_billing_address_uppercase": "31"
}
}Use state and province codes for US and Canada billing
For billing addresses in the United States and Canada, send the state or province as its postal abbreviation:
- United States (USPS):
AL,AK,AS,AZ,AR,CA,CO,CT,DE,DC,FM,FL,GA,GU,HI,ID,IL,IN,IA,KS,KY,LA,ME,MH,MD,MA,MI,MN,MS,MO,MT,NE,NV,NH,NJ,NM,NY,NC,ND,MP,OH,OK,OR,PW,PA,PR,RI,SC,SD,TN,TX,UT,VT,VI,VA,WA,WV,WI,WY. - Canada (Canada Post):
AB,BC,MB,NB,NL,NS,NT,NU,ON,PE,QC,SK,YT.
5. Add Cybersource to your payment strategy#
- Go to Payment strategies.
- Find the rule where Cybersource should run and select Edit.
- Add Cybersource as the anti-fraud provider.
- Enable manual review.
- Enable automatic execution of operations.
- Select Activate.
Payment strategies
Configure default processing and rules for each payment flow.
Default processing
Configure default processing and rules for each payment flow.
| Rule | Routing | Status | Action |
|---|---|---|---|
| Default processing | Adyen → Worldpay | Active |
Specific rules
Configure default processing and rules for each payment flow.
| Priority | Rule | Conditions | Routing | Status |
|---|---|---|---|---|
| 1 | High-value orders | Amount over USD 100 | Adyen → Worldpay | Active |
Before activating the strategy, confirm how Medium Risk transactions should be handled. Depending on your configuration, these transactions are approved by the payment gateway and held for a manual decision in the Cybersource Control Panel, sent through 3DS, or both.
6. Use REVIEW as a 3DS recommendation#
You can optionally use a Cybersource REVIEW result to trigger 3DS instead of manual review.
Configure REVIEW for 3DS
- In the Cybersource connection credentials, enter
Yesfor Use "Review" status for 3DS. - In DEUNA Admin, go to Merchant > Payment settings > General Fraud Settings.
- Turn on Enable Manual Review.
The Enable Manual Review setting must be on even though these orders do not enter a manual-review flow.
Understand the resulting behavior
When Cybersource returns REVIEW, DEUNA runs the 3DS flow instead of starting manual review.
| Stage | Fraud status | Payment status | Update sent to Cybersource |
|---|---|---|---|
Cybersource returns REVIEW; 3DS is in progress | Pending 3DS | Pending | None |
| 3DS completes and the gateway processes the payment | Approved | Authorized, Processing, or Processed | Case changes from Review to Accept |
| 3DS completes and the gateway denies the payment | Denied | Denied by the gateway | Case changes from Review to Reject |
The fraud status remains Pending 3DS and the payment status remains Pending until the 3DS flow finishes and the payment is processed.
After the gateway returns its result, DEUNA notifies Cybersource to change the case from Review to its final status. The message includes the relevant 3DS fields, such as eci, cavv, ds_transaction_id, and par_status.
In sandbox, use review@deuna.com as billing_address.email to trigger REVIEW. When Use "Review" status for 3DS is set to Yes, DEUNA runs 3DS instead of manual review.
7. Test the integration#
- In DEUNA Admin, confirm that Test mode is on.
- Confirm that the Cybersource connection and payment strategy are active.
- Make test transactions using these values:
| Scenario | Field | Value |
|---|---|---|
| Automatic approval | billing_address.email | accept@deuna.com |
| Automatic rejection | billing_address.email | reject@deuna.com |
| Manual review | billing_address.email | review@deuna.com |
The testuser.com addresses from the simulation-list setup are also accepted.
- Open each order in DEUNA Admin and verify the Fraud section:
| Scenario | Expected result |
|---|---|
| Automatic approval | Low risk |
| Automatic rejection | High risk |
| Manual review when manual review is disabled | Medium risk |
| Manual review when manual review is enabled | Approved by the payment gateway and pending a decision in Cybersource |
| Reviewer accepts in Cybersource | Approved |
| Reviewer rejects in Cybersource | Rejected |
Orders
Find a payment, then open its operational context.
| Order ID | Created | Customer | Processor | Amount | Status |
|---|---|---|---|---|---|
| Oct 1, 14:32 | sofia@example.com | Worldpay | $128.40 | Approved | |
| Oct 1, 14:18 | diego@example.com | Adyen | $82.00 | Pending | |
| Oct 1, 13:54 | ana@example.com | Stripe | $246.90 | Declined | |
| Oct 1, 13:41 | marco@example.com | Worldpay | $54.25 | Approved |
Resolve a manual-review case
- Save a payment strategy that sends Medium Risk transactions to manual review.
- In the Cybersource Control Panel, go to Decision Manager > Case Management > Cases.
- Search by date range or test order ID.
- Select the most recent attempt for the order. Each attempt generates a new request ID under the same order ID.
- Accept or reject the transaction.
- Return to DEUNA Admin and confirm that the order status changed.
For United States and Canada billing addresses, use the postal abbreviations listed in Use state and province codes for US and Canada billing.
8. Deploy to production#
Repeat the setup in production using production credentials and values.
Configure Cybersource production
- Sign in to the Cybersource production Control Panel.
- Create a production profile.
- Create the rules for acceptance, rejection, and manual review.
- Recreate the required MDDs.
- Set the notification URL to
https://api.deuna.io/post-transactions/cybersource. - Set the device-fingerprint
cs_orgIdtok8vif92e.
Configure DEUNA production
- Turn off Test mode in DEUNA Admin.
- Go to Connections and connect Cybersource with your production credentials and the
liveenvironment. - Ask your DEUNA Technical Account Manager to confirm that manual review and automatic operation execution are enabled for the production store.
- Configure the payment gateways and activate the production payment strategy.
- Process a Medium Risk transaction to validate manual review or the configured 3DS behavior.