Fraud Detection

Use our Fraud Detection API to stop fraudulent transactions.


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 Payment 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:

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

4a. Create a Sale with Fraud Detection

Copy
Copied
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"
        }
    }'

HTTP Request

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

Request Arguments

Field Type Description
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD) processor
fraud_session_id string, required The session ID you want to review for fraud.
merchant string, required Merchant ID of the merchant whom you're charging on behalf of
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)

4b. Create an Authorization with Fraud Detection

Copy
Copied
curl https://finix.sandbox-payments-api.com/authorizations \
    -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"
        }
    }'

HTTP Request

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

Request Arguments

Field Type Description
amount integer, required The total amount that will be debited in cents (e.g. 100 cents to debit $1.00)
currency string, required 3-letter ISO code designating the currency of the Transfers (e.g. USD)processor
fraud_session_id string, required The session ID you want to review for fraud.
merchant string, required Merchant ID of the merchant whom you're charging on behalf of
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)

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.

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

Request Arguments

Field Type Description
callback string, optional A callback function that's called after initialization and returns the unique session key.
merchant_id string, required The 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.

Copy
Copied
    {
        "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.

Copy
Copied
{
    "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

Copy
Copied
{
  "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.

Copy
Copied
{
    "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"
                    }
                }
            }
        ]
    }
}