Callback functions passed in the options object to Finix.PaymentForm(). Each callback fires in response to a specific form lifecycle event.
onLoad
Fires once when the Payment Form iframe finishes loading. Takes no parameters.
onLoad: function () { ... }Use onLoad to show UI that depends on the form being ready — for example, enabling a custom submit button or hiding a loading spinner.
onUpdate
Fires every time the form state changes — field values, validation errors, focus and blur events, card brand detection, and payment method switching.
onUpdate: function (state, binInformation, hasErrors) { ... }| Parameter | Type | Description |
|---|---|---|
state | object | Form state including metadata about which inputs are valid, dirty, or focused — does not expose payment data |
binInformation | object | High-level BIN data such as BIN number and card brand |
hasErrors | boolean | true if the form currently has validation errors — useful for enabling or disabling a custom submit button |
onSubmit
Fires when the form is submitted. Providing onSubmit in the options automatically renders a submit button inside the form.
onSubmit: function (error, response) { ... }| Parameter | Type | Description |
|---|---|---|
error | object | null | Error object if submission failed; null on success |
response | object | null | Response object containing the token data on success; null on error |
Use onSubmit when you want the form to render and manage its own submit button. For a custom button outside the form, use form.submit() method instead.
See Token Response for the full response shape.
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";
},
});
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);
}
},
});
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);
},
});
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);
},
});