onSubmit

onSubmit fires when an element produces a submittable value. For inputs, it fires when you call element.submit() after validation passes. For wallet elements, it fires when the wallet sheet resolves with a cryptogram. value is non-null by construction.

Payload

interface OverflowSubmitEvent<T> {
  elementType: T;
  value: ElementValueMap[T]; // non-null
}

Example

card.on('onSubmit', async ({ value }) => {
  await fetch('/your-backend/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ paymentMethod: value }),
  });
});

Merchant-driven vs. self-driven

card, bank, email, fullName, phone, companyName, address elements, and custom elements are merchant-driven: you call element.submit() (from a button click, a form submit, or an external CTA).
applePay and googlePay are self-driven: the wallet sheet triggers onSubmit directly when the shopper authorizes.
checkout composes both: card and bank submit through the internal button, wallets submit through their sheet.
submitButton is a relay: it fires onSubmit with value: undefined on every click. Use it to drive an external card.submit() or bank.submit() call.

Never call the payment gateway directly

For card and wallets, value is a tokenized payload. Forward it to your server, which calls the Overflow authorize endpoint. Calling the payment gateway directly from the browser bypasses risk evaluation and the SDK’s payment-settings layer.

Do not return a promise expecting the SDK to await it

The contract is fire-and-forget. If you need request-in-flight UI, manage it in your own state:

let inFlight = false;

card.on('onSubmit', async ({ value }) => {
  if (inFlight) return;
  inFlight = true;
  spinner.hidden = false;
  try {
    await postToBackend(value);
  } finally {
    inFlight = false;
    spinner.hidden = true;
  }
});

Checkout

Switch on value.method first; the per-method key is then non-null:

checkout.on('onSubmit', async ({ value }) => {
  const { method, contact, billingAddress } = value;
  const paymentMethod =
    method === 'card'      ? { type: 'scheme', ...value.card } :
    method === 'bank'      ? bankPayload(value.bank) :
    method === 'applePay'  ? { type: 'applepay',  walletToken: value.applePay.walletToken } :
                             { type: 'googlepay', walletToken: value.googlePay.walletToken };

  await fetch('/your-backend/authorize', {
    method: 'POST',
    body: JSON.stringify({ paymentMethod, contact, billingAddress }),
  });
});

Wallets

The onSubmit.value for wallets is:

interface WalletElementValue {
  walletToken: string;
  walletType: 'applePay' | 'googlePay';
  email?: string;
  name?: { firstName: string; lastName: string };
  phone?: string;
  billingAddress?: AddressValue;
  shippingAddress?: AddressValue;
}

Contact and address keys appear only when the wallet sheet returned them. Set require.email, require.name, and so on in the wallet options to ask the sheet for them. Keys the sheet did not return are omitted, never null.

Get started

Elements

Options

Events

Theming

Guides

Payload

Example

Merchant-driven vs. self-driven

Never call the payment gateway directly

Do not return a promise expecting the SDK to await it

Checkout

Wallets

See also

​Payload

​Example

​Merchant-driven vs. self-driven

​Never call the payment gateway directly

​Do not return a promise expecting the SDK to await it

​Checkout

​Wallets

​See also

Payload

Example

Merchant-driven vs. self-driven

Never call the payment gateway directly

Do not return a promise expecting the SDK to await it

Checkout

Wallets

See also