How Checkout works

​

Lifecycle

1. Create. overflow.checkout(options) returns a handle. No network calls yet.
2. Mount. checkout.mount('#host') renders a loading skeleton, then fetches your merchant payment settings from the Overflow API.
3. Ready. Once configuration loads, Checkout renders the configured sections and fires onReady.
4. Interact. As the shopper types or selects fields, onChange fires with the aggregated { value, complete, errors }.
5. Submit. The submit button inside Checkout (or your programmatic checkout.submit() call) validates every section, tokenizes the selected payment method, and fires onSubmit with the payload.
6. Authorize. Forward the payload to your server, which calls the Overflow API to authorize the charge with your secret key.

​

Section order

1. Contact
2. Shipping address
3. Billing address
4. Payment methods
5. Custom elements

overflow.checkout({
  paymentMethods: ['card', 'bank'],
  order: ['paymentMethods'],   // Picker first, then the rest.
});

​

Payment method order

overflow.checkout({
  paymentMethods: ['applePay', 'googlePay', 'card', 'bank'],
});

​

Contact block

overflow.checkout({
  paymentMethods: ['card'],
  contact: {
    email: {},
    fullName: { splitMode: 'horizontal' },
    phone: { defaultCountry: 'US' },
    companyName: {},
  },
});

​

Addresses

overflow.checkout({
  paymentMethods: ['card'],
  billingAddress: {},
  shippingAddress: {
    header: { text: 'Shipping address' },
    fields: {
      fullName: {},
      country: { supportedCountries: ['US', 'CA'] },
    },
  },
});

​

Custom elements

overflow.checkout({
  paymentMethods: ['card'],
  customElements: {
    giftMessage: { elementType: 'text', label: 'Gift message (optional)' },
    coverFee: { elementType: 'checkbox', label: 'Cover the processing fee' },
  },
});

​

Submit flow

1. Flush any pending debounced validation on every mounted child.
2. Collect per-section errors, tagged by source.
3. If there are errors, fire onError with the aggregated fieldErrors and stop.
4. Otherwise, tokenize the selected payment method.
5. Fire onSubmit with { value } where value carries the method, the tokenized payment payload, and every configured section (contact, addresses, custom elements).

​

Update in place

checkout.update({
  paymentMethods: ['card', 'bank', 'applePay'],
  card: { fields: { postalCode: { hidden: true } } },
});

​

Programmatic access to custom elements

const gift = checkout.getCustomElement('giftMessage');
gift?.on('onChange', ({ value }) => console.log(value));

​

Next steps