# 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](/guides/online-payments/payment-tokenization/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: ```javascript Finix JS Library ``` ## 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. ```javascript 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 | Field | Type | Description | | --- | --- | --- | | `environment` | String, required | The 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_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: ```javascript 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 ```shell 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", // [!code highlight] "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "tags": { "test": "sale" } }' ``` - A successful request will return the newly created [`Transfer` resource](/api/transfers/createtransfer). - A blocked transaction will return a [`PAYMENT_DECLINED` response](/guides/online-payments/fraud-and-risk/fraud-detection#blocked-fraud-transactions). ### Create an Authorization with Fraud Detection In the request body, include the [Session ID](/guides/online-payments/fraud-and-risk/fraud-detection#step-3-get-the-session-id) as the `fraud_session_id`. #### Request Example API Definition #### 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](/api/authorizations/createauthorization#authorizations/createauthorization/response&c=201/body). Blocked Transaction If fraud is detected, the transaction will be blocked, and the API will return a [`PAYMENT_DECLINED` response](/guides/online-payments/fraud-and-risk/fraud-detection#blocked-fraud-authorization). ## 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. ```javascript Connect Function // 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. ```json 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", // [!code highlight] "failure_message": "The transaction was declined for suspected fraud. Please ask the buyer to use a different account.", // [!code highlight] "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", // [!code highlight] "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. ```json Transfer Error { "total": 1, "_embedded": { "errors": [ { "logref": "2052140766f14dec", "code": "DECLINED", // [!code highlight] "failure_code": "FRAUD_DETECTED", // [!code highlight] "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 ```json 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", // [!code highlight] "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", // [!code highlight] "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. ```json Authorization Error { "total": 1, "_embedded": { "errors": [ { "logref": "2052140766f14dec", "code": "DECLINED", // [!code highlight] "failure_code": "FRAUD_DETECTED", // [!code highlight] "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" } } } ] } } ```