Skip to content

Finix.Auth

Finix.js includes built-in fraud detection through Finix.Auth. It establishes a session that tracks behavioral signals during the buyer's checkout flow. When the buyer submits a payment, you send the session key to your backend, which includes it in the payment request so Finix can score the transaction for fraud.

There are two parts to integrating fraud detection:

  1. Client side — initialize Finix.Auth and retrieve the session key at submit time
  2. Backend side — include fraud_session_id when creating an Authorization or Transfer

Client-side setup

Finix.Auth()

Initialize Finix.Auth before Finix.PaymentForm, at page load. This gives the session time to establish before the buyer submits the form.

Finix.Auth(environment, merchantId, callback)
ParameterTypeRequiredDescription
environmentstringYes"sandbox" or "live"
merchantIdstringYesYour Finix Merchant ID
callbackfunction(sessionKey)NoCalled once initialization completes

Optional callback

Pass a callback to receive the session key as soon as it's available. This is useful if you need the key before the buyer submits the form.

getSessionKey()

Returns the current fraud session key. Call this inside onSubmit — by the time the buyer submits the form, the session will have initialized.

finixAuth.getSessionKey() → string

Sending to your backend

Pass the session key on submit

Inside onSubmit, retrieve the session key and send it to your backend alongside the token. Your backend uses the session key when creating the payment request.

Include fraud_session_id in your payment request

Your backend should include fraud_session_id when creating an Authorization or Transfer with the Finix API. Finix uses the session key to correlate the buyer's checkout behavior with the payment for fraud scoring.

For full details on the backend payment request and how to handle blocked transactions, see the Fraud Detection guide.

Managing multiple merchants

connect()

Call connect() to reinitialize tracking for a different Merchant ID. This generates a new session key for that merchant.

finixAuth.connect(merchantId, callback)
ParameterTypeRequiredDescription
merchantIdstringYesThe Finix Merchant ID to switch tracking to
callbackfunction(sessionKey)NoCalled once the new session key is ready
// Initialize before Finix.PaymentForm so the session is ready by submit time
const finixAuth = Finix.Auth("sandbox", "MUeDVrf2ahuKc9Eg5TeZugvs");

// Optional callback — fires once the session key is available
const finixAuth = Finix.Auth("sandbox", "MUeDVrf2ahuKc9Eg5TeZugvs", function (sessionKey) {
  console.log("Session key:", sessionKey);
});

const sessionKey = finixAuth.getSessionKey();

const finixAuth = Finix.Auth("sandbox", "MUeDVrf2ahuKc9Eg5TeZugvs");

Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
  onSubmit: function (error, response) {
    if (error) {
      console.error("Error:", error);
      return;
    }
    const tokenData = response.data || {};

    fetch("/your/backend", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        token: tokenData.id,
        fraud_session_id: finixAuth.getSessionKey(),
      }),
    });
  },
});

// Your backend then includes fraud_session_id when creating
// an Authorization or Transfer with the Finix API:
//
// POST /authorizations
// {
//   "source": "PIe2YvPC7Mf6aMpP9kKTREHB",
//   "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
//   "amount": 100,
//   "currency": "USD",
//   "fraud_session_id": "<session key from finixAuth.getSessionKey()>"
// }

// Switch tracking to a different Merchant ID
finixAuth.connect("MUeDVrf2ahuKc9Eg5TeZugvs");

// With optional callback
finixAuth.connect("MUeDVrf2ahuKc9Eg5TeZugvs", function (sessionKey) {
  console.log("New session key:", sessionKey);
});