Checkout functionality reference

​

1) Enable checkout on a page

1. Open Page List → Edit Page
2. Enable Is checkout page
3. Save

​

2) Checkout scope (frontend)

​

3) Supported form field names

• first_name, last_name, email
• phone (optional)
• shipping_address, shipping_address2 (optional)
• shipping_country, shipping_city, shipping_state, shipping_zip
• Optional explicit shipping names: shipping_first_name, shipping_last_name

• billing_first_name, billing_last_name
• billing_address, billing_address2, billing_country, billing_city, billing_state, billing_zip

• shipping_same_as_billing → checkout.shipping_same_as_billing

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

​

4) checkout_settings (backend script)

<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

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

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

1. Values are normalized (e.g. uppercase) and validated against built-in lists.
2. Invalid entries are dropped.
3. If nothing valid remains, the full default lists are used (not restricted).
4. 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>

​

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

​

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>

​

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

1. 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).
2. Each qualifying POST /process-checkout is counted per visitor IP inside a checkout-specific bucket (not mixed with generic page-view rate limits).
3. 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.
4. 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

​

5.5 JSON response fields (checkout submit)

​

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

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

​

<checkout-cc-panel> attributes

​

Smart field detection

• Cardholder name: If first_name and last_name inputs are not on the page, a “Cardholder Name” field appears inside the card panel.
• Billing details: If no billing_address or shipping_address inputs are on the page, the card panel shows a billing details section (name, country, address line).
• 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).

​

Wallet contact field auto-detection

​

<checkout-apple-pay />

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

​

Wallet conditional display

<template-if data-condition="checkout.wallet_available.applePay">
  <div style="text-align:center; padding: 20px;">
    <checkout-apple-pay />
    <p>Or fill out the form below</p>
  </div>
</template-if>

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

​

Styling checkout fields

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

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

​

Styling the wallet divider

<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).

​

8) Troubleshooting

​

Related docs

• 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)