{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-js/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-walkthrough","step"]},"type":"markdown"},"seo":{"title":"Callbacks | Finix.js Reference","description":"API reference for Finix.js callbacks — onLoad, onUpdate, and onSubmit event handlers for the payment form.","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/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":"Low-Code / No-Code","includeFiles":["low-code-no-code/**/*.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":[]},{"title":"Release Notes","includeFiles":["release-notes/**/*.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/callbacks.js","content":[{"start":0,"condition":{"steps":["on-load"]},"children":["Finix.PaymentForm(\"payment-form\", \"sandbox\", \"APgPDQrLD52TYvqazjHJJchM\", {","  onLoad: function () {","    // Form iframe has finished loading — safe to show dependent UI","    document.getElementById(\"pay-btn\").disabled = false;","    document.getElementById(\"loading-spinner\").style.display = \"none\";","  },","});"]},"",{"start":10,"condition":{"steps":["on-update"]},"children":["Finix.PaymentForm(\"payment-form\", \"sandbox\", \"APgPDQrLD52TYvqazjHJJchM\", {","  onUpdate: function (state, binInformation, hasErrors) {","    // state: form field states keyed by field name","    // binInformation: { cardBrand, bin } (card payments only)","    // hasErrors: true if any field has a validation error","","    document.getElementById(\"pay-btn\").disabled = hasErrors;","","    // Detect card brand","    if (binInformation?.cardBrand) {","      console.log(\"Card brand:\", binInformation.cardBrand);","    }","  },","});"]},"",{"start":27,"condition":{"steps":["on-update-state"]},"children":["Finix.PaymentForm(\"payment-form\", \"sandbox\", \"APgPDQrLD52TYvqazjHJJchM\", {","  onUpdate: function (state, binInformation, hasErrors) {","    // Each field in state has: errors, isDirty, isFocused, errorMessages","    // Note: most fields do not expose a value; exceptions include country and current_payment_method","    const nameField = state[\"name\"]; // card_holder_name / account_holder_name maps to \"name\"","    const addressLine1 = state[\"address.line1\"];","","    console.log(\"Name has errors:\", nameField?.errors);","    console.log(\"Name is focused:\", nameField?.isFocused);","  },","});"]},"",{"start":41,"condition":{"steps":["on-submit"]},"children":["Finix.PaymentForm(\"payment-form\", \"sandbox\", \"APgPDQrLD52TYvqazjHJJchM\", {","  // Providing onSubmit automatically renders a submit button in the form","  onSubmit: function (error, response) {","    if (error) {","      // error contains status code and error details","      console.error(\"Tokenization failed:\", error);","      return;","    }","    const tokenData = response.data || {};","    const token = tokenData.id; // use to create a Payment Instrument","    console.log(\"Token:\", token);","  },","});"]},""],"metadata":{"steps":["on-load","on-update","on-update-state","on-submit"]},"basename":"callbacks.js","language":"javascript"}],"downloadAssociatedFiles":[]}],"steps":[{"id":"on-load","heading":"onLoad"},{"id":"on-update","heading":"onUpdate"},{"id":"on-submit","heading":"onSubmit"}],"inputs":{},"toggles":{}},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"callbacks","__idx":0},"children":["Callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Callback functions passed in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," object to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/js/payment-form"},"children":["Finix.PaymentForm()"]},". Each callback fires in response to a specific form lifecycle event."]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"on-load","heading":"onLoad"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires once when the Payment Form iframe finishes loading. Takes no parameters."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"onLoad: function () { ... }\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onLoad"]}," to show UI that depends on the form being ready — for example, enabling a custom submit button or hiding a loading spinner."]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"on-update","heading":"onUpdate"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires every time the form state changes — field values, validation errors, focus and blur events, card brand detection, and payment method switching."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"onUpdate: function (state, binInformation, hasErrors) { ... }\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":"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":["state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Form state including metadata about which inputs are valid, dirty, or focused — does not expose payment data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["binInformation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["High-level BIN data such as BIN number and card brand"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasErrors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if the form currently has validation errors — useful for enabling or disabling a custom submit button"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"on-submit","heading":"onSubmit"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when the form is submitted. Providing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," in the options automatically renders a submit button inside the form."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"onSubmit: function (error, response) { ... }\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":"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":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object | null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error object if submission failed; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," on success"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object | null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Response object containing the token data on success; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," on error"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," when you want the form to render and manage its own submit button. For a custom button outside the form, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form.submit()"]}," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/js/form-instance"},"children":["method"]}," instead."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/js/token-response"},"children":["Token Response"]}," for the full response shape."]}]}]}]},"headings":[{"value":"Callbacks","id":"callbacks","depth":1}],"frontmatter":{"seo":{"title":"Callbacks | Finix.js Reference","description":"API reference for Finix.js callbacks — onLoad, onUpdate, and onSubmit event handlers for the payment form."},"markdown":{"toc":{"hide":true}},"footer":{"hide":true}},"lastModified":"2026-04-07T17:00:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/js/callbacks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}