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

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

A successful request will return the newly created Transfer resource .
A blocked transaction will return a PAYMENT_DECLINED response .

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

A successful request will return the newly created Authorization resource .
A blocked transaction will return a PAYMENT_DECLINED response .

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"
                    }
                }
            }
        ]
    }
}