# Options

The optional fourth argument to [Finix.PaymentForm()](https://docs.finix.com/js/payment-form). All properties are optional.

## Payment Methods

`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"]`

## Field Display

`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](https://docs.finix.com/js/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](https://docs.finix.com/js/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`

## Custom Text

`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

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 |

## Appearance

`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](https://docs.finix.com/js/styles-and-fonts).

## Plaid

`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`.

## Options Example

```javascript
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"])
  },
});
```