Bank best practices

Fast bank sign-in has higher completion rates than manual entry. Set it as the default and let shoppers who need it fall back to manual:

overflow.bank({
  mode: { default: 'plaid' },
});

Only lock to 'manual' when your integration or shopper base explicitly needs it.

Retry on `UNKNOWN_KID`

Manual-mode bank submissions encrypt account credentials with a rotating key. If your authorize endpoint returns 400 { code: 'UNKNOWN_KID' }, refresh the cached key and prompt the shopper to submit again:

if (result.code === 'UNKNOWN_KID') {
  overflow.invalidateBankFieldEncryptionCache();
  showBanner('Please try again.');
}

Checkout wires this recovery in automatically. Only wire it yourself for standalone bank integrations.

Do not rely on `disabled` to fully suppress bank

Setting disabled: true on a mounted bank element locks the manual-mode inputs and the mode toggle, but the fast-signin surface owns its own iframe and is not fully suppressed by disabled. To completely take bank offline (for example, while another payment method is processing), call bank.unmount() and remount when you are ready to accept it again.

Gate your Pay button on `complete`

Bank validation completes when the shopper finishes fast-signin or when every manual field passes format checks and the two account-number entries match.

bank.on('onChange', ({ complete }) => {
  payButton.disabled = !complete;
});

Show a clear label

Bank payments have longer capture windows than cards. Label your Pay button so shoppers know what happens next (Pay by bank, Authorize ACH, etc.).

Test with `test_pub_…`

Use a test_pub_… publishable key while you build. Test fast-signin behavior in a sandbox institution. Swap to live_pub_… for production.

Get started

Elements

Options

Events

Theming

Guides

Retry on `UNKNOWN_KID`

Do not rely on `disabled` to fully suppress bank

Gate your Pay button on `complete`

Show a clear label

Test with `test_pub_…`

Next steps

​Default to fast-signin

​Retry on UNKNOWN_KID

​Do not rely on disabled to fully suppress bank

​Gate your Pay button on complete

​Show a clear label

​Test with test_pub_…

​Next steps

Default to fast-signin

Retry on `UNKNOWN_KID`

Do not rely on `disabled` to fully suppress bank

Gate your Pay button on `complete`

Show a clear label

Test with `test_pub_…`

Next steps