# Clearpayo

> Free card tokenization for stores built on SpecialX. Card numbers are typed into an iframe served by a separate vault (vault.clearpayo.com); your code only ever sees a token like tok_3cf5d1129ff172c64f290863b6866395.

## For AI agents: integrate in one pass

Add Clearpayo card fields to this store's checkout.
1. Load https://vault.clearpayo.com/sdk.js once on the checkout page.
2. Mount the fields where the card inputs are: ClearpayoFields.mount(el, { layout: "inline", style: { ...match the page's font, border, focus and radius... } }).
3. Remove the old card number / expiry / CVC inputs and any client-side card encryption.
4. On pay: const { token } = await fields.tokenize(); then POST /api/checkout/charge with vault_token: token (everything else unchanged).
5. Show your own error only when err.code === "network"; invalid_* errors are shown inside the fields.
6. If the page has a CSP, allow script-src and frame-src https://vault.clearpayo.com.
Docs: https://checkout.specialx.ai/docs#card-tokenization-with-clearpayo
Full agent guide: https://clearpayo.com/llms.txt

## SDK

- Script: https://vault.clearpayo.com/sdk.js (no build step, no API key in the browser)
- ClearpayoFields.mount(target, options) -> { tokenize(), clear(), focus(), destroy() }
- options.layout: "inline" (one bordered row: number | MM/YY | CVC) or "stacked" (default)
- options.style: fontFamily, fontSize, color, placeholderColor, background, borderColor, focusColor, errorColor, borderRadius, gap, inputHeight, labelColor, dividerColor
- options.fontUrlFamily: Google Font spec, e.g. "Poppins:wght@400;500"
- options.labels / placeholders / messages: { number, exp, cvc } (+ messages.network); options.hideLabels: boolean
- options.onReady(), options.onChange({ complete, empty, brand })
- tokenize() resolves { token, brand, last4, exp_month, exp_year } or rejects with err.code: invalid_number | invalid_exp | invalid_cvc | network | not_ready

## Charging

POST /api/checkout/charge on the store's own origin with { store_id, vault_token: token, email, name, items, shipping, billing }. The platform claims the token for the store and sends the card to the store's payment provider. 3-D Secure, subscriptions, discounts and upsells work as before.

## Rules

- A token is bound to the page origin it was typed on and can only be claimed by the store that owns that origin ({store}.specialx.ai or its custom domains).
- Card data is stored only in the vault (own database and keys, AES-256-GCM). The CVC is deleted after the first authorization (at the latest after 1 hour); unclaimed tokens are deleted after 1 day.
- Styling options only set CSS variables and text inside the iframe. No merchant code runs on the vault origin.

## Links

- Docs: https://checkout.specialx.ai/docs#card-tokenization-with-clearpayo
- Site: https://clearpayo.com