{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-js/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-walkthrough","step"]},"type":"markdown"},"seo":{"title":"Finix.Auth | Finix.js Reference","description":"How to use Finix.Auth to initialize fraud detection and pass the session key to your backend for fraud scoring on payments.","siteUrl":"https://docs.finix.com/","llmstxt":{"hide":false,"sections":[{"title":"Getting Started","includeFiles":["guides/getting-started/**/*.md"],"excludeFiles":[]},{"title":"Online Payments","includeFiles":["guides/online-payments/**/*.md"],"excludeFiles":["guides/online-payments/payment-features/fsa-hsa-non-healthcare-mcc.md"]},{"title":"In-Person Payments","includeFiles":["guides/in-person-payments/**/*.md"],"excludeFiles":[]},{"title":"Subscriptions","includeFiles":["guides/subscriptions/**/*.md"],"excludeFiles":[]},{"title":"After the Payment","includeFiles":["guides/subscriptions/after-the-payment/**/*.md"],"excludeFiles":[]},{"title":"Managing Operations","includeFiles":["guides/managing-operations/**/*.md"],"excludeFiles":[]},{"title":"Platform Payments","includeFiles":["guides/platform-payments/**/*.md"],"excludeFiles":[]},{"title":"Payouts","includeFiles":["guides/payouts/**/*.md"],"excludeFiles":[]},{"title":"Developers","includeFiles":["additional-resources/developers/**/*.md"],"excludeFiles":[]},{"title":"Plugins","includeFiles":["additional-resources/plugins/**/*.md"],"excludeFiles":[]},{"title":"Industry Considerations","includeFiles":["guides/industry-considerations/**/*.md"],"excludeFiles":[]},{"title":"Regional Considerations","includeFiles":["guides/regional-considerations/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeWalkthrough","attributes":{"__idx":1,"filters":{},"filesets":[{"files":[{"path":"js/_filesets/auth.js","content":[{"start":0,"condition":{"steps":["init"]},"children":["// Initialize before Finix.PaymentForm so the session is ready by submit time","const finixAuth = Finix.Auth(\"sandbox\", \"MUeDVrf2ahuKc9Eg5TeZugvs\");"]},"",{"start":5,"condition":{"steps":["init-callback"]},"children":["// Optional callback — fires once the session key is available","const finixAuth = Finix.Auth(\"sandbox\", \"MUeDVrf2ahuKc9Eg5TeZugvs\", function (sessionKey) {","  console.log(\"Session key:\", sessionKey);","});"]},"",{"start":12,"condition":{"steps":["get-session-key"]},"children":["const sessionKey = finixAuth.getSessionKey();"]},"",{"start":16,"condition":{"steps":["with-payment-form"]},"children":["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(),","      }),","    });","  },","});"]},"",{"start":39,"condition":{"steps":["backend-note"]},"children":["// 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()>\"","// }"]},"",{"start":53,"condition":{"steps":["connect"]},"children":["// Switch tracking to a different Merchant ID","finixAuth.connect(\"MUeDVrf2ahuKc9Eg5TeZugvs\");","","// With optional callback","finixAuth.connect(\"MUeDVrf2ahuKc9Eg5TeZugvs\", function (sessionKey) {","  console.log(\"New session key:\", sessionKey);","});"]},""],"metadata":{"steps":["init","init-callback","get-session-key","with-payment-form","backend-note","connect"]},"basename":"auth.js","language":"javascript"}],"downloadAssociatedFiles":[]}],"steps":[{"id":"init","heading":"Finix.Auth()"},{"id":"init-callback","heading":"Optional callback"},{"id":"get-session-key","heading":"getSessionKey()"},{"id":"with-payment-form","heading":"Pass the session key on submit"},{"id":"backend-note","heading":"Include fraud_session_id in your payment request"},{"id":"connect","heading":"connect()"}],"inputs":{},"toggles":{}},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"finixauth","__idx":0},"children":["Finix.Auth"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finix.js includes built-in fraud detection through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two parts to integrating fraud detection:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client side"]}," — initialize ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Finix.Auth"]}," and retrieve the session key at submit time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Backend side"]}," — include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fraud_session_id"]}," when creating an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transfer"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"client-side-setup","__idx":1},"children":["Client-side setup"]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"init","heading":"Finix.Auth()"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Initialize ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Finix.Auth"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Finix.PaymentForm"]},", at page load. This gives the session time to establish before the buyer submits the form."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Finix.Auth(environment, merchantId, callback)\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"sandbox\""]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"live\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your Finix Merchant ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["function(sessionKey)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called once initialization completes"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"init-callback","heading":"Optional callback"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"get-session-key","heading":"getSessionKey()"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returns the current fraud session key. Call this inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," — by the time the buyer submits the form, the session will have initialized."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"finixAuth.getSessionKey() → string\n","lang":"text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-to-your-backend","__idx":2},"children":["Sending to your backend"]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"with-payment-form","heading":"Pass the session key on submit"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"backend-note","heading":"Include fraud_session_id in your payment request"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your backend should include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fraud_session_id"]}," when creating an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transfer"]}," with the Finix API. Finix uses the session key to correlate the buyer's checkout behavior with the payment for fraud scoring."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For full details on the backend payment request and how to handle blocked transactions, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/online-payments/fraud-and-risk/fraud-detection#step-4-send-session-id-in-payment"},"children":["Fraud Detection guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"managing-multiple-merchants","__idx":3},"children":["Managing multiple merchants"]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"connect","heading":"connect()"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connect()"]}," to reinitialize tracking for a different Merchant ID. This generates a new session key for that merchant."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"finixAuth.connect(merchantId, callback)\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Finix Merchant ID to switch tracking to"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["function(sessionKey)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called once the new session key is ready"]}]}]}]}]}]}]}]},"headings":[{"value":"Finix.Auth","id":"finixauth","depth":1},{"value":"Client-side setup","id":"client-side-setup","depth":2},{"value":"Sending to your backend","id":"sending-to-your-backend","depth":2},{"value":"Managing multiple merchants","id":"managing-multiple-merchants","depth":2}],"frontmatter":{"seo":{"title":"Finix.Auth | Finix.js Reference","description":"How to use Finix.Auth to initialize fraud detection and pass the session key to your backend for fraud scoring on payments."},"markdown":{"toc":{"hide":true}},"footer":{"hide":true}},"lastModified":"2026-04-07T17:00:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/js/auth","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}