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 users are interacting with your website (e.g., pages visited, 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 with Hosted Fields.

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:

Copy
Copied
<script type="text/javascript" src="https://forms.finixpymnts.com/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.

Copy
Copied
// 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

Field Type Description
environment string, required The environment you wish to communicate with. These options are strictly scoped to: sandbox or live. Providing an improper environment string will default to using the sandbox environment.
merchant_id string, required The Finix Merchant ID that you want to enable tracking for.
callback string, optional A 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:

Copy
Copied
const sessionKey = FinixAuth.getSessionKey();

Step 4: Send Session ID in Payment

After a user 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 browsing and checkout session to detect and block potentially fraudulent payments.

In other words, the fraud_session_id helps Finix review that specific user's browsing activity and 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 user:

  • 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.

4a. Create a Sale with Fraud Detection

Copy
Copied
curl https://finix.sandbox-payments-api.com/transfers \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
    {
        "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
        "currency": "USD",
        "amount": 100,
        "source": "PIe2YvpcjvoVJ6PzoRPBK137",
        "tags": {
            "test": "sale"
        },
        "fraud_session_id": "adasdaxafckasd"
    }'

HTTP Request

POST https://finix.sandbox-payments-api.com/transfers

Request Arguments

Field Type Description
merchant string, required Merchant ID of the merchant whom you're charging on behalf of
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD) processor
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
source string, required ID of the Payment Instrument that will be debited
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
fraud_session_id string, required The session ID you want to review for fraud.

4b. Create an Authorization with Fraud Detection

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations \
    -H "Content-Type: application/vnd.json+api" \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
        {
            "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
            "currency": "USD",
            "amount": 100,
            "source": "PIe2YvpcjvoVJ6PzoRPBK137",
            "tags": {
            "test": "sale"
        },
        "fraud_session_id": "adasdaxafckasd"
    }'

HTTP Request

POST https://finix.sandbox-payments-api.com/authorizations

Request Arguments

Field Type Description
merchant string, required Merchant ID of the merchant whom you're charging on behalf of
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)processor
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
source string, required ID of the Payment Instrument that will be debited
tags object, optional Key value pair for annotating custom metadata (e.g. order numbers)
fraud_session_id string, required The session ID you want to review for fraud.

Managing Different Merchants

To monitor and manage a different merchant, 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.

Copy
Copied
// without optional callback
FinixAuth.connect('MUeDVrf2ahuKc9Eg5TeZugvs');
 
// with optional callback
FinixAuth.connect('MUeDVrf2ahuKc9Eg5TeZugvs', (sessionKey) => {
  console.log(sessionKey);
});

Request Arguments

Field Type Description
merchant_id string, required The Finix Merchant ID that you want to enable tracking for.
callback string, optional A callback function that's called after initialization and returns the unique session key.

Blocked Fraud Transactions

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

Blocked Fraud Sale

Copy
Copied
{
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "logref": "2052140766f14dec",
                "message": "Transfer TR3tfQZg4KFWo5Zp8X2SuH7g was declined. Cause: fraud has recommended to block the transaction",
                "code": "PAYMENT_DECLINED",
                "_links": {
                    "self": {
                        "href": "https://finix.sandbox-payments-api.com/transfers"
                    },
                    "transfer": {
                        "href": "https://finix.sandbox-payments-api.com/transfers/TR3tfQZg4KFWo5Zp8X2SuH7g"
                    }
                }
            }
        ]
    }
}

Blocked Fraud Authorization

Copy
Copied
{
    "total": 1,
    "_embedded": {
        "errors": [
            {
                "logref": "2052140766f14dec",
                "message": "Authorization AU3tfQZg4KFWo5Zp8X2SuH7g was declined. Cause: fraud has recommended to block the transaction",
                "code": "PAYMENT_DECLINED",
                "_links": {
                    "self": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations"
                    },
                    "authorization": {
                        "href": "https://finix.sandbox-payments-api.com/authorizations/AU3tfQZg4KFWo5Zp8X2SuH7g"
                    }
                }
            }
        ]
    }
}