Skip to content

Fraud Detection

Use Finix's Fraud Detection API to minimize chargeback losses on your e-commerce sales by detecting and stopping potentially fraudulent transactions performed by bad actors.

To use the Fraud Detection API, Finix needs to know how your buyers interact with your website (e.g., visited pages, devices used, etc.).

We can collect this data automatically if you add Finix's JavaScript library to your customer-facing website, where you collect orders from your buyers.

This JavaScript library is the same library that lets you secure sensitive credit and debit card data. For more info on securing card data, see Tokenization Forms.

Step 1: Add the Finix JavaScript Library

First, add the Finix JavaScript library to your customer-facing website by including this script in your website:

Finix JS Library
<script
    type="text/javascript"
    src="https://js.finix.com/v/1/finix.js"
    async
></script>

Step 2: Initialize the Finix Auth Service

Initialize the Finix Auth service by providing an environment and a Merchant ID.

The callback parameter triggers once the library has finished initializing and passes the unique session key to the callback function.

Initialize Finix Auth
// without optional callback
const FinixAuth = window.Finix.Auth("sandbox", "MUeDVrf2ahuKc9Eg5TeZugvs");

// with optional callback
const FinixAuth = window.Finix.Auth(
    "sandbox",
    "MUeDVrf2ahuKc9Eg5TeZugvs",
    (sessionKey) => {
        console.log(sessionKey);
    }
);

Request Arguments

FieldTypeDescription
environmentString, requiredThe environment you wish to communicate with. These options are strictly scoped to sandbox and live. Providing an improper environment string will default to using sandbox.
merchant_idString, requiredThe Finix Merchant.id that you want to enable tracking for.
callbackString, optionalA callback function that's called after initialization. It returns the unique session key.

Step 3: Get the Session ID

Once the Finix JavaScript library initializes, use the Finix Auth getSession() function to return the unique session ID:

Get Finix Auth Session
const sessionKey = FinixAuth.getSessionKey();

Step 4: Send Session ID in Payment

After a buyer enters their credit card information and completes checkout, send the session ID to your backend server so the server can include the session ID in fraud_session_id while creating the Authorization or Transfer.

With the fraud_session_id, Finix can use payment details (e.g., card number, amount, etc.) and the buyer’s checkout session to detect and block potentially fraudulent payments.

In other words, including the fraud_session_id helps Finix review information about the buyer, such as IP address and web browser, to confirm if fraud occurred during that specific checkout session.

  • The fraud_session_id only needs to be sent once while creating the first Authorization or Transfer that debits the relevant Payment Instrument.
  • To review a checkout session for fraud without debiting a Payment Instrument, create a $0 Authorization with the relevant Payment Instrument and fraud_session_id.

We recommend passing a new Session ID when your users start a new checkout session on your website. For example, we recommend passing a new Session ID when a buyer:

  • Leaves your site after the first Authorization or Transfer and returns after some time has passed (days, weeks, months, etc.).
  • Begins a new checkout session from a new browser, a different machine, or a new location.

Create a Sale with Fraud Detection

Transfer Request
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
        "amount": 100,
        "currency": "USD",
        "fraud_session_id": "test_fraud",
        "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
        "source": "PIe2YvpcjvoVJ6PzoRPBK137",
        "tags": {
            "test": "sale"
        }
    }'

Create an Authorization with Fraud Detection

In the request body, include the Session ID as the fraud_session_id.

Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/authorizations \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "amount": 100,
    "currency": "USD",
    "fraud_session_id": "test_fraud",
    "merchant": "MU7noQ1wdgdAeAfymw2rfBMq",
    "source": "PIkxmtueemLD6dN9ZoWGHT44"
  }'

Responses

No Fraud Detected - Authorization Created

If no fraud is detected for the session, the API returns a 201 Created status code, with the response body containing the newly created Authorization resource.

Blocked Transaction

If fraud is detected, the transaction will be blocked, and the API will return a PAYMENT_DECLINED response.

Managing Different Sellers

To monitor and manage a different seller, call the Finix Auth connect function and pass in the new Merchant ID.

This initializes the tracking system again and generates a new unique session key for that specific Merchant ID.

The connect function has an additional parameter that accepts a callback function. Once the new session key has been initialized, callback passes the unique session key to the callback function.

Connect Function
// without optional callback
FinixAuth.connect("MUeDVrf2ahuKc9Eg5TeZugvs");

// with optional callback
FinixAuth.connect("MUeDVrf2ahuKc9Eg5TeZugvs", (sessionKey) => {
    console.log(sessionKey);
});

Request Arguments

FieldTypeDescription
callbackString, optionalA callback function that's called after initialization and returns the unique session key.
merchant_idString, requiredThe Finix Merchant.id that you want to enable tracking for.

Blocked Fraud Transactions

When a transaction is blocked, you'll receive a FRAUD_DETECTED response.

Blocked Fraud Sale

This will be the Transfer response format for a Sale that was declined.

Failed Transfer
{
    "id": "TRqRN65R8YEpZnHaSC3qnQYD",
    "created_at": "2024-02-22T21:10:20.61Z",
    "updated_at": "2024-02-22T21:10:21.29Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 400,
    "amount_requested": 400,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "destination": null,
    "externally_funded": "UNKNOWN",
    "failure_code": "FRAUD_DETECTED", 
    "failure_message": "The transaction was declined for suspected fraud. Please ask the buyer to use a different account.", 
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MU7cXuKj2xx41hhZZi6bZ13A",
    "merchant_identity": "IDvHGrfeVmB3i7uL78xjemNk",
    "messages": ["Fraud detection has blocked the Transfer."],
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PI6cFmCphAEwirmGanPL7m6S",
    "split_transfers": [],
    "state": "FAILED", 
    "statement_descriptor": "FNX*FINIX FLOWERS",
    "subtype": "API",
    "tags": {},
    "trace_id": "b753ec53-6c04-40a2-ab20-438ce9994c1d",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqRN65R8YEpZnHaSC3qnQYD"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHGrfeVmB3i7uL78xjemNk"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqRN65R8YEpZnHaSC3qnQYD/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqRN65R8YEpZnHaSC3qnQYD/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqRN65R8YEpZnHaSC3qnQYD/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRqRN65R8YEpZnHaSC3qnQYD/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI6cFmCphAEwirmGanPL7m6S"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

Our API may also return an error depending on where in the payment layer the Fraud was detected.

Transfer Error
{
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "logref": "2052140766f14dec",
                "code": "DECLINED", 
                "failure_code": "FRAUD_DETECTED", 
                "failure_message": "The transaction was declined for suspected fraud. Please ask the buyer to use a different account.",
                "_links": {
                    "self": {
                        "href": "https://finix.sandbox-payments-api.com/transfers"
                    },
                    "transfer": {
                        "href": "https://finix.sandbox-payments-api.com/transfers/TR3tfQZg4KFWo5Zp8X2SuH7g"
                    }
                }
            }
        ]
    }
}

Blocked Fraud Authorization

Failed Authorization
{
    "id": "AUeC3Ybeq6HUJRgNHqJ5RGXD",
    "created_at": "2024-02-22T21:40:34.11Z",
    "updated_at": "2024-02-22T21:40:34.11Z",
    "3ds_redirect_url": null,
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
    "amount": 100,
    "amount_requested": 100,
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "expires_at": "2024-02-29T21:40:34.11Z",
    "failure_code": "FRAUD_DETECTED", 
    "failure_message": "The transaction was declined for suspected fraud. Please ask the buyer to use a different account.",
    "idempotency_id": null,
    "is_void": false,
    "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg",
    "messages": ["Fraud detection has blocked the Transfer."],
    "raw": null,
    "receipt_last_printed_at": null,
    "security_code_verification": "MATCHED",
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "state": "FAILED", 
    "tags": {
        "order_number": "21DFASJSAKAS"
    },
    "trace_id": "c20ced3c-abd8-4fbd-9059-9afecd163eb8",
    "transfer": null,
    "void_state": "UNATTEMPTED",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/authorizations/AUeC3Ybeq6HUJRgNHqJ5RGXD"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        }
    }
}

Our API may also return an error depending on where in the payment layer the Fraud was detected.

Authorization Error
{
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "logref": "2052140766f14dec",
                "code": "DECLINED", 
                "failure_code": "FRAUD_DETECTED", 
                "failure_message": "The transaction was declined for suspected fraud. Please ask the buyer to use a different account.",
                "_links": {
                    "self": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations"
                    },
                    "authorization": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations/AU3tfQZg4KFWo5Zp8X2SuH7g"
                    }
                }
            }
        ]
    }
}