The optional fourth argument to Finix.PaymentForm(). All properties are optional.
paymentMethods
Controls which payment types the form accepts.
| Value | Description |
|---|---|
["card", "bank"] | Accept both card and bank accounts (default) |
["card"] | Accept only credit or debit cards |
["bank"] | Accept only bank accounts (USA and Canada) |
Type: string[] — Default: ["card", "bank"]
showAddress
Show billing address fields below the payment fields.
Type: boolean — Default: false
To find the list of address field IDs, go to the Field IDs page and look for the Address Fields section.
showLabels / showPlaceholders
| Option | Type | Default | Description |
|---|---|---|---|
showLabels | boolean | true | Show labels above each input |
showPlaceholders | boolean | true | Show placeholder text inside inputs |
hideFields
An array of field IDs to hide from the form. The fields number and expiration_date cannot be hidden.
Type: string[] — Default: []
For valid field ID values, visit the Field IDs page.
requiredFields
An array of field IDs to mark as required beyond the form defaults.
Type: string[] — Default: []
Supported values: name, card_holder_name, account_holder_name, address_line1, address_line2, address_city, address_region, address_postal_code, address_country
labels
Override the default label text for any field, keyed by field ID.
Type: Record<string, string> — Default: {}
placeholders
Override the default placeholder text for any field, keyed by field ID.
Type: Record<string, string> — Default: {}
errorMessages
Override the default validation error messages for any field, keyed by field ID.
Type: Record<string, string> — Default: {}
defaultValues
Pre-fill field values on form load, keyed by field ID.
Type: Record<string, string> — Default: {}
The following PCI-sensitive fields cannot be pre-filled: number, expiration_date, security_code, account_number, bank_code, institution_number, or transit_number
submitLabel
Custom text for the auto-rendered submit button. Only applies when onSubmit is provided.
Type: string — Default: undefined
Validation options
| Option | Type | Default | Description |
|---|---|---|---|
requireSecurityCode | boolean | true | Require CVV/CVC for card payments |
confirmAccountNumber | boolean | true | Show double-entry confirmation for bank account number |
hidePotentialIssueMessages | boolean | true | Hide warning messages for non-standard but valid card numbers |
hideErrorMessages | boolean | false | Hide all inline validation error messages |
theme / enableDarkMode
| Option | Type | Default | Description |
|---|---|---|---|
theme | string | "finix" | Built-in visual theme |
enableDarkMode | boolean | false | Apply dark styles when prefers-color-scheme: dark |
Available themes: finix, amethyst, sapphire, topaz, ruby, emerald, midnight, elevated
For custom CSS overrides, see Styles & Fonts.
plaidLinkSettings
Configure the Plaid Link experience for bank account connections. Only applies when paymentMethods includes "bank".
| Property | Type | Default | Description |
|---|---|---|---|
displayName | string | Application name | Name shown at the top of the Plaid modal |
language | string | "en" | Language for the Plaid Link experience |
countries | string[] | ["USA", "CAN"] | ISO-3 country codes for which banks appear |
When a user completes the Plaid flow, finix.js submits a third-party token request using the Plaid public_token and account_id.
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
paymentMethods: ["card", "bank"], // Accept both (default)
// paymentMethods: ["card"], // Cards only
// paymentMethods: ["bank"], // Bank accounts only
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
showAddress: true, // Show billing address fields (default: false)
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
showLabels: true, // Show field labels (default: true)
showPlaceholders: true, // Show placeholder text (default: true)
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
hideFields: ["security_code", "card_holder_name"],
// Note: "number" and "expiration_date" cannot be hidden
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
requiredFields: [
"name", // Alias for card_holder_name / account_holder_name
"address_line1",
"address_city",
"address_region",
"address_postal_code",
"address_country",
],
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
labels: {
card_holder_name: "Full Name",
number: "Card Number",
expiration_date: "Expiry",
security_code: "CVV",
},
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
placeholders: {
card_holder_name: "Jane Smith",
number: "•••• •••• •••• ••••",
security_code: "•••",
},
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
errorMessages: {
number: "Please enter a valid card number.",
expiration_date: "Please enter a valid expiration date.",
security_code: "Please enter your 3-digit CVV.",
},
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
defaultValues: {
// PCI-sensitive fields cannot be pre-filled:
// number, expiration_date, security_code, account_number, bank_code
card_holder_name: "Jane Smith",
address_line1: "123 Main St",
address_city: "San Francisco",
address_region: "CA",
address_postal_code: "94105",
address_country: "USA",
},
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
onSubmit: function (error, response) { /* ... */ },
submitLabel: "Pay Now", // Custom label for the auto-rendered submit button
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
requireSecurityCode: true, // Require CVV/CVC (default: true)
confirmAccountNumber: true, // Show double-entry for bank account number (default: true)
hidePotentialIssueMessages: false, // Hide warnings for unusual-but-valid cards (default: false)
hideErrorMessages: false, // Hide all validation error messages (default: false)
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
// Available themes: finix, amethyst, sapphire, topaz, ruby, emerald, midnight, elevated
theme: "sapphire",
enableDarkMode: true, // Respect prefers-color-scheme media query (default: false)
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
paymentMethods: ["bank"],
plaidLinkSettings: {
displayName: "My Store", // Name shown at top of Plaid modal
language: "en", // Language for the Plaid experience (default: "en")
countries: ["USA", "CAN"],// ISO-3 country codes (default: ["USA", "CAN"])
},
});