> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> A two-step checkout flow optimized for conversion

## Checkout Overview

Waffo Pancake uses a **two-step checkout flow** optimized for conversion. This design collects customer details first, then payment information, reducing abandonment and supporting accurate tax calculation.

***

## Checkout URLs

### Product Purchase Links (Recommended)

Every product gets a permanent purchase link that never expires:

```
https://checkout.waffo.ai/{store-slug}/{product-slug}
```

Test mode:

```
https://checkout.waffo.ai/{store-slug}/{product-slug}/test
```

Just click "Copy Link" in the Dashboard. The link stays the same even when you update the product. A checkout session is created automatically when the customer opens the link.

### Checkout Sessions (API)

For advanced use cases (dynamic pricing, custom metadata, programmatic checkout), create a session via the API:

```
https://checkout.waffo.ai/{store-slug}/checkout/{sessionId}
```

| Component    | Description                             |
| ------------ | --------------------------------------- |
| `store-slug` | Your store's unique URL slug            |
| `sessionId`  | Checkout session identifier (7-day TTL) |

<Note>
  Checkout sessions are generated server-side and lock the product version, pricing, and currency at creation time.
</Note>

***

## Two-Step Flow

<Steps>
  <Step title="Consumer Details" icon="user">
    Collect email, country, and billing info for tax calculation and order processing.
  </Step>

  <Step title="Payment" icon="credit-card">
    Enter card details or use Apple Pay / Google Pay to complete payment.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/waffo/fAGQ8sa2qycWEk2d/images/checkout/checkout-step1.png?fit=max&auto=format&n=fAGQ8sa2qycWEk2d&q=85&s=e7454a2c64f08d42fe0fa1ac4084b712" alt="Checkout page — Consumer details" width="1440" height="900" data-path="images/checkout/checkout-step1.png" />
</Frame>

### Step 1: Consumer Details

Collects information needed for tax calculation and order processing.

**Required Fields:**

| Field         | Purpose                                           |
| ------------- | ------------------------------------------------- |
| Email address | Receipt, account creation, Customer Portal access |
| Country       | Tax jurisdiction determination                    |

**Conditional Fields (Based on Country):**

| Field           | When Shown                                     |
| --------------- | ---------------------------------------------- |
| ZIP/Postal Code | Most countries (US, CA, UK, etc.)              |
| State/Province  | US, CA, AU, IN, and other applicable countries |

**Business Purchase Option:**
Customers can toggle "I'm purchasing as a business" to provide:

* Business name
* Tax ID (for VAT/tax exemption)

### Step 2: Payment

<Frame>
  <img src="https://mintcdn.com/waffo/YbM_n4_eoBfrCsTT/images/checkout/checkout-step2.png?fit=max&auto=format&n=YbM_n4_eoBfrCsTT&q=85&s=e424a83d42c68d5946214be7f18cbbb7" alt="Checkout — Payment" width="1440" height="900" data-path="images/checkout/checkout-step2.png" />
</Frame>

<CardGroup cols={2}>
  <Card title="Card Payment" icon="credit-card">
    * Card number
    * Expiry date (MM/YY)
    * CVC/CVV
    * Cardholder name
  </Card>

  <Card title="Digital Wallets" icon="wallet">
    * Apple Pay (iOS, Safari)
    * Google Pay (Android, Chrome)
    * One-click with biometric auth
  </Card>
</CardGroup>

**Order Summary** is displayed alongside the payment form with product name, image, subtotal, tax, and total.

***

## Subscription Checkout

For subscription products, additional billing information displays:

| Element           | Example                                                |
| ----------------- | ------------------------------------------------------ |
| Billing frequency | "Billed monthly"                                       |
| Recurring amount  | "\$29.00/month"                                        |
| Next billing date | Calculated from today                                  |
| Trial duration    | "7-day free trial" (if the product has trials enabled) |

***

## Customization

Make your checkout page match your brand through the Checkout Settings in your dashboard.

### Logo

Upload a custom logo displayed on the checkout page. Supported formats include PNG, JPG, and SVG.

### Theme Mode

<CardGroup cols={2}>
  <Card title="Light Mode" icon="sun">
    White background, dark text. Best for most brands.
  </Card>

  <Card title="Dark Mode" icon="moon">
    Dark background, light text. Modern aesthetic.
  </Card>
</CardGroup>

Switch between Light and Dark mode presets. Each mode maintains its own set of color values.

### Color Settings

| Setting              | Field Name                | Default (Light) | Default (Dark) |
| -------------------- | ------------------------- | --------------- | -------------- |
| **Primary Color**    | `checkoutColorPrimary`    | #111111         | #FEFDFD        |
| **Background Color** | `checkoutColorBackground` | #F4F4F4         | #111315        |
| **Card Color**       | `checkoutColorCard`       | #FFFFFF         | #181A1B        |
| **Text Color**       | `checkoutColorText`       | #111111         | #FFFFFF        |

### Border Radius

Control the roundness of UI elements with the `checkoutBorderRadius` setting. Default is `8px`. Options range from 0px (sharp corners) to 16px (extra-large rounding).

<Note>
  Ensure sufficient contrast between text and background colors for accessibility. WCAG recommends a contrast ratio of at least 4.5:1.
</Note>

### Store Information

| Option        | Description                              |
| ------------- | ---------------------------------------- |
| Store Name    | Shown in header                          |
| Support Email | For customer questions                   |
| Terms Link    | Link to your terms of service (required) |
| Privacy Link  | Link to your privacy policy (required)   |

***

<h2 id="checkout-language">
  Multi-Language Support
</h2>

The hosted checkout is multilingual and requires no merchant configuration:

* **Automatic detection** — the checkout UI opens in the shopper's browser language and falls back to English when the language isn't supported yet.
* **Shopper choice** — shoppers can switch languages at any time via the selector in the checkout footer.
* **Payment page follows** — the payment page opens in the language the shopper was using when they clicked Pay (22 payment-page languages supported).

The checkout UI supports 19 languages:

| Language              | Code      | Language   | Code |
| --------------------- | --------- | ---------- | ---- |
| English               | `en`      | Italian    | `it` |
| Chinese (Simplified)  | `zh`      | Russian    | `ru` |
| Chinese (Traditional) | `zh-Hant` | Arabic     | `ar` |
| Japanese              | `ja`      | Hindi      | `hi` |
| Korean                | `ko`      | Thai       | `th` |
| German                | `de`      | Vietnamese | `vi` |
| French                | `fr`      | Indonesian | `id` |
| Spanish               | `es`      | Dutch      | `nl` |
| Portuguese            | `pt`      | Polish     | `pl` |
|                       |           | Turkish    | `tr` |

<h3 id="language-priority">
  Language priority
</h3>

When checkout first opens, the UI language is resolved in this order — the first match wins:

| Priority | Source                         | Notes                                                                                                                         |
| -------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| 1        | **Shopper's manual choice**    | Once the shopper picks a language in the footer selector, that choice wins                                                    |
| 2        | **Merchant-specified default** | The [`language`](/api-reference/endpoints/orders/create-checkout-session) parameter passed when creating the checkout session |
| 3        | **Shopper's browser language** | Used when `language` was not provided                                                                                         |
| 4        | **English**                    | Fallback when none of the above match a supported language                                                                    |

<Note>
  Language is fully decoupled from currency — the shopper can switch to any of the 19 supported languages regardless of the order's currency.
</Note>

***

## Processing & Results

After payment submission:

1. **Card validation** -- Luhn check, expiry, CVC verification
2. **3D Secure** -- Bank verification (if required by the issuing bank)
3. **Authorization** -- Charge to card
4. **Order creation** -- Record in system

**Success Page:** Order confirmation number, receipt email notification, next steps, Customer Portal link.

**Failed Page:** Clear error explanation, suggested action, retry button, support contact option.

***

## Error Handling

| Error         | Cause                            | Customer Action    |
| ------------- | -------------------------------- | ------------------ |
| Card declined | Insufficient funds or bank block | Try different card |
| Invalid card  | Incorrect card number            | Check and re-enter |
| Expired card  | Card past expiration             | Use valid card     |
| CVC mismatch  | Wrong security code              | Re-enter CVC       |
| 3DS failed    | Bank verification failed         | Contact bank       |

***

## Test Checkout

Use [Test Mode](/features/test-mode) to try the checkout flow without real charges.

| Card              | Number                | Result   |
| ----------------- | --------------------- | -------- |
| Visa Credit       | `4576 7500 0000 0110` | Success  |
| Mastercard Credit | `2226 9000 0000 0110` | Success  |
| Visa Credit       | `4576 7500 0000 0220` | Declined |

<Note>
  Test mode is indicated by a banner: "Test Mode - No real charges will be made"
</Note>

***

## Merchant of Record Notice

At checkout footer, customers see:

> "This order is processed by our online reseller & Merchant of Record, Waffo Pancake, who also handles order-related inquiries and returns."

This disclosure is required for MoR compliance and helps customers understand the payment relationship.