Bank

The bank element collects ACH bank credentials. Shoppers can search for their bank and sign in (fast, no typing) or enter routing and account numbers manually. You choose which modes are available and which is the default. Configure bank inside Checkout for the recommended integration path, or mount standalone when you need a bank-only form.

Standalone example

<div id="bank"></div>
<button id="pay" disabled>Pay</button>

<script>
  const overflow = new Overflow('live_pub_...');

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

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

  bank.on('onSubmit', ({ value }) => {
    fetch('/api/authorize', {
      method: 'POST',
      body: JSON.stringify({ method: 'bank', bank: value }),
    });
  });

  bank.mount('#bank');
  document.getElementById('pay').addEventListener('click', () => bank.submit());
</script>

Modes

The element renders one of two modes at a time. The shopper can toggle between them (unless you lock one in) using an in-element control.

Mode	Behavior
`'plaid'`	Search for your bank, sign in, and pick an account.
`'manual'`	Enter routing number, account number, and account type.

Pick the default:

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

Lock the shopper to a single mode:

overflow.bank({
  mode: { lockTo: 'manual' },   // Toggle button is hidden.
});

Manual fields

accountType: <select> with values 'checking' / 'savings'. Default 'checking'.
routingNumber: 9-digit routing number.
accountNumber: account number.
confirmAccountNumber: must match accountNumber to complete.

Configure via fields.accountType, fields.routingNumber, fields.accountNumber, fields.confirmAccountNumber.

Submitted value

onSubmit emits a discriminated union keyed by mode. Manual submissions carry encrypted routing and account numbers; fast-signin submissions carry a linked-account public token.

bank.on('onSubmit', ({ value }) => {
  if (value.mode === 'manual') {
    // value.bankAccountType:            'checking' | 'savings'
    // value.encryptedBankAccountNumber: encrypted string, forward verbatim
    // value.encryptedBankRoutingNumber: encrypted string, forward verbatim
  } else {
    // value.mode === 'plaid'
    // value.publicToken:      Linked-account public token.
    // value.accountId:        Linked account id.
    // value.institutionName:  Bank display name.
    // value.accountLast4:     Last four digits.
    // value.accountType?:     'checking' | 'savings'
  }
});

Forward value to your server as-is. See the Bank reference for the full type and the authorize a payment API reference for the authorize request.

Retry on `UNKNOWN_KID`

If your authorize endpoint returns 400 { code: 'UNKNOWN_KID' } after a manual-mode bank submission, call overflow.invalidateBankFieldEncryptionCache() and prompt the shopper to submit again. Checkout runs this recovery for you when the tagged error is recognized.

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

Inside Checkout

overflow.checkout({
  paymentMethods: ['card', 'bank'],
  bank: { mode: { default: 'manual' } },
});

The nested bank key accepts the same options the standalone element accepts. Values arrive on the Checkout envelope as value.bank.

Get started

Elements

Options

Events

Theming

Guides

Standalone example

Modes

Manual fields

Submitted value

Retry on `UNKNOWN_KID`

Inside Checkout

Next steps

Best practices

Reference

​Standalone example

​Modes

​Manual fields

​Submitted value

​Retry on UNKNOWN_KID

​Inside Checkout

​Next steps

Best practices

Reference

Standalone example

Modes

Manual fields

Submitted value

Retry on `UNKNOWN_KID`

Inside Checkout

Next steps