Checkout functionality reference - ElasticFunnels.io Documentation

This page is the source of truth for how ElasticFunnels checkout works: configuration keys, server behavior, and what visitors experience. For a step-by-step page build (HTML patterns, wizard layout, copy-paste examples), use How to design a checkout page. That guide defers to this page for exact semantics of checkout_settings and security options. For template syntax ([[ ]], bindings, checkout.* in the page builder), see Frontend Template Engine: Checkout.

1) Enable checkout on a page

Checkout behavior runs only when the page is marked as a checkout page:

Open Page List → Edit Page
Enable Is checkout page
Save

If this is off, checkout scope data, submit handling, payment processing, and post-purchase redirects may not run as documented here.

2) Checkout scope (frontend)

On checkout pages, the checkout scope is available to templates and bindings. Common keys:

Area	Keys
Customer	`checkout.customer.*` (names, email, phone, shipping/billing address fields)
Geography	`checkout.countries`, `checkout.usStates` (dropdown options)
Commerce	`checkout.coupon`, `checkout.coupon_message`, `checkout.bump_products`, `checkout.selectedBumpLines`
Totals	`checkout.subtotal`, `checkout.tax`, `checkout.shipping`, `checkout.total`, plus `*_raw` variants (see template engine doc)
Toggle	`checkout.shipping_same_as_billing`
Wallets	`checkout.wallet_available` (`{ applePay, googlePay }` — starts `false/false`, updated once Collect.js / Stripe.js detects support), `checkout.wallet_visible` (boolean — `true` once a wallet button actually renders; only promoted, never reset), `checkout.wallet_settings` (from `checkout_settings.wallet`)
Merchant	`checkout.merchant_country` (merchant’s country, falling back to the domain’s, then `US`)
Payment panel	`checkout.panel_billing_fields` (from `checkout_settings.billing_fields`; `null` = show all)
Subscription	`checkout.is_subscription`, `checkout.subscription.*` (see template engine doc for the full shape, including `intro_offer`, `price_steps`, `prepaid`, `tiers`)

Template engine details: Checkout.

3) Supported form field names

These align with what the checkout runtime validates and submits (shipping-first; billing can mirror shipping). Names Two name pairs exist and both are recognised:

shipping_first_name, shipping_last_name — what the Checkout Details builder block emits, and what the server requires (with fallbacks). Use these on shipping-collecting pages.
first_name, last_name — what <checkout-personal-details> emits, and the pair the card panel checks when deciding whether to inject its own “Cardholder Name” field.

The cardholder-name detector only looks for first_name / last_name. A page that collects shipping_first_name / shipping_last_name (the builder default) will therefore also get a redundant Cardholder Name field injected into the card panel. Add first_name / last_name inputs — hidden ones are fine — if you want to suppress it.

Where a name is missing, the server backfills it: personal ← shipping ← billing ← the cardholder name (split into first / last). Shipping / personal

email (required), phone (optional)
shipping_address, shipping_address2 (optional)
shipping_country (required, 2-letter, uppercased), shipping_city, shipping_state, shipping_zip

Client-side validation requires any of these that are present on the page; server-side, only email, shipping_country and the shipping name pair are strictly required — address, city, state and ZIP are accepted empty. shipping_country defaults to US when left blank.

Billing (when shown; if empty, shipping values are used)

billing_first_name, billing_last_name — never client-side required
billing_address, billing_address2, billing_country, billing_city, billing_state, billing_zip — validated client-side only when a billing field is visible; all optional server-side

Toggle

shipping_same_as_billing → checkout.shipping_same_as_billing

Errors

Use data-checkout-error="<field_name>" matching the input name for inline validation messages.

4) `checkout_settings` (backend script)

Configure checkout using variables set in a backend script on the same checkout page (<script scope="backend">). The platform reads checkout_settings when the page is rendered.

<script scope="backend">
var checkout_settings = checkout_settings || {};
// Optional: restrict countries / US states (see below)
// Optional: checkout abuse protection (see section 5)
</script>

4.1 Countries and US states allowlist

Keys:

checkout_settings.countries → drives checkout.countries in the UI
checkout_settings.usStates → drives checkout.usStates for US state dropdowns

Allowed entry formats:

Two-letter codes as strings: 'US', 'ca', 'tx'
{ value: 'US' }
{ value: 'US', label: 'United States' }

Behavior:

Values are normalized (e.g. uppercase) and validated against built-in lists.
Invalid entries are dropped.
If nothing valid remains, the full default lists are used (not restricted).
The effective allowlist is stored in the visitor session and re-validated on submit, so blocked values cannot be forced with browser devtools alone.

4.2 Example: countries only

<script scope="backend">
var checkout_settings = checkout_settings || {};
checkout_settings.countries = ['US', 'CA', 'GB'];
</script>

4.3 Example: US states only

<script scope="backend">
var checkout_settings = checkout_settings || {};
checkout_settings.usStates = ['CA', 'TX', 'NY', 'FL'];
</script>

4.4 Card panel billing fields

checkout_settings.billing_fields controls which inputs the card panel’s auto-injected billing block renders. It is surfaced to templates as checkout.panel_billing_fields.

<script scope="backend">
var checkout_settings = checkout_settings || {};
checkout_settings.billing_fields = ['country'];   // country only, no ZIP
</script>

Value	Effect
omitted / `null`	Both Country and ZIP are shown (default)
`['country']`	Country select only
`['zip']`	ZIP / postal code only
`['country', 'zip']`	Both — same as the default
`['address']`	Legacy alias for `['zip']`, kept so existing pages keep working

If the resulting set is empty, the billing block is not rendered at all.

4.5 Wallet labels

checkout_settings.wallet is passed through to checkout.wallet_settings and used on the wallet payment sheet for subscriptions:

<script scope="backend">
var checkout_settings = checkout_settings || {};
checkout_settings.wallet = {
  recurring_description: 'Monthly wellness subscription',
  management_url: 'https://members.yourdomain.com/subscriptions'
};
</script>

5) Checkout abuse protection (card-testing / velocity)

Optional progressive friction on main sale card checkout submissions (POST /process-checkout). It is off by default unless you set checkout_settings.abuse_protection.enabled to true.

This is separate from site-wide page rate limiting / HTML captcha on normal page views. Abuse protection here applies only to the checkout payment submit path when enabled on the checkout page.

5.1 Configuration

<script scope="backend">
var checkout_settings = checkout_settings || {};
checkout_settings.abuse_protection = {
  enabled: true,
  mode: 'progressive',
  thresholds: {
    captcha_requests: 8,
    hard_block_requests: 20,
    window_ms: 60000,
    block_duration_ms: 3600000
  }
};
</script>

Key	Type	Default when omitted
`checkout_settings.abuse_protection.enabled`	boolean	`false` (feature off)
`checkout_settings.abuse_protection.mode`	string	`"progressive"` (only mode documented)
`thresholds.captcha_requests`	integer	`8`
`thresholds.hard_block_requests`	integer	`20`
`thresholds.window_ms`	integer	`60000` (1 minute)
`thresholds.block_duration_ms`	integer	platform default block window (typically one hour)

You can omit thresholds entirely to use defaults. Partial overrides are merged with defaults for any key you specify.

5.2 What is protected

In scope: Main sale submissions to POST /process-checkout when the request is not marked as an upsell (type ≠ upsell).
Out of scope: One-click upsell charges, PayPal/Klarna flows that do not use the same submit path, and arbitrary API calls. Tighten other surfaces separately if needed.

5.3 Session lifecycle

When a visitor loads a checkout page, sanitized abuse settings are stored in session (with brand_id, checkout page_id from the render context, and a timestamp).
Each qualifying POST /process-checkout is counted per visitor IP inside a checkout-specific bucket (not mixed with generic page-view rate limits).
If settings are stale (e.g. older than 24 hours) or brand / page no longer match the request, the stored config is cleared and protection does not apply until the visitor loads checkout again.
After a successful checkout captcha verification, the visitor receives a short-lived “verified” flag for checkout (default 15 minutes) and the checkout attempt counter for that IP is reset, so legitimate users can complete payment after solving the challenge.

5.4 Progressive behavior

Within window_ms, counting checkout submit attempts for the IP:

Condition	HTTP	Visitor experience
Below `captcha_requests`	200 path	Normal checkout continues.
At or above `captcha_requests`, below `hard_block_requests`	`429`	JSON response asks for captcha; checkout UI opens a modal, visitor solves math challenge, then checkout resubmits automatically.
At or above `hard_block_requests`	`403`	Submit blocked for a period (`block_duration_ms`); message indicates too many attempts.

Local and private IPs are not rate-limited by this checkout guard.

5.5 JSON response fields (checkout submit)

When abuse protection returns an error-shaped response, the JSON may include:

Field	Meaning
`success`	`false`
`error`	Human-readable message
`error_code`	Machine code (see below)
`error_type`	`"abuse_protection"` when from this feature
`retry_allowed`	`true` when captcha path may retry; `false` on hard block
`captcha_required`	`true` when the UI should show the captcha step
`captcha_payload`	`{ question, token }` for the modal challenge

error_code values (submit / middleware)

Code	Typical HTTP	Meaning
`CHECKOUT_CAPTCHA_REQUIRED`	429	Solve captcha, then retry submit.
`CHECKOUT_HARD_BLOCKED`	403	Too many attempts; wait before retrying.

Captcha verification (handled inside checkout UI, not a merchant integration surface) may return CHECKOUT_CAPTCHA_INVALID, CHECKOUT_CAPTCHA_DISABLED, CHECKOUT_CAPTCHA_SAVE_FAILED, or CHECKOUT_CAPTCHA_ERROR if something goes wrong; the UI refreshes the challenge or shows an error.

5.6 Tuning and false positives

Corporate NAT or shared IPs can concentrate traffic on one address; if legitimate buyers are challenged too often, raise captcha_requests or widen window_ms.
For testing, use low thresholds only on a sandbox checkout or test brand.
If protection “never fires,” confirm the checkout page was loaded in the same browser session before submit (session must contain the config).

6) Payment panel and submit wiring

Recommended card flow:

<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover"></checkout-cc-panel>
<div data-checkout-message class="checkout-message"></div>
<button type="button" data-checkout-submit>Pay now</button>

Submission is formless: the checkout runtime never submits a <form>. It listens for a click on [data-checkout-submit] (or .checkout-button), calls preventDefault(), and collects every named / data-template-value field from the page wrapper. type="submit", method="POST" and form="..." are cosmetic.

`<checkout-cc-panel>` attributes

Written on the custom tag, these are read server-side and re-emitted onto the generated <div class="checkout-cc-panel">:

Attribute	Values	Default	Description
`data-accepted-cards`	Comma-separated card names	`visa,mastercard,amex,discover`	Card brands shown in the payment tab and validated during input. Supported: `visa`, `mastercard`, `amex`, `discover`, `diners`, `jcb`
`data-applepay`	`"false"` to disable	enabled	When `"false"`, Apple Pay is not rendered inside this panel. See the caveat below.
`data-applepay-force`	`"true"`	—	Pre-renders a native `<apple-pay-button>` placeholder and sets `checkout.wallet_visible` immediately
`data-paypal`	Merchant ID	—	Enables PayPal tab (resolved server-side)
`data-klarna`	Merchant ID	—	Enables Klarna tab (resolved server-side)

The panel builds its UI client-side from these attributes and efScope.checkout. When PayPal, Klarna, or the Apple Pay tab is active, the panel renders as a tabbed accordion; otherwise it renders card fields only.

data-applepay-layout is not in this list. The client-side panel does read data-applepay-layout ("separated", "tab", "inline", or unset for auto), but the server-side tag expander does not forward it — the generated <div> carries only the attributes above. Setting it on <checkout-cc-panel> has no effect. Use <checkout-wallet /> for an above-the-panel wallet.

data-applepay="false" does not always suppress Google Pay. On NMI, a #googlePay container is still injected when the visitor is on Android. On Stripe, both wallets share one mount point, so it disables both.

Layout selection

With no wallet tag elsewhere on the page, the panel picks its layout automatically:

Condition	Layout
HTTPS, gateway is NMI or Stripe, `data-applepay` not `"false"`, and no `#applePay` already in the DOM	Apple Pay as a radio tab alongside Card (and PayPal / Klarna). The tab relabels to Google Pay if that is what gets detected.
Any of the above not met	Legacy inline layout — wallet containers above the card fields with an `or pay with card` divider

Because the tab layout requires that no #applePay element already exists, adding <checkout-wallet /> anywhere on the page automatically stops the panel from rendering its own wallet tab.

Smart field detection

The card panel automatically detects which checkout fields are present on the page and fills in any gaps:

Cardholder name: If first_name or last_name is missing from the page, a “Cardholder Name” field appears inside the card panel. Note this checks only that pair — shipping_first_name / shipping_last_name do not satisfy it.
Billing block: If neither billing_zip nor shipping_zip is on the page, the card panel renders a billing block containing a Country select and a ZIP / postal code input. It never adds a name or street-address field. Which of the two appear is controlled by checkout_settings.billing_fields (section 4.4).
Auto-copy: When billing fields are inside the card panel and no shipping fields exist on the page, billing values are automatically copied to shipping during submission (and vice versa).

This means a minimal checkout page with only email and the payment panel still collects enough billing information for AVS.

Wallet contact field auto-detection

NMI / Collect.js only. On Stripe, the payment request is always created with requestPayerName, requestPayerEmail and requestShipping enabled and no phone request, regardless of which fields are on the page.

Page has	Wallet requests
`shipping_address` or `shipping_country`	Shipping postal address
`billing_address` or `billing_country`	Billing postal address
`first_name`, `shipping_first_name`, or `billing_first_name`	Name
`email`	Email
`phone`	Phone
None of the above (card-only)	No contact fields — just the payment token

Only first-name variants are checked; last_name alone does not trigger the name request. No configuration is needed — for digital products that only need email and payment, the wallet skips address collection entirely.

`<checkout-wallet />`

Standalone wallet placement. Renders <div class="ef-wallet-standalone"> containing both the #applePay and #googlePay containers, so the buttons can sit anywhere on the page:

<checkout-wallet force="true" wallets="apple_pay,google_pay" />
<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>

Attribute	Values	Description
`force`	`"true"`	Pre-renders a native `<apple-pay-button>` placeholder so iOS shows it immediately, and sets `checkout.wallet_visible` to `true` without waiting for detection
`wallets`	`apple_pay`, `google_pay` (comma-separated)	Restricts which wallets are allowed. Emitted as `data-wallets` and used for Stripe’s `disableWallets`

Both are plain attributes, not data- prefixed. The tag may be self-closing. <checkout-apple-pay /> is the legacy single-wallet form of this tag. It accepts force="true" and renders only the Apple Pay container. Prefer <checkout-wallet /> on new pages.

<checkout-wallet> and <checkout-apple-pay> accept a self-closing form. The other checkout tags — <checkout-cc-panel>, <checkout-personal-details>, <checkout-details>, <checkout-bump> — require an explicit closing tag. Written self-closing they are neither expanded nor stripped, and pass through to the browser as unknown markup.

Tag content handling

Tag	Children you write inside it
`<checkout-personal-details>`	Preserved, rendered through the template engine, and appended after the fields the tag generates
`<checkout-details>`	Same — appended after the generated shipping / billing fields
`<checkout-cc-panel>`	Discarded. The tag is replaced by an empty `<div>` that the client-side panel fills in

<checkout-personal-details> and <checkout-details> generate their own inputs (from data-fields and data-shipping-fields respectively) — you do not write the inputs yourself. <checkout-personal-details> attributes

Attribute	Values	Default
`data-fields`	Comma-separated: `email`, `phone`, `first_name`, `last_name`	`email,phone`

<checkout-details> attributes

Attribute	Description
`data-shipping-fields`	Which shipping fields to render
`data-countries`	Country allowlist for the dropdown
`data-theme-class`	Extra class applied to the generated container
`data-input-style`, `data-label-style`	Inline style strings applied to generated inputs / labels
`data-input-border-color`, `data-input-bg-color`, `data-input-text-color`, `data-input-focus-border-color`, `data-input-focus-shadow-color`, `data-input-border-radius`, `data-input-padding`	Generated input theming
`data-label-color`, `data-label-bg-color`, `data-label-active-color`, `data-label-font-size`, `data-label-font-weight`	Generated floating-label theming

Wallet conditional display

Key	Meaning
`checkout.wallet_available`	`{ applePay, googlePay }`. Starts `false / false` server-side; updated once the payment library detects support, typically 1-2 seconds after load
`checkout.wallet_visible`	`true` once a wallet button has actually rendered. Only promoted `false` → `true`, never reset. Set immediately by `force="true"`

Prefer wallet_visible for layout decisions — it will not flicker on first paint the way wallet_available does:

<checkout-wallet force="true" />

<template-if data-condition="checkout.wallet_visible">
  <div class="or-divider">or pay another way</div>
</template-if>

<checkout-cc-panel data-accepted-cards="visa,mastercard,amex,discover" data-applepay="false"></checkout-cc-panel>

`window.ef.checkout` API

A small JavaScript API for programmatic wallet control:

Member	Description
`ef.checkout.walletAvailable`	Getter returning the same `{ applePay, googlePay }` as `checkout.wallet_available`
`ef.checkout.payWithWallet(method)`	Triggers `'applePay'` or `'googlePay'` by clicking the matching `[data-wallet]` button. Requires NMI Collect.js; logs a warning if the wallet or button is unavailable
`ef.checkout.onWalletComplete(callback)`	Registers a callback fired after a wallet payment attempt

See Apple Pay and Google Pay for full setup, configuration, and layout examples.

Styling checkout fields

Checkout input fields (floating labels, focus rings, active label color) respond to a single CSS variable:

Variable	Default	Controls
`--ef-primary`	`#3b82f6`	Focus border color, focus glow, active floating label color

Set it in the page’s <style> block to match your brand:

<style>
  :root {
    --ef-primary: #FF4500; /* your brand color */
  }
</style>

You can also scope it to a specific container instead of :root:

<style>
  .checkout-form-section {
    --ef-primary: #2b3a5c;
  }
</style>

All standard input fields (ef-floating-input, ef-form-input) and quiz fields (ef-quiz-floating-input) inherit the value automatically. No other changes are needed.

Styling the wallet divider

The divider between the wallet buttons and the card panel uses the ef-wallet-divider classes. The platform emits the text in lowercase — or pay another way in the separated layout, or pay with card in the inline layout — and applies no styling of its own, so define these classes in your page’s <style> block (the text-transform below is what makes it render uppercase):

<style>
  .ef-wallet-divider {
    display: flex;
    align-items: center;
    margin: 1rem 0;
    gap: 0.75rem;
  }
  .ef-wallet-divider-line {
    flex: 1;
    height: 1px;
    background-color: #e5e7eb;
  }
  .ef-wallet-divider-text {
    color: #9ca3af;
    font-size: 13px;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    white-space: nowrap;
  }
</style>

7) After successful payment (redirects)

If the server returns redirectUrl, the visitor is sent there.
Otherwise, the default purchase confirmation route is used (query parameters typically include order and email).

Details: Checkout redirect behavior.

8) Troubleshooting

Issue	What to check
Country/state restriction ignored	`checkout_settings` on backend scope; valid codes; session + server enforcement after page load
Abuse protection never triggers	`enabled: true`; visitor opened checkout page first; thresholds not too high; not upsell-only flow
Too many captchas	Increase `captcha_requests` or `window_ms`; check shared IP / VPN concentration
Hard blocks too aggressive	Increase `hard_block_requests` or `window_ms`; review `block_duration_ms`

How to design a checkout page — build walkthrough and HTML patterns
Frontend Template Engine: Checkout — checkout.* in templates
Frontend Template Engine: Cart — cart lines, bumps, qty controls
Checkout redirect behavior — post-checkout routing
reCAPTCHA setup — site-wide captcha (separate from checkout abuse modal)

​1) Enable checkout on a page

​2) Checkout scope (frontend)

​3) Supported form field names

​4) checkout_settings (backend script)

​4.1 Countries and US states allowlist

​4.2 Example: countries only

​4.3 Example: US states only

​4.4 Card panel billing fields

​4.5 Wallet labels

​5) Checkout abuse protection (card-testing / velocity)

​5.1 Configuration

​5.2 What is protected

​5.3 Session lifecycle

​5.4 Progressive behavior

​5.5 JSON response fields (checkout submit)

​5.6 Tuning and false positives

​6) Payment panel and submit wiring

​<checkout-cc-panel> attributes

​Layout selection

​Smart field detection

​Wallet contact field auto-detection

​<checkout-wallet />

​Tag content handling

​Wallet conditional display

​window.ef.checkout API

​Styling checkout fields

​Styling the wallet divider

​7) After successful payment (redirects)

​8) Troubleshooting

​Related docs

1) Enable checkout on a page

2) Checkout scope (frontend)

3) Supported form field names

4) `checkout_settings` (backend script)

4.1 Countries and US states allowlist

4.2 Example: countries only

4.3 Example: US states only

4.4 Card panel billing fields

4.5 Wallet labels

5) Checkout abuse protection (card-testing / velocity)

5.1 Configuration

5.2 What is protected

5.3 Session lifecycle

5.4 Progressive behavior

5.5 JSON response fields (checkout submit)

5.6 Tuning and false positives

6) Payment panel and submit wiring

`<checkout-cc-panel>` attributes

Layout selection

Smart field detection

Wallet contact field auto-detection

`<checkout-wallet />`

Tag content handling

Wallet conditional display

`window.ef.checkout` API

Styling checkout fields

Styling the wallet divider

7) After successful payment (redirects)

8) Troubleshooting

Related docs