tonder-web-sdk 1.16.15 → 2.0.0

package/README.md

@@ -1,1059 +1,1493 @@
-# Tonder SDK
+# tonder-web-sdk
 
-Tonder SDK helps to integrate the services Tonder offers in your own website
+PCI DSS–compliant payment SDK for web applications.
+Card data is collected through **Skyflow secure iframes** — raw card values never touch your application code.
 
 ## Table of Contents
 
-1. [Installation](#installation)
-2. [Usage](#usage)
-   - [InlineCheckout](#inlinecheckout)
-   - [LiteCheckout](#litecheckout)
-3. [Configuration Options](#configuration)
-   - [Inline Options](#inline-options)
-   - [Lite Options](#lite-options)
-4. [Styling InlineCheckout](#styling-inlinecheckout)
-5. [Payment Data Structure](#payment-data-structure)
-6. [Field Validation Functions](#field-validation-functions)
-7. [HMAC Signature Validation](#hmac-signature-validation)
-8. [API Reference](#api-reference)
-9. [Examples](#examples)
-10. [License](#license)
+1. [Quick Start](#1-quick-start)
+2. [Installation](#2-installation)
+3. [Choosing an Integration](#3-choosing-an-integration)
+4. [Constructor & Configuration](#4-constructor--configuration)
+   - [4.1 InlineCheckout options](#41-inlinecheckout-options)
+   - [4.2 LiteInlineCheckout options](#42-liteinlinecheckout-options)
+   - [4.3 Secure token](#43-secure-token)
+   - [4.4 Form events](#44-form-events-icardvents)
+5. [Initialization Sequence](#5-initialization-sequence)
+6. [Collecting Card Data — `mountCardFields`](#6-collecting-card-data--mountcardfields-liteinlinecheckout)
+   - [6.1 New-card form (all 5 fields)](#61-new-card-form-all-5-fields)
+   - [6.2 Saved-card CVV only](#62-saved-card-cvv-only)
+   - [6.3 Unmounting fields](#63-unmounting-fields)
+7. [Processing Payments](#7-processing-payments)
+   - [7.1 New card](#71-new-card-payment)
+   - [7.2 Pay with a saved card](#72-pay-with-a-saved-card)
+   - [7.3 Alternative Payment Method (APM)](#73-alternative-payment-method-apm)
+   - [7.4 Payment response reference](#74-payment-response-reference)
+8. [3DS Handling](#8-3ds-handling)
+9. [Managing Saved Cards](#9-managing-saved-cards-liteinlinecheckout)
+   - [9.1 List saved cards](#91-list-saved-cards)
+   - [9.2 Save a new card (enrollment)](#92-save-a-new-card-enrollment)
+   - [9.3 Remove a card](#93-remove-a-card)
+10. [Revealing Card Data — `revealCardFields`](#10-revealing-card-data--revealcardfields-liteinlinecheckout)
+11. [Error Handling](#11-error-handling)
+    - [11.1 Error structure](#111-error-structure)
+    - [11.2 Error code reference](#112-error-code-reference)
+12. [Customization & Styling](#12-customization--styling)
+    - [12.1 InlineCheckout styles](#121-inlinecheckout-styles)
+    - [12.2 LiteInlineCheckout styles](#122-liteinlinecheckout-styles)
+    - [12.3 Labels & placeholders](#123-labels--placeholders-liteinlinecheckout)
+    - [12.4 InlineCheckout UI customization](#124-inlinecheckout-ui-customization)
+13. [Framework Examples](#13-framework-examples)
+    - [13.1 Vanilla JS — InlineCheckout](#131-vanilla-js--inlinecheckout)
+    - [13.2 Vanilla JS — LiteInlineCheckout](#132-vanilla-js--liteinlinecheckout)
+    - [13.3 React / Next.js](#133-react--nextjs)
+    - [13.4 Angular](#134-angular)
+14. [HMAC Signature Validation](#14-hmac-signature-validation)
+15. [Deprecated API](#15-deprecated-api)
+16. [License](#16-license)
+
+---
+
+## 1. Quick Start
+
+Get a working payment form in under 5 minutes using **InlineCheckout** (pre-built UI):
 
-## Installation
+```html
+<!-- index.html -->
+<script src="https://js.skyflow.com/v1/index.js"></script>
+
+<!-- Checkout mounts here -->
+<div id="tonder-checkout"></div>
+```
+
+```js
+import { InlineCheckout } from "tonder-web-sdk";
+
+const checkout = new InlineCheckout({
+  apiKey: "YOUR_PUBLIC_API_KEY",
+  mode: "stage",
+  returnUrl: `${window.location.origin}/checkout`,
+});
+
+// Fetch a secure token from your backend (see Section 4.3)
+const { access } = await fetch("/api/tonder-secure-token", { method: "POST" }).then((r) =>
+  r.json()
+);
+
+checkout.configureCheckout({
+  customer: { email: "user@example.com" },
+  secureToken: access,
+});
+
+await checkout.injectCheckout();
+
+// Handle returning from a 3DS redirect
+const tdsResult = await checkout.verify3dsTransaction();
+if (tdsResult) {
+  console.log("3DS result:", tdsResult.transaction_status);
+}
+```
+
+```js
+// Trigger payment from your own Pay button
+const response = await checkout.payment({
+  customer: { firstName: "John", lastName: "Doe", email: "user@example.com" },
+  cart: { total: 100, items: [{ name: "Product A", description: "...", quantity: 1, price_unit: 100, discount: 0, taxes: 0, product_reference: "SKU-001", amount_total: 100 }] },
+  currency: "MXN",
+});
+console.log("Transaction status:", response.transaction_status);
+```
+
+> **Security note:** `YOUR_SECRET_API_KEY` is a server-side credential. In production, fetch the secure token from your own backend and return only the `access` value to the client. See [Section 4.3](#43-secure-token).
+
+---
+
+## 2. Installation
 
-You can install the Tonder SDK using NPM or by including it via a script tag.
+Choose **one** of the following installation methods:
 
-### NPM Installation
+### Option A — NPM (recommended for bundlers)
 
 ```bash
-npm i tonder-web-sdk
+npm install tonder-web-sdk
+# or
+yarn add tonder-web-sdk
 ```
 
-### Script Tag Installation
+```js
+import { InlineCheckout } from "tonder-web-sdk";
+```
+
+### Option B — Script Tag (no bundler)
+
+Choose the URL that matches your environment:
 
 ```html
-<script src="https://zplit-prod.s3.amazonaws.com/v1/bundle.min.js"></script>
+<!-- Stage -->
+<script src="https://zplit-stage.s3.amazonaws.com/v2/bundle.min.js"></script>
+
+<!-- Production -->
+<script src="https://zplit-prod.s3.amazonaws.com/v2/bundle.min.js"></script>
 ```
 
-### Dependencies
+Both URLs expose `window.TonderSdk`. Use one at a time:
+
+```js
+// InlineCheckout
+const { InlineCheckout } = window.TonderSdk;
+
+// or LiteInlineCheckout
+const { LiteInlineCheckout } = window.TonderSdk;
+```
 
-Add dependencies to the root of the app (index.html)
+### Required Dependencies
+
+Add these scripts to the `<head>` of every page that uses the SDK:
 
 ```html
 <script src="https://js.skyflow.com/v1/index.js"></script>
-<script src="https://openpay.s3.amazonaws.com/openpay.v1.min.js"></script>
-<script src="https://openpay.s3.amazonaws.com/openpay-data.v1.min.js"></script>
 ```
 
-## Usage
+---
 
-### InlineCheckout
+## 3. Choosing an Integration
 
-InlineCheckout provides a pre-built, customizable checkout interface.
+| | `InlineCheckout` | `LiteInlineCheckout` |
+|---|---|---|
+| **UI** | Pre-built, fully styled checkout UI | Headless — you own the markup |
+| **Card collection** | Automatically renders Skyflow iframes | You call `mountCardFields()` into your own `<div>` |
+| **Saved cards** | Built-in saved-card list UI | Fetch with `getCustomerCards()`, render yourself |
+| **APMs** | Built-in APM selector UI | Fetch with `getCustomerPaymentMethods()`, render yourself |
+| **Customization** | `customization` options (show/hide sections, dark mode) | Full control over layout and styling |
+| **Best for** | Drop-in checkout with minimal code | Fully custom checkout experiences |
 
-#### HTML Setup
+---
 
-You need to have an element where the inline checkout will be mounted. This should be a DIV element with the ID "tonder-checkout":
+## 4. Constructor & Configuration
 
-```html
-<div>
-  <h1>Checkout</h1>
-  <div id="tonder-checkout"></div>
-</div>
+### 4.1 InlineCheckout options
+
+```js
+import { InlineCheckout } from "tonder-web-sdk";
+
+const checkout = new InlineCheckout(options);
 ```
 
-#### JavaScript Implementation
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `apiKey` | `string` | **Required** | — | Public API key from the Tonder Dashboard |
+| `returnUrl` | `string` | **Required for 3DS** | — | URL the browser returns to after a 3DS redirect |
+| `mode` | `'stage' \| 'production'` | Optional | `'stage'` | Target environment |
+| `styles` | `ICardStyles` | Optional | `undefined` | Card field styles — see [Section 12.1](#121-inlinecheckout-styles) |
+| `customization` | `CustomizationOptions` | Optional | `undefined` | UI controls (show/hide sections, dark mode) — see [Section 12.4](#124-inlinecheckout-ui-customization) |
+| `callbacks` | `IInlineCallbacks` | Optional | `undefined` | `onCancel` callback |
+| `events` | `ICardEvents` | Optional | `undefined` | Per-field `onChange` / `onFocus` / `onBlur` — see [Section 4.4](#44-form-events-icardvents) |
+| `signatures` | `{ transaction?: string; customer?: string }` | Optional | `undefined` | HMAC signatures — see [Section 14](#14-hmac-signature-validation) |
+
+**`IInlineCallbacks`:**
+
+| Callback | Parameters | Description |
+|----------|------------|-------------|
+| `onCancel` | none | Called when the user clicks the cancel button |
+
+**Environment URLs:**
 
-```javascript
-import { InlineCheckout } from "tonder-web-sdk"; // Not required if using script tag
+| `mode` | Base URL |
+|--------|----------|
+| `'stage'` | `https://stage.tonder.io` |
+| `'production'` | `https://app.tonder.io` |
+
+---
+
+### 4.2 LiteInlineCheckout options
+
+```js
+import { LiteInlineCheckout } from "tonder-web-sdk";
+
+const liteCheckout = new LiteInlineCheckout(options);
 ```
 
-```javascript
-// if using script tag, it should be initialized like this
-// new TonderSdk.InlineCheckout
-const inlineCheckout = new InlineCheckout({
-  apiKey: "your-api-key",
-  returnUrl: "https://your-website.com/checkout",
-  styles: customStyles, // Optional, see Styling section
-  signatures: {
-    transaction: "nA6nQXxQ....=", // Optional HMAC signature for transaction
-    customer: "2EVYDI0H5l5v4....="     // Optional HMAC signature for card-related ops
-  }
-});
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `apiKey` | `string` | **Required** | — | Public API key from the Tonder Dashboard |
+| `returnUrl` | `string` | **Required for 3DS** | — | URL the browser returns to after a 3DS redirect |
+| `mode` | `'stage' \| 'production'` | Optional | `'stage'` | Target environment |
+| `customization` | `ILiteCustomization` | Optional | `undefined` | Styles, labels, and placeholders — see [Section 12.2](#122-liteinlinecheckout-styles) |
+| `events` | `ICardEvents` | Optional | `undefined` | Per-field `onChange` / `onFocus` / `onBlur` — see [Section 4.4](#44-form-events-icardvents) |
+| `signatures` | `{ transaction?: string; customer?: string }` | Optional | `undefined` | HMAC signatures — see [Section 14](#14-hmac-signature-validation) |
 
-// The configureCheckout function allows you to set initial information,
-// such as the customer's email, which is used to retrieve a list of saved cards.
-inlineCheckout.configureCheckout({ customer: { email: "example@email.com" } });
+---
 
-// Inject the checkout into the DOM
-inlineCheckout.injectCheckout();
+### 4.3 Secure token
 
-// To verify a 3ds transaction you can use the following method
-// It should be called after the injectCheckout method
-// The response status will be one of the following
-// ['Declined', 'Cancelled', 'Failed', 'Success', 'Pending', 'Authorized']
+The secure token is a short-lived credential required for `configureCheckout`. Fetch it from Tonder's API using your **secret API key**:
 
-inlineCheckout.verify3dsTransaction().then((response) => {
-  console.log("Verify 3ds response", response);
-});
+```js
+// Base URL by mode: stage → https://stage.tonder.io, production → https://app.tonder.io
+const baseUrl = "https://stage.tonder.io";
+
+const { access } = await fetch(`${baseUrl}/api/secure-token/`, {
+  method: "POST",
+  headers: {
+    Authorization: "Token YOUR_SECRET_API_KEY",
+    "Content-Type": "application/json",
+  },
+}).then((r) => r.json());
+```
+
+> **Security note:** `YOUR_SECRET_API_KEY` is a server-side credential. In production, make this request from your own backend and return only the `access` token to the frontend. Never expose your secret key in client-side code.
+
+---
+
+### 4.4 Form events (`ICardEvents`)
+
+Register callbacks to react to field state changes. Works the same way for both `InlineCheckout` and `LiteInlineCheckout`.
+
+```js
+const events = {
+  cardNumberEvents: {
+    onChange: ({ isValid, isEmpty }) => {
+      setCardValid(isValid);
+    },
+    onBlur: ({ isValid, isEmpty }) => {
+      setShowCardError(!isValid && !isEmpty);
+    },
+  },
+  cvvEvents: {
+    onChange: ({ isValid }) => {
+      setCvvValid(isValid);
+    },
+  },
+};
+
+new InlineCheckout({ ..., events });
+// or
+new LiteInlineCheckout({ ..., events });
 ```
 
-```javascript
-// Process a payment
-const response = await inlineCheckout.payment(checkoutData);
+**`ICardEvents` shape:**
+
+```js
+{
+  cardHolderEvents?: { onChange?, onFocus?, onBlur? },
+  cardNumberEvents?: { onChange?, onFocus?, onBlur? },
+  cvvEvents?:        { onChange?, onFocus?, onBlur? },
+  monthEvents?:      { onChange?, onFocus?, onBlur? },
+  yearEvents?:       { onChange?, onFocus?, onBlur? },
+}
 ```
 
-### LiteCheckout
+**Event payload (`ICardEventPayload`):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `elementType` | `string` | Field name (e.g. `'CARD_NUMBER'`, `'CVV'`) |
+| `isEmpty` | `boolean` | `true` when the field has no input |
+| `isFocused` | `boolean` | `true` when the field currently has focus |
+| `isValid` | `boolean` | `true` when the field passes validation |
+| `value` | `string` | See PCI note below |
 
-LiteCheckout allows you to build a custom checkout interface using Tonder's core functionality.
+> **PCI note:** In `production`, `card_number` returns a **partially masked** value (first 8 digits for non-AMEX, first 6 for AMEX, rest masked). All other fields — including `cvv` — return `value: ''`. In `stage`/`development`, all fields return the actual value. Use `isValid` and `isEmpty` for UI state logic — never depend on `value` for business logic in production.
 
-```javascript
-import { LiteCheckout } from "tonder-web-sdk";
+---
+
+## 5. Initialization Sequence
+
+Both checkouts must be initialized in this exact order:
+
+```
+1. new InlineCheckout(options)  /  new LiteInlineCheckout(options)
+         ↓
+2. Fetch secure token from YOUR backend  →  { access: string }
+         ↓
+3. configureCheckout({ customer, secureToken, ...optional })
+         ↓
+4. await injectCheckout()
+         ↓
+5. result = await verify3dsTransaction()
+         ↓ if result → handle 3DS return; if void → continue ↓
+6. (LiteInlineCheckout only) await mountCardFields(...)
 ```
 
-```javascript
-const liteCheckout = new LiteCheckout({
-  apiKey: "your-api-key", // Your api key getted from Tonder Dashboard
-  returnUrl: "http://your-website.com/checkout",
-  signatures: {
-    transaction: "nA6nQXxQ....=", // Optional HMAC signature for transaction
-    customer: "2EVYDI0H5l5v4....="     // Optional HMAC signature for card-related ops
-  }
+### `configureCheckout(data)`
+
+Sets the customer identity and secure token. You can also pass payment defaults here — any field provided again in `payment()` overrides them.
+
+```js
+checkout.configureCheckout({
+  customer: { email: "user@example.com" },  // Required
+  secureToken: access,                       // Required — from the token fetch
+  // Optional payment defaults:
+  // cart: { total: 100, items: [...] },
+  // currency: "MXN",
+  // metadata: { order_id: "ORD-001" },
 });
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `customer` | `{ email: string }` or full `ICustomer` | **Required** | Customer identity |
+| `secureToken` | `string` | **Required** | Short-lived token from `/api/secure-token/` |
+| `cart` | `{ total, items }` | Optional | Can be set here or overridden in `payment()` |
+| `currency` | `string` | Optional | ISO currency code (e.g. `'MXN'`) |
+| `metadata` | `Record<string, any>` | Optional | Reporting fields (see [Section 7.1](#71-new-card-payment)) |
 
-// The configureCheckout function allows you to set initial information,
-// such as the customer's email, which is used to retrieve a list of saved cards.
-inlineCheckout.configureCheckout({ customer: { email: "example@email.com" } });
+### `injectCheckout()`
 
-// Initialize the checkout
-await liteCheckout.injectCheckout();
+Initializes the checkout session. Must be **awaited** before calling `mountCardFields` or `payment`.
+
+```js
+await checkout.injectCheckout();
 ```
 
-```javascript
-// Retrieve customer's saved cards
-const cards = await liteCheckout.getCustomerCards();
+### `verify3dsTransaction()`
+
+Call this on **every page load**. When the page is loaded as a return from a 3DS redirect, it verifies the transaction and resolves with the result. On a normal page load it resolves with `void`.
+
+```js
+const tdsResult = await checkout.verify3dsTransaction();
+
+if (tdsResult) {
+  // Returning from 3DS
+  if (tdsResult.transaction_status === "Success") {
+    // Navigate to order confirmation
+  } else {
+    // Show error to the user
+  }
+  return; // Do not mount card fields — payment flow already completed
+}
+
+// Normal page load — continue initialization
+// (LiteInlineCheckout: proceed to mountCardFields)
 ```
 
-```javascript
-// Save a new card
-const newCard = await liteCheckout.saveCustomerCard(cardData);
+---
+
+## 6. Collecting Card Data — `mountCardFields` (LiteInlineCheckout)
+
+Mounts Skyflow secure iframes into your `<div>` containers. Card values are captured inside the iframe and **never pass through your application code**.
+
+> **Prerequisite:** Container `<div>` elements must exist in the DOM before calling `mountCardFields()`.
+> Must be called after `injectCheckout()` resolves.
+
+```js
+// IMountCardFieldsRequest
+{
+  fields: Array<CardField | { field: CardField, container_id?: string }>,
+  card_id?: string,            // Omit for new card; skyflow_id for saved-card CVV
+  unmount_context?: 'all' | 'current' | 'none' | string,  // default: 'all'
+}
+
+// CardField = 'cardholder_name' | 'card_number' | 'expiration_month' | 'expiration_year' | 'cvv'
 ```
 
-```javascript
-// Remove a saved card
-await liteCheckout.removeCustomerCard(cardId);
+---
+
+### 6.1 New-card form (all 5 fields)
+
+**Default container IDs** (used when no `container_id` is provided):
+
+| Field | Default Container ID |
+|-------|---------------------|
+| `cardholder_name` | `#collect_cardholder_name` |
+| `card_number` | `#collect_card_number` |
+| `expiration_month` | `#collect_expiration_month` |
+| `expiration_year` | `#collect_expiration_year` |
+| `cvv` | `#collect_cvv` |
+
+**HTML:**
+```html
+<div id="collect_cardholder_name"></div>
+<div id="collect_card_number"></div>
+<div id="collect_expiration_month"></div>
+<div id="collect_expiration_year"></div>
+<div id="collect_cvv"></div>
 ```
 
-```javascript
-// Get available payment methods
-const paymentMethods = await liteCheckout.getCustomerPaymentMethods();
+**Shorthand (string array):**
+```js
+await liteCheckout.mountCardFields({
+  fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+});
 ```
 
-```javascript
-// Process a payment
-const paymentResponse = await liteCheckout.payment(paymentData);
+**Custom container IDs:**
+```js
+await liteCheckout.mountCardFields({
+  fields: [
+    { field: "cardholder_name",   container_id: "#my-name" },
+    { field: "card_number",       container_id: "#my-card-number" },
+    { field: "expiration_month",  container_id: "#my-month" },
+    { field: "expiration_year",   container_id: "#my-year" },
+    { field: "cvv",               container_id: "#my-cvv" },
+  ],
+});
 ```
 
-```javascript
-// Verify a 3DS transaction
-const verificationResult = await liteCheckout.verify3dsTransaction();
+> **Container sizing:** Skyflow iframes require explicit dimensions on their containers. Add at minimum `display: block; width: 100%; height: 40px` (or your desired height) to each container `<div>`.
+
+---
+
+### 6.2 Saved-card CVV only
+
+For saved-card payments, mount only the CVV field for the selected card. The default container ID becomes `#collect_cvv_<skyflow_id>`.
+
+```html
+<!-- Use the card's skyflow_id as part of the container ID -->
+<div id="collect_cvv_abc123"></div>
 ```
 
-## Configuration
-### Inline Options
-
-|   Property    |         Type         | Required | Description                                         | Default                                                                                                                                                                                                                                                                                |                                  Description                                  |
-|:-------------:|:--------------------:|----------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------:|
-|     mode      |        string        | Yes      | Environment mode for the SDK                        | stage                                                                                                                                                                                                                                                                                  | Environment mode. Options: 'stage', 'production', 'sandbox'. Default: 'stage' |
-|    apiKey     |        string        | Yes      | Your Tonder Public API key                          |                                                                                                                                                                                                                                                                                        |                    Your API key from the Tonder Dashboard                     |
-|   returnUrl   |        string        | Yes      | URL for 3DS redirect completion                     |                                                                                                                                                                                                                                                                                        |             URL where the checkout form is mounted (used for 3DS)             |
-|    styles     |        object        | No       |                                                     |                                                                                                                                                                                                                                                                                        |        (InlineCheckout only) Custom styles for the checkout interface         |
-| customization | CustomizationOptions | No       | UI customization options                            | `{displayMode: 'light',saveCards: {showSaveCardOption: false,showSaved: false,autoSave: false,},paymentButton: {show: false,text: "Pagar",showAmount: true,},cancelButton: {show: false,text: "Cancelar",},paymentMethods: {show: true,},cardForm: {show: true,},showMessages: true,}` |               Object to customize the checkout behavior and UI.               |
-|   callbacks   |   IInlineCallbacks   | No       | Payment process callback functions                  |
-|  signatures   |        object        | No       | HMAC signatures for transaction and customer fields |
-<details>
-<summary>View Interface Definition</summary>
+```js
+await liteCheckout.mountCardFields({
+  fields: ["cvv"],
+  card_id: "abc123",  // card.fields.skyflow_id
+});
+```
 
-```typescript
-interface IInlineCheckoutBaseOptions {
-  mode?: "production" | "sandbox" | "stage" | "development";
-  apiKey: string;
-  returnUrl: string;
-  callBack?: (response: any) => void;
-  signatures?:{
-    transaction?: string;
-    customer?: string;
-  }
-}
-interface IInlineCheckoutOptions extends IInlineCheckoutBaseOptions {
-  styles?: Record<string, string>;
-  customization?: CustomizationOptions;
-  callbacks?: IInlineCallbacks;
+**Conditional CVV mount pattern:**
+```js
+function handleSelectCard(card) {
+  liteCheckout.mountCardFields({
+    fields: ["cvv"],
+    card_id: card.fields.skyflow_id,
+  });
 }
 ```
-</details>
 
-### Inline Callbacks Structure
+---
 
-| Callback   | Required | Parameters | Description                                | Return        |
-|------------|----------|------------|--------------------------------------------|---------------|
-| `onCancel` | No       | none       | Called when user clicked the cancel button | Promise<void> |
-<details>
-<summary>View Interface Definition</summary>
+### 6.3 Unmounting fields
 
-```typescript
-interface IInlineCallbacks extends IBaseCallback {
-  onCancel?: () => Promise<void>;
-}
-```
-</details>
+`mountCardFields()` automatically unmounts previously mounted fields before mounting new ones — you don't need to call `unmountCardFields()` manually when switching cards.
 
-### Inline Customization Options
-
-| Option                       | Type    | Default    | Description                                                                               |
-|------------------------------|---------|------------|-------------------------------------------------------------------------------------------|
-| **saveCards**                |
-| saveCards.showSaveCardOption | boolean | true       | Shows a checkbox allowing users to choose whether to save their card for future purchases |
-| saveCards.showSaved          | boolean | true       | Displays a list of previously saved cards for the customer                                |
-| saveCards.autoSave           | boolean | false      | Automatically saves the card without showing the save option to the user                  |
-| **paymentButton**            |
-| paymentButton.show           | boolean | true       | Controls the visibility of the payment button                                             |
-| paymentButton.text           | string  | 'Pagar'    | Custom text to display on the payment button                                              |
-| paymentButton.showAmount     | boolean | true       | Shows the payment amount on the button (e.g., "Pay $100")                                 |
-| **cancelButton**             |
-| cancelButton.show            | boolean | true       | Controls the visibility of the cancel button                                              |
-| cancelButton.text            | string  | 'Cancelar' | Custom text to display on the cancel button                                               |
-| **paymentMethods**           |
-| paymentMethods.show          | boolean | true       | Controls the visibility of alternative payment methods section                            |
-| **cardForm**                 |
-| cardForm.show                | boolean | true       | Controls the visibility of the card input form                                            |
-| **General**                  |
-| showMessages                 | boolean | true       | Controls the visibility of error and success messages                                     |
-| displayMode                  | string  | light      | Controls the display mode light or dark                                                   |
+The `unmount_context` parameter controls what gets cleared before new fields mount:
 
-<details>
-<summary>View Interface Definition</summary>
+| `unmount_context` | Behavior |
+|---|---|
+| `'all'` (default) | Unmounts all mounted fields across all contexts |
+| `'current'` | Unmounts only the current context (new-card or the active saved-card CVV) |
+| `'none'` | Does not unmount anything before mounting |
 
-```typescript
-export type CustomizationOptions = {
-  displayMode?: "light" | "dark";
-  saveCards?: {
-    showSaveCardOption?: boolean;
-    showSaved?: boolean;
-    autoSave?: boolean;
-  };
-  paymentButton?: {
-    show?: boolean;
-    text?: string;
-    showAmount?: boolean;
-  };
-  cancelButton?: {
-    show?: boolean;
-    text?: string;
-  };
-  paymentMethods?: {
-    show?: boolean;
-  };
-  cardForm?: {
-    show?: boolean;
-  };
-  showMessages?: boolean;
-};
+The only time you need to call `unmountCardFields()` directly is when **navigating away** from the checkout:
+
+```js
+// Cleanup when leaving the checkout page
+liteCheckout.unmountCardFields();
+// Or remove the whole checkout:
+// checkout.removeCheckout();  (InlineCheckout)
 ```
-</details>
 
-## Lite Options
-
-|  Property  |  Type  | Required | Description                     | Default |                                  Description                                  |
-|:----------:|:------:|----------|---------------------------------|---------|:-----------------------------------------------------------------------------:|
-|    mode    | string | Yes      | Environment mode for the SDK    | stage   | Environment mode. Options: 'stage', 'production', 'sandbox'. Default: 'stage' |
-|   apiKey   | string | Yes      | Your Tonder Public API key      |         |                    Your API key from the Tonder Dashboard                     |
-| returnUrl  | string | Yes      | URL for 3DS redirect completion |         |             URL where the checkout form is mounted (used for 3DS)             |
-| signatures | object | No       | HMAC signatures                 |         | Provide transaction/customer HMAC if your merchant configuration requires it. |
-
-
-## Styling InlineCheckout
-
-You can customize the appearance of InlineCheckout by passing a `styles` object:
-
-```javascript
-const customStyles = {
-  inputStyles: {
-    base: {
-      border: "1px solid #e0e0e0",
-      padding: "10px 7px",
-      borderRadius: "5px",
-      color: "#1d1d1d",
-      marginTop: "2px",
-      backgroundColor: "white",
-      fontFamily: '"Inter", sans-serif',
-      fontSize: "16px",
-      "&::placeholder": {
-        color: "#ccc",
-      },
-    },
-    cardIcon: {
-      position: "absolute",
-      left: "6px",
-      bottom: "calc(50% - 12px)",
-    },
-    complete: {
-      color: "#4caf50",
-    },
-    empty: {},
-    focus: {},
-    invalid: {
-      border: "1px solid #f44336",
-    },
-    global: {
-      "@import":
-        'url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700&display=swap")',
-    },
-  },
-  labelStyles: {
-    base: {
-      fontSize: "12px",
-      fontWeight: "500",
-      fontFamily: '"Inter", sans-serif',
+> **Important:** Never show the new-card form (all 5 fields) and a saved-card CVV field simultaneously. Only one active CVV input per saved card at a time.
+
+---
+
+## 7. Processing Payments
+
+### 7.1 New card payment
+
+**LiteInlineCheckout prerequisite:** Mount all 5 card fields ([Section 6.1](#61-new-card-form-all-5-fields)) and let the user fill them in before calling `payment()`.
+
+```js
+try {
+  const response = await checkout.payment({
+    customer: {
+      firstName: "John",
+      lastName: "Doe",
+      email: "john@example.com",
+      phone: "+1 555 0100",
+      country: "MX",
+      city: "CDMX",
+      street: "123 Main St",
+      state: "CMX",
+      postCode: "06600",
     },
-  },
-  errorTextStyles: {
-    base: {
-      fontSize: "12px",
-      fontWeight: "500",
-      color: "#f44336",
-      fontFamily: '"Inter", sans-serif',
+    cart: {
+      total: 150,
+      items: [
+        {
+          name: "Product A",
+          description: "Product description",
+          quantity: 1,
+          price_unit: 150,
+          discount: 0,
+          taxes: 0,
+          product_reference: "SKU-001",
+          amount_total: 150,
+        },
+      ],
     },
-  },
-  labels: {
-    nameLabel: "Card Holder Name",
-    cardLabel: "Card Number",
-    cvvLabel: "CVC/CVV",
-    expiryDateLabel: "Expiration Date",
-  },
-  placeholders: {
-    namePlaceholder: "Name as it appears on the card",
-    cardPlaceholder: "1234 1234 1234 1234",
-    cvvPlaceholder: "3-4 digits",
-    expiryMonthPlaceholder: "MM",
-    expiryYearPlaceholder: "YY",
-  },
-};
+    currency: "MXN",
+    order_reference: "ORD-001",           // Recommended — shown in Tonder dashboard & exports
+    metadata: { order_id: "ORD-001" },    // Recommended — reporting fields
+  });
+
+  console.log("Transaction status:", response.transaction_status);
+} catch (error) {
+  console.error(error.message, error.detail);
+}
 ```
 
-## Payment Data Structure
+**`IProcessPaymentRequest` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `customer` | `ICustomer` | **Required** | Customer information |
+| `cart` | `{ total, items }` | **Required** | Order total and line items |
+| `currency` | `string` | Optional | ISO currency code (e.g. `'MXN'`) |
+| `order_reference` | `string` | Recommended | Your internal order ID — shown in Tonder dashboard filters and exports |
+| `metadata` | `Record<string, any>` | Recommended | Reporting fields (see below) |
+| `payment_method` | `string` | Optional | APM identifier (e.g. `'Spei'`) — omit for card payments |
+| `card` | `string` | Optional | **LiteInlineCheckout only** — `skyflow_id` of a saved card; omit to pay with mounted card fields |
+| `apm_config` | `object` | Optional | APM-specific config (e.g. Mercado Pago preferences) |
+
+**`ICustomer`:**
+```js
+{
+  firstName: "John",    // Required
+  lastName: "Doe",      // Required
+  email: "john@example.com",  // Required
+  phone: "+1 555 0100",
+  country: "MX",
+  street: "123 Main St",
+  city: "CDMX",
+  state: "CMX",
+  postCode: "06600",
+  address: "123 Main St, CDMX",
+  identification: { type: "CPF", number: "19119119100" },
+}
+```
 
-When calling the `payment` method, use the following data structure:
+**`IItem`:**
+```js
+{
+  name: "Product A",
+  description: "Product description",
+  quantity: 1,
+  price_unit: 150,
+  discount: 0,
+  taxes: 0,
+  product_reference: "SKU-001",
+  amount_total: 150,
+}
+```
 
-### Field Descriptions
+**Metadata for reporting:**
 
-- **customer**: Object containing the customer's personal information to be registered in the transaction.
+| Field | Report column | Description |
+|-------|---------------|-------------|
+| `order_reference` | Business Transaction ID | Merchant's internal order ID |
+| `metadata.order_id` | Business Transaction ID | Takes precedence over `order_reference` when both are provided |
+| `metadata.customer_email` | Customer Email | Overrides the email shown in reports |
+| `metadata.customer_id` | Customer ID | Your internal customer identifier |
+| `metadata.business_user` | Business User | Internal user or system that initiated the payment |
+| `metadata.operation_date` | Operation Date | Business operation date for reconciliation |
 
-- **cart**: Object containing the total amount and an array of items to be registered in the Tonder order.
+---
 
-  - **total**: The total amount of the transaction.
-  - **items**: An array of objects, each representing a product or service in the order.
-    - name: name of the product
-    - price_unit: valid float string with the price of the product
-    - quantity: valid integer string with the quantity of this product
+### 7.2 Pay with a saved card
 
-- **currency**: String representing the currency code for the transaction (e.g., "MXN" for Mexican Peso).
+**LiteInlineCheckout prerequisite:** Mount the CVV field for the selected card ([Section 6.2](#62-saved-card-cvv-only)) before calling `payment()`.
 
-- **metadata**: Object for including any additional information about the transaction. This can be used for internal references or tracking.
+```js
+// Pass the card's skyflow_id as the `card` field
+const response = await liteCheckout.payment({
+  customer: { email: "user@example.com" },
+  cart: { total: 100, items: [...] },
+  currency: "MXN",
+  card: selectedCard.fields.skyflow_id,
+});
+```
 
-- **card**: (for LiteCheckout) Object containing card information. This is used differently depending on whether it's a new card or a saved card:
+For `InlineCheckout`, saved-card selection is handled automatically by the built-in UI.
 
-  - For a new card: Include `card_number`, `cvv`, `expiration_month`, `expiration_year`, and `cardholder_name`.
-  - For a saved card: Include only the `skyflow_id` of the saved card.
-  - This is only used when not paying with a payment_method.
+---
 
-- **payment_method**: (for LiteCheckout) String indicating the alternative payment method to be used (e.g., "Spei"). This is only used when not paying with a card.
+### 7.3 Alternative Payment Method (APM)
 
-- **apm_config**: (Optional) Configuration object for APM-specific options. Only applicable when using alternative payment methods like Mercado Pago.
-<details>
-<summary>APM Config Fields</summary>
-
-| **Field**                           | **Type**                                   | **Description**                                                           |
-|-------------------------------------|--------------------------------------------|---------------------------------------------------------------------------|
-| `binary_mode`                       | `boolean`                                  | If `true`, payment must be approved or rejected immediately (no pending). |
-| `additional_info`                   | `string`                                   | Extra info shown during checkout and in payment details.                  |
-| `back_urls`                         | `object`                                   | URLs to redirect the user after payment.                                  |
-| └─ `success`                        | `string`                                   | Redirect URL after successful payment.                                    |
-| └─ `pending`                        | `string`                                   | Redirect URL after pending payment.                                       |
-| └─ `failure`                        | `string`                                   | Redirect URL after failed/canceled payment.                               |
-| `auto_return`                       | `"approved"` \| `"all"`                    | Enables auto redirection after payment completion.                        |
-| `payment_methods`                   | `object`                                   | Payment method restrictions and preferences.                              |
-| └─ `excluded_payment_methods[]`     | `array`                                    | List of payment methods to exclude.                                       |
-| └─ `excluded_payment_methods[].id`  | `string`                                   | ID of payment method to exclude (e.g., "visa").                           |
-| └─ `excluded_payment_types[]`       | `array`                                    | List of payment types to exclude.                                         |
-| └─ `excluded_payment_types[].id`    | `string`                                   | ID of payment type to exclude (e.g., "ticket").                           |
-| └─ `default_payment_method_id`      | `string`                                   | Default payment method (e.g., "master").                                  |
-| └─ `installments`                   | `number`                                   | Max number of installments allowed.                                       |
-| └─ `default_installments`           | `number`                                   | Default number of installments suggested.                                 |
-| `expires`                           | `boolean`                                  | Whether the preference has expiration.                                    |
-| `expiration_date_from`              | `string` (ISO 8601)                        | Start of validity period (e.g. `"2025-01-01T12:00:00-05:00"`).            |
-| `expiration_date_to`                | `string` (ISO 8601)                        | End of validity period.                                                   |
-| `differential_pricing`              | `object`                                   | Configuration for differential pricing.                                   |
-| └─ `id`                             | `number`                                   | ID of the differential pricing strategy.                                  |
-| `marketplace`                       | `string`                                   | Marketplace identifier (default: "NONE").                                 |
-| `marketplace_fee`                   | `number`                                   | Fee to collect as marketplace commission.                                 |
-| `tracks[]`                          | `array`                                    | Ad tracking configurations.                                               |
-| └─ `type`                           | `"google_ad"` \| `"facebook_ad"`           | Type of tracker.                                                          |
-| └─ `values.conversion_id`           | `string`                                   | Google Ads conversion ID.                                                 |
-| └─ `values.conversion_label`        | `string`                                   | Google Ads label.                                                         |
-| └─ `values.pixel_id`                | `string`                                   | Facebook Pixel ID.                                                        |
-| `statement_descriptor`              | `string`                                   | Text on payer’s card statement (max 16 characters).                       |
-| `shipments`                         | `object`                                   | Shipping configuration.                                                   |
-| └─ `mode`                           | `"custom"` \| `"me2"` \| `"not_specified"` | Type of shipping mode.                                                    |
-| └─ `local_pickup`                   | `boolean`                                  | Enable pickup at local branch (for `me2`).                                |
-| └─ `dimensions`                     | `string`                                   | Package dimensions (e.g. `10x10x10,500`).                                 |
-| └─ `default_shipping_method`        | `number`                                   | Default shipping method (for `me2`).                                      |
-| └─ `free_methods[]`                 | `array`                                    | Shipping methods offered for free (for `me2`).                            |
-| └─ `free_methods[].id`              | `number`                                   | ID of free shipping method.                                               |
-| └─ `cost`                           | `number`                                   | Shipping cost (only for `custom` mode).                                   |
-| └─ `free_shipping`                  | `boolean`                                  | If `true`, shipping is free (`custom` only).                              |
-| └─ `receiver_address`               | `object`                                   | Shipping address.                                                         |
-| └─ `receiver_address.zip_code`      | `string`                                   | ZIP or postal code.                                                       |
-| └─ `receiver_address.street_name`   | `string`                                   | Street name.                                                              |
-| └─ `receiver_address.street_number` | `number`                                   | Street number.                                                            |
-| └─ `receiver_address.city_name`     | `string`                                   | City name.                                                                |
-| └─ `receiver_address.state_name`    | `string`                                   | State name.                                                               |
-| └─ `receiver_address.country_name`  | `string`                                   | Country name.                                                             |
-| └─ `receiver_address.floor`         | `string`                                   | Floor (optional).                                                         |
-| └─ `receiver_address.apartment`     | `string`                                   | Apartment or unit (optional).                                             |
-</details>
+No `mountCardFields()` call is needed for APM payments.
 
-Note: The exact fields required may vary depending on whether you're using InlineCheckout or LiteCheckout, and the specific payment method being used.
-
-
-```javascript
-const paymentData = {
-  customer: {
-    firstName: "John",
-    lastName: "Doe",
-    country: "USA",
-    address: "123 Main St",
-    city: "Anytown",
-    state: "CA",
-    postCode: "12345",
-    email: "john.doe@example.com",
-    phone: "1234567890",
-    identification:{
-      type: "CPF",
-      number: "19119119100"
-    }
-  },
-  cart: {
-    total: "100.00",
-    items: [
-      {
-        description: "Product description",
-        quantity: 1,
-        price_unit: "100.00",
-        discount: "0.00",
-        taxes: "0.00",
-        product_reference: "PROD123",
-        name: "Product Name",
-        amount_total: "100.00",
-      },
-    ],
-  },
+```js
+// 1. Fetch available APMs
+const apms = await liteCheckout.getCustomerPaymentMethods();
+// IPaymentMethod: { id, payment_method, priority, category, icon, label }
+
+// 2. User selects an APM
+
+// 3. Pay
+const response = await liteCheckout.payment({
+  customer: { email: "user@example.com" },
+  cart: { total: 100, items: [...] },
   currency: "MXN",
-  metadata: {
-    order_id: "ORDER123",
-  },
-  // For Lite checkout
-  card: {
-    // For a new card:
-    card_number: "4111111111111111",
-    cvv: "123",
-    expiration_month: "12",
-    expiration_year: "25",
-    cardholder_name: "John Doe",
-    // Or for a saved card:
-    skyflow_id: "saved-card-id",
+  payment_method: selectedApm.payment_method,  // e.g. 'Spei'
+});
+```
+
+**Mercado Pago with `apm_config`:**
+```js
+const response = await liteCheckout.payment({
+  ...paymentData,
+  payment_method: "MercadoPago",
+  apm_config: {
+    back_urls: {
+      success: "https://myapp.com/success",
+      pending: "https://myapp.com/pending",
+      failure: "https://myapp.com/failure",
+    },
+    auto_return: "approved",
   },
-  // For Lite checkout
-  payment_method: "Spei",
-};
+});
 ```
 
-## Field Validation Functions
+<details>
+<summary>Full Mercado Pago <code>apm_config</code> fields</summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `binary_mode` | `boolean` | If `true`, payment must be approved or rejected immediately (no pending) |
+| `additional_info` | `string` | Extra info shown during checkout |
+| `back_urls.success` | `string` | Redirect URL after successful payment |
+| `back_urls.pending` | `string` | Redirect URL after pending payment |
+| `back_urls.failure` | `string` | Redirect URL after failed/canceled payment |
+| `auto_return` | `'approved' \| 'all'` | Enable auto-redirect after payment completion |
+| `payment_methods.excluded_payment_methods[].id` | `string` | Payment method to exclude (e.g. `'visa'`) |
+| `payment_methods.excluded_payment_types[].id` | `string` | Payment type to exclude (e.g. `'ticket'`) |
+| `payment_methods.default_payment_method_id` | `string` | Default payment method |
+| `payment_methods.installments` | `number` | Max installments allowed |
+| `payment_methods.default_installments` | `number` | Default installments suggested |
+| `expires` | `boolean` | Whether the preference has an expiration |
+| `expiration_date_from` | `string` (ISO 8601) | Start of validity period |
+| `expiration_date_to` | `string` (ISO 8601) | End of validity period |
+| `statement_descriptor` | `string` | Text on payer's card statement (max 16 chars) |
+| `marketplace` | `string` | Marketplace identifier (default: `'NONE'`) |
+| `marketplace_fee` | `number` | Fee to collect as marketplace commission |
+| `tracks[].type` | `'google_ad' \| 'facebook_ad'` | Ad tracker type |
+| `tracks[].values.conversion_id` | `string` | Google Ads conversion ID |
+| `tracks[].values.pixel_id` | `string` | Facebook Pixel ID |
+| `shipments.mode` | `'custom' \| 'me2' \| 'not_specified'` | Shipping mode |
+| `shipments.cost` | `number` | Shipping cost (custom mode only) |
+| `shipments.free_shipping` | `boolean` | Free shipping flag (custom mode only) |
+| `differential_pricing.id` | `number` | Differential pricing strategy ID |
 
-For LiteCheckout implementations, the SDK provides validation functions to ensure the integrity of card data before submitting:
+</details>
 
-- `validateCardNumber(cardNumber)`: Validates the card number using the Luhn algorithm.
-- `validateCardholderName(name)`: Checks if the cardholder name is valid.
-- `validateCVV(cvv)`: Ensures the CVV is in the correct format.
-- `validateExpirationDate(expirationDate)`: Validates the expiration date in MM/YY format.
-- `validateExpirationMonth(month)`: Checks if the expiration month is valid.
-- `validateExpirationYear(year)`: Validates the expiration year.
+---
+
+### 7.4 Payment response reference
+
+```js
+// IStartCheckoutResponse
+{
+  status: string,
+  message: string,
+  transaction_status: string,   // 'Success' | 'Pending' | 'Declined' | 'Failed'
+  transaction_id: number,
+  payment_id: number,
+  checkout_id: string,
+  is_route_finished: boolean,
+  provider: string,
+  psp_response: Record<string, any>,  // Raw response from the payment processor
+}
+```
 
-Example usage:
+> **Note:** 3DS authentication is handled automatically by the SDK. You do not need to handle redirects manually.
 
-```javascript
-import {
-  validateCardNumber,
-  validateCardholderName,
-  validateCVV,
-  validateExpirationDate,
-} from "tonder-web-sdk";
+---
+
+## 8. 3DS Handling
+
+When a payment requires 3DS authentication, the SDK performs a **full-page redirect** to the bank's authentication page. After authentication, the bank sends the user back to `returnUrl`. On that page load, `verify3dsTransaction()` completes the verification.
 
-const cardNumber = "4111111111111111";
-const cardholderName = "John Doe";
-const cvv = "123";
-const expirationDate = "12/25";
-
-if (
-  validateCardNumber(cardNumber) &&
-  validateCardholderName(cardholderName) &&
-  validateCVV(cvv) &&
-  validateExpirationDate(expirationDate)
-) {
-  // Proceed with payment
-} else {
-  // Show error message
+**How it works:**
+
+1. `payment()` detects the 3DS challenge and redirects the browser to the bank's page
+2. User completes authentication
+3. Bank redirects back to `returnUrl`
+4. Your page calls `verify3dsTransaction()` — it detects the 3DS return, verifies the transaction, and returns the result
+5. If routing is configured and the transaction was declined, it automatically retries with the next payment route
+
+**Implementation pattern (call on every page load):**
+
+```js
+await checkout.injectCheckout();
+
+const tdsResult = await checkout.verify3dsTransaction();
+if (tdsResult) {
+  // Returned from 3DS challenge
+  const { transaction_status } = tdsResult;
+  if (transaction_status === "Success") {
+    showOrderConfirmation();
+  } else {
+    showError(`Payment ${transaction_status}`);
+  }
+  return; // Do not proceed to mounting card fields
 }
-```
 
-## HMAC Signature Validation
+// Normal page load — mount card fields (LiteInlineCheckout) or let InlineCheckout render
+```
 
-Tonder supports **HMAC** validation to ensure the data sent from your application to Tonder is not tampered with.
+---
 
-### Overview
+## 9. Managing Saved Cards (LiteInlineCheckout)
 
-- **HMAC**: A cryptographic method used to validate the integrity of transmitted data.
-- You receive an **API Secret Key** from Tonder.
-- You generate the HMAC signature locally (SHA-256, Base64) based on certain fields.
-- Tonder compares your signature with its own calculation.
-- If invalid, Tonder returns a **403**.
+### 9.1 List saved cards
 
-### Generating the HMAC Signature (JavaScript Example)
-> **Important**: This HMAC generation should be done on your **backend** server, not in client-side code, to keep your secret key secure.
-```javascript
-const crypto = require('crypto');
+```js
+const { cards } = await liteCheckout.getCustomerCards();
+// Returns: ICustomerCardsResponse = { user_id: number, cards: ICard[] }
 
-function generateHMAC(secretKey, requestBody) {
-  // Convert the payload to a JSON string.
-  // Ensure the fields are in alphabetical order if required by your config.
-  const dataString = JSON.stringify(requestBody);
+cards.forEach((card) => {
+  const lastFour = card.fields.card_number.slice(-4);
+  const expiry = `${card.fields.expiration_month}/${card.fields.expiration_year}`;
+  console.log(`${card.fields.card_scheme} •••• ${lastFour} — expires ${expiry}`);
+});
+```
 
-  // Create HMAC using SHA-256, then Base64-encode it.
-  return crypto
-    .createHmac('sha256', secretKey)
-    .update(dataString)
-    .digest('base64');
+**`ICard` shape:**
+
+```js
+{
+  fields: {
+    skyflow_id: string,         // Use this as the card identifier in payment()
+    card_number: string,        // Masked — e.g. 'XXXX-XXXX-XXXX-4242'
+    cardholder_name: string,
+    expiration_month: string,   // e.g. '12'
+    expiration_year: string,    // e.g. '25'
+    card_scheme: string,        // e.g. 'VISA', 'MASTERCARD'
+  },
+  icon?: string,                // URL to card brand image
 }
 
-// Example usage.
-const secretKey = "<MERCHANT_SECRET_KEY>";
-const requestBody = {
-  customer: {
-    email: "user@example.com",
-    firstName: "John",
-    lastName: "Doe",
-  },
-  currency: "mxn",
-  cart: {
-    total: 100,
-    items: [
-      {
-        amount_total: 100,
-        description: "Sample Item",
-      },
-    ],
-  },
-};
+---
 
-const signature = generateHMAC(secretKey, requestBody);
-console.log("Generated HMAC:", signature);
-```
+### 9.2 Save a new card (enrollment)
 
-### Providing the Signature in the SDK
+**Prerequisites:** Mount all 5 card fields (`mountCardFields()` with no `card_id`) and let the user fill them in.
 
-If using the Tonder SDK, include your generated signature in the `signatures` field:
+```js
+// 1. Mount all 5 fields (Section 6.1)
+await liteCheckout.mountCardFields({
+  fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+});
 
-```javascript
-const inlineCheckout = new InlineCheckout({
-  mode: "stage",
-  apiKey: "<YOUR_API_KEY>",
-  returnUrl: "https://your-website.com/checkout",
-  signatures: {
-    transaction: "<Base64 HMAC>", // For payment
-    customer: "<Base64 HMAC>"      // For card ops
-  }
+// 2. User fills in the card form...
+
+// 3. Save the card
+const saved = await liteCheckout.saveCustomerCard();
+console.log("Saved card skyflow_id:", saved.skyflow_id);
+// Returns: { skyflow_id: string, user_id: number }
+
+// 4. Optionally reveal the saved card data (Section 10)
+await liteCheckout.revealCardFields({
+  fields: ["card_number", "cardholder_name", "expiration_month", "expiration_year"],
 });
 ```
 
-The SDK will handle attaching the signature to outgoing requests. If the signature does not match Tonder’s validation, the request will be rejected.
+---
 
-### Providing the Signature in Direct Calls (Without the SDK)
+### 9.3 Remove a card
 
-If you call Tonder’s REST endpoints directly, add headers:
+```js
+await liteCheckout.removeCustomerCard(card.fields.skyflow_id);
 
-- `X-Signature-Transaction: <Base64 HMAC>`
-- `X-Client-Source: <merchant>-sdk` (the agreed-upon source)
+// Refresh the card list
+const { cards } = await liteCheckout.getCustomerCards();
+```
 
-### Important Notes
+---
 
-- Always ensure your JSON structure matches what Tonder expects.
-- If you are required to sign specific fields, confirm you’re only signing those fields **in alphabetical order**.
-- A mismatch results in a **403**.
+## 10. Revealing Card Data — `revealCardFields` (LiteInlineCheckout)
 
+After a successful `saveCustomerCard()` or `payment()` with a new card, use `revealCardFields()` to display card data in your UI through secure iframes — raw values are never exposed to your code.
 
-## API Reference
+> **When to call:** Only after a successful `saveCustomerCard()` or new-card `payment()`.
 
-### InlineCheckout Methods
+**Default container IDs and redaction:**
 
-- `configureCheckout(data)`: Set initial checkout data
-- `injectCheckout()`: Inject the checkout interface into the DOM
-- `payment(data)`: Process a payment
-- `verify3dsTransaction()`: Verify a 3DS transaction
+| Field | Default Container ID | Redaction |
+|-------|---------------------|-----------|
+| `card_number` | `#reveal_card_number` | `MASKED` — e.g. `4111 11•• •••• 1234` |
+| `cardholder_name` | `#reveal_cardholder_name` | `PLAIN_TEXT` |
+| `expiration_month` | `#reveal_expiration_month` | `PLAIN_TEXT` |
+| `expiration_year` | `#reveal_expiration_year` | `PLAIN_TEXT` |
 
-### LiteCheckout Methods
+> **PCI note:** `cvv` cannot be revealed — PCI DSS Requirement 3.2.1 prohibits storing or displaying CVV post-authorization. Redaction levels are fixed by the SDK and cannot be overridden.
 
-- `configureCheckout(data)`: Set initial checkout data
-- `injectCheckout()`: Initialize the checkout
-- `getCustomerCards()`: Retrieve saved cards
-- `saveCustomerCard(cardData)`: Save a new card
-- `removeCustomerCard(cardId)`: Remove a saved card
-- `getCustomerPaymentMethods()`: Get available payment methods
-- `payment(data)`: Process a payment
-- `verify3dsTransaction()`: Verify a 3DS transaction
+> **Container sizing:** Reveal iframes also need explicit dimensions on their containers (e.g. `display: block; width: 100%; height: 26px`).
 
-## Examples
+**Example 1 — Shorthand:**
+```html
+<div id="reveal_cardholder_name"></div>
+<div id="reveal_card_number"></div>
+<div id="reveal_expiration_month"></div>
+<div id="reveal_expiration_year"></div>
+```
+```js
+await liteCheckout.saveCustomerCard();
 
-Here are examples of how to implement Tonder SDK in various JavaScript frameworks:
+await liteCheckout.revealCardFields({
+  fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year"],
+});
+```
 
-### Vanilla JavaScript
+**Example 2 — With `altText`, `label`, and per-field options:**
+```js
+await liteCheckout.revealCardFields({
+  fields: [
+    { field: "card_number",       altText: "•••• •••• •••• ••••", label: "Card Number" },
+    { field: "cardholder_name",   altText: "Loading…", label: "Cardholder" },
+    { field: "expiration_month",  label: "Month" },
+    { field: "expiration_year",   label: "Year" },
+  ],
+});
+```
 
-#### HTML Setup
+**Example 3 — Custom styles (e.g. overlay on a card graphic):**
+```js
+await liteCheckout.revealCardFields({
+  fields: [
+    { field: "card_number",      container_id: "#my-card-number-display" },
+    { field: "cardholder_name",  container_id: "#my-name-display" },
+    { field: "expiration_month", container_id: "#my-month-display" },
+    { field: "expiration_year",  container_id: "#my-year-display" },
+  ],
+  styles: {
+    inputStyles: {
+      base: {
+        color: "#ffffff",
+        fontFamily: '"Courier New", monospace',
+        fontSize: "16px",
+        background: "transparent",
+        border: "none",
+        letterSpacing: "2px",
+      },
+    },
+  },
+});
+```
 
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Tonder Checkout Example</title>
-    <script src="https://js.skyflow.com/v1/index.js"></script>
-    <script src="https://openpay.s3.amazonaws.com/openpay.v1.min.js"></script>
-    <script src="https://openpay.s3.amazonaws.com/openpay-data.v1.min.js"></script>
-    <!-- Only if not use npm package   -->
-    <script src="https://zplit-prod.s3.amazonaws.com/v1/bundle.min.js"></script>
-  </head>
-  <body>
-    <div id="tonder-checkout"></div>
-    <button id="pay-button">Pay Now</button>
+**`IRevealCardFieldsRequest` types:**
+
+```js
+// fields: Array of shorthand strings or per-field objects
+{
+  field: 'card_number' | 'cardholder_name' | 'expiration_month' | 'expiration_year',
+  container_id?: string,   // default: #reveal_<field>
+  altText?: string,        // Placeholder shown before reveal resolves
+  label?: string,          // Label rendered above the field
+  styles?: {               // Per-field style override
+    inputStyles?: { base?, copyIcon?, global? },
+    labelStyles?: { base?, global? },
+    errorTextStyles?: { base?, global? },
+  },
+}
 
-    <script src="your-script.js"></script>
-  </body>
-</html>
+// Top-level styles apply to all fields unless overridden per-field
+styles?: {
+  inputStyles?: { base?, copyIcon?, global? },
+  labelStyles?: { base?, global? },
+  errorTextStyles?: { base?, global? },
+}
 ```
 
-#### InlineCheckout Example (your-script.js)
+> **Style variants:** Reveal elements support only `base`, `copyIcon`, and `global` variants — not `focus`, `complete`, `invalid`, or `empty` (those apply to collect fields only).
 
-```javascript
-import { InlineCheckout } from "tonder-web-sdk";
+---
 
-const apiKey = "your-api-key";
-const returnUrl = "http://your-website.com/checkout";
+## 11. Error Handling
 
-const inlineCheckout = new InlineCheckout({
-  mode: "development",
-  apiKey,
-  returnUrl,
-  styles: customStyles, // Define your custom styles here
-});
+### 11.1 Error structure
 
-inlineCheckout.configureCheckout({ customer: { email: "example@email.com" } });
-inlineCheckout.injectCheckout();
+When a public SDK method fails, it throws a plain error object with the following shape:
 
-inlineCheckout.verify3dsTransaction().then((response) => {
-  console.log("Verify 3ds response", response);
-});
+```js
+{
+  status: "error",
+  code: 400,        // HTTP status code as number
+  message: "...",   // Human-readable description
+  detail: "..." | { ... },  // Additional context from the server
+}
+```
 
-document
-  .getElementById("pay-button")
-  .addEventListener("click", async function () {
-    try {
-      const response = await inlineCheckout.payment(checkoutData);
-      console.log("Payment response:", response);
-      alert("Payment successful");
-    } catch (error) {
-      console.error("Payment error:", error.details);
-      alert("Payment failed");
-    }
-  });
+**Catch pattern:**
+```js
+try {
+  const response = await liteCheckout.payment(data);
+  console.log("Transaction status:", response.transaction_status);
+} catch (error) {
+  console.error(`[${error.code}] ${error.message}`);
+  // Use error.detail for server response details
+}
 ```
 
+For `InlineCheckout.payment()`, the error is a standard `Error` instance with an additional `.details` property:
+```js
+try {
+  await checkout.payment(data);
+} catch (error) {
+  console.error(error.message);
+  console.error(error.details); // IStartCheckoutErrorResponse from the server
+}
+```
 
-#### InlineCheckout with default Tonder Payment button Example (your-script.js)
-> 💡 **Note:** It is important to send all payment data (customer, cart, metadata, etc) when configuring the checkout; this is necessary when using Tonder's default payment button.
+---
 
-```javascript
-import { InlineCheckout } from "tonder-web-sdk";
+### 11.2 Error code reference
 
-const apiKey = "your-api-key";
-const returnUrl = "http://your-website.com/checkout";
+| `code` | HTTP Status | Thrown by | When |
+|--------|-------------|-----------|------|
+| `400` | 400 | `payment()`, `saveCustomerCard()` | Validation error or bad request |
+| `401` | 401 | Any method | Invalid or missing API key |
+| `403` | 403 | Any method | HMAC signature mismatch |
+| `404` | 404 | `getCustomerCards()`, `removeCustomerCard()` | Customer or card not found |
+| `500` | 500 | Any method | Unexpected server error |
 
-const inlineCheckout = new InlineCheckout({
-  mode: "development",
-  apiKey,
-  returnUrl,
-  styles: customStyles,
-  customization: {
-    paymentButton: {
-      show: true
-    }
-  }, // activate default Tonder Payment button
-  callBack: (response) => {
-      console.log('Payment response', response)
-  }  
-});
+---
 
-// It is important to send all payment data (customer, cart, metadata, etc) when configuring the checkout; this is necessary when using Tonder's default payment button.
-inlineCheckout.configureCheckout(
-    { 
-        customer: { email: "example@email.com" },
-        currency: "mxn",
-        cart: {
-            total: 399,
-            items: [
-                {
-                    description: "Black T-Shirt",
-                    quantity: 1,
-                    price_unit: 1,
-                    discount: 0,
-                    taxes: 0,
-                    product_reference: 1,
-                    name: "T-Shirt",
-                    amount_total: 399,
-                },
-            ],
+## 12. Customization & Styling
+
+### 12.1 InlineCheckout styles
+
+Pass styles inside `customization.styles`. Uses `ICardStyles` with optional per-field overrides.
+
+```js
+new InlineCheckout({
+  apiKey: "YOUR_KEY",
+  returnUrl: "https://myapp.com/checkout",
+  customization: {
+    styles: {
+      // Show the card brand icon inside the card number field (default: true)
+      enableCardIcon: true,
+
+      // Global styles applied to all fields
+      cardForm: {
+        inputStyles: {
+          base: {
+            fontFamily: "Inter, sans-serif",
+            fontSize: "14px",
+            color: "#1d1d1f",
+            border: "1px solid #d1d1d6",
+            borderRadius: "8px",
+            padding: "10px 12px",
+            backgroundColor: "#ffffff",
+          },
+          focus: {
+            borderColor: "#6200ee",
+            boxShadow: "0 0 0 3px rgba(98, 0, 238, 0.15)",
+            outline: "none",
+          },
+          complete: { borderColor: "#34c759" },
+          invalid:  { borderColor: "#ff3b30", color: "#ff3b30" },
+          cardIcon: { position: "absolute", left: "6px", bottom: "calc(50% - 12px)" },
+          global: {
+            "@import": 'url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500&display=swap")',
+          },
         },
-        metadata: {}, // Optional
-        order_reference: "" // Optional
-    }
-);
-inlineCheckout.injectCheckout();
+        labelStyles: {
+          base: { fontSize: "12px", fontWeight: "500", color: "#6e6e73", marginBottom: "4px" },
+        },
+        errorStyles: {
+          base: { color: "#ff3b30", fontSize: "11px", marginTop: "4px" },
+        },
+      },
 
-inlineCheckout.verify3dsTransaction().then((response) => {
-  console.log("Verify 3ds response", response);
+      // Per-field overrides — take priority over cardForm
+      cardNumber: {
+        inputStyles: {
+          base: { letterSpacing: "2px" },
+        },
+      },
+      cvv: {
+        inputStyles: {
+          base:    { backgroundColor: "#faf5ff" },
+          invalid: { borderColor: "#e74c3c" },
+        },
+      },
+    },
+  },
 });
 ```
 
+**`ICardStyles` shape:**
+
+```js
+{
+  enableCardIcon?: boolean,      // default: true
+  cardForm?: ICardFormStyles,    // Global styles for all fields
+  cardholderName?: ICardFormStyles,
+  cardNumber?: ICardFormStyles,
+  cvv?: ICardFormStyles,
+  expirationMonth?: ICardFormStyles,
+  expirationYear?: ICardFormStyles,
+}
 
-#### LiteCheckout Example (your-script.js)
+// ICardFormStyles:
+{
+  inputStyles?: {
+    base?, focus?, complete?, invalid?, empty?,
+    cardIcon?,   // Card brand icon position (card_number only)
+    global?,     // CSS @import or global rules
+  },
+  labelStyles?: { base? },
+  errorStyles?: { base? },
+}
+```
 
-```javascript
-import { LiteInlineCheckout } from "tonder-web-sdk";
+> **Backward compatibility:** Passing `styles` at the **root** of `InlineCheckout` options is still supported but **deprecated** — move it to `customization.styles`. If both are provided, `customization.styles` takes precedence. Passing a flat `{ inputStyles, labelStyles, errorTextStyles }` object is also still supported but deprecated — wrap it in `{ cardForm: { ... } }`. See [Section 15](#15-deprecated-api).
 
-const apiKey = "your-api-key";
-const returnUrl = "http://your-website.com/checkout";
+---
 
-const liteCheckout = new LiteInlineCheckout({
-  mode: "development",
-  apiKey,
-  returnUrl,
-});
+### 12.2 LiteInlineCheckout styles
 
-liteCheckout.configureCheckout({ customer: { email: "example@email.com" } });
-liteCheckout.injectCheckout();
+Pass styles inside `customization.styles`. Uses the same `ICardStyles` format:
 
-liteCheckout.verify3dsTransaction().then((response) => {
-  console.log("Verify 3ds response", response);
+```js
+new LiteInlineCheckout({
+  apiKey: "YOUR_KEY",
+  returnUrl: "https://myapp.com/checkout",
+  customization: {
+    styles: {
+      enableCardIcon: true,
+      cardForm: {
+        inputStyles: {
+          base: {
+            border: "1px solid #d1d1d6",
+            borderRadius: "8px",
+            padding: "10px 12px",
+          },
+          focus: {
+            borderColor: "#6200ee",
+            boxShadow: "0 0 0 3px rgba(98, 0, 238, 0.15)",
+          },
+          complete: { borderColor: "#34c759" },
+          invalid:  { borderColor: "#ff3b30" },
+        },
+        labelStyles: {
+          base: { fontSize: "12px", fontWeight: "500", color: "#6e6e73" },
+        },
+        errorStyles: {
+          base: { color: "#ff3b30", fontSize: "11px" },
+        },
+      },
+      // Per-field override
+      cvv: {
+        inputStyles: {
+          base: { borderColor: "#8e44ad", backgroundColor: "#faf5ff" },
+        },
+        labelStyles: {
+          base: { color: "#8e44ad", fontWeight: "600" },
+        },
+      },
+    },
+  },
 });
+```
 
-document
-  .getElementById("lite-payment-form")
-  .addEventListener("submit", async function (event) {
-    event.preventDefault();
-    const cardData = {
-      card_number: document.getElementById("card-number").value,
-      cardholder_name: document.getElementById("card-name").value,
-      expiration_month: document.getElementById("month").value,
-      expiration_year: document.getElementById("year").value,
-      cvv: document.getElementById("cvv").value,
-    };
+---
 
-    try {
-      const paymentData = { ...checkoutData, card: cardData };
-      const response = await liteCheckout.payment(paymentData);
-      console.log("Payment response:", response);
-      alert("Payment successful");
-    } catch (error) {
-      console.error("Payment error:", error);
-      alert("Payment failed");
-    }
-  });
+### 12.3 Labels & placeholders (LiteInlineCheckout)
+
+```js
+new LiteInlineCheckout({
+  customization: {
+    labels: {
+      cardholder_name: "Name on Card",
+      card_number: "Card Number",
+      cvv: "CVC / CVV",
+      expiration_month: "Month",
+      expiration_year: "Year",
+    },
+    placeholders: {
+      cardholder_name: "Name as it appears on the card",
+      card_number: "1234 5678 9012 3456",
+      cvv: "3–4 digits",
+      expiration_month: "MM",
+      expiration_year: "YY",
+    },
+  },
+});
 ```
 
-### React or Nextjs
+---
 
-For React or Nextjs applications, we recommend using a context provider to manage the Tonder instance across your application.
+### 12.4 InlineCheckout UI customization
 
-First, create a TonderProvider:
+Control visibility and behavior of the pre-built checkout UI:
 
-```jsx
-// TonderProvider.jsx
-"use client"; // only for Nextjs
-import React, { createContext, useContext, useState, useEffect } from "react";
-import { InlineCheckout } from "tonder-web-sdk";
+```js
+new InlineCheckout({
+  customization: {
+    displayMode: "light",         // 'light' | 'dark'
+    saveCards: {
+      showSaveCardOption: true,   // Show "Save card" checkbox
+      showSaved: true,            // Show list of saved cards
+      autoSave: false,            // Auto-save without showing the checkbox
+    },
+    paymentButton: {
+      show: true,
+      text: "Pay",
+      showAmount: true,           // Show amount on the button, e.g. "Pay $100"
+    },
+    cancelButton: {
+      show: false,
+      text: "Cancel",
+    },
+    paymentMethods: {
+      show: true,                 // Show APM section
+    },
+    cardForm: {
+      show: true,                 // Show the card form
+    },
+    showMessages: true,           // Show error/success messages
+  },
+});
+```
 
-const TonderContext = createContext();
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `displayMode` | `'light' \| 'dark'` | `'light'` | Color scheme |
+| `saveCards.showSaveCardOption` | `boolean` | `true` | Show "Save this card" checkbox |
+| `saveCards.showSaved` | `boolean` | `true` | Show saved card list |
+| `saveCards.autoSave` | `boolean` | `false` | Silently save the card without showing the option |
+| `paymentButton.show` | `boolean` | `true` | Show the payment button |
+| `paymentButton.text` | `string` | `'Pagar'` | Payment button label |
+| `paymentButton.showAmount` | `boolean` | `true` | Append amount to button label |
+| `cancelButton.show` | `boolean` | `false` | Show the cancel button |
+| `cancelButton.text` | `string` | `'Cancelar'` | Cancel button label |
+| `paymentMethods.show` | `boolean` | `true` | Show APM section |
+| `cardForm.show` | `boolean` | `true` | Show the card form |
+| `showMessages` | `boolean` | `true` | Show validation and status messages |
 
-export const useTonder = () => useContext(TonderContext);
+---
 
-export const TonderProvider = ({ children }) => {
-  const [tonderInstance, setTonderInstance] = useState(null);
+## 13. Framework Examples
 
-  useEffect(() => {
-    const init = async () => {
-      try {
-        const inlineCheckout = new InlineCheckout({
-          mode: "development",
-          apiKey: "your-api-key",
-          returnUrl: "http://your-website.com/checkout",
+### 13.1 Vanilla JS — InlineCheckout
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <script src="https://js.skyflow.com/v1/index.js"></script>
+    <script src="https://zplit-prod.s3.amazonaws.com/v2/bundle.min.js"></script>
+  </head>
+  <body>
+    <div id="tonder-checkout"></div>
+    <button id="pay-btn">Pay</button>
+
+    <script>
+      const { InlineCheckout } = window.TonderSdk;
+
+      const checkout = new InlineCheckout({
+        apiKey: "YOUR_PUBLIC_API_KEY",
+        mode: "stage",
+        returnUrl: window.location.href,
+        customization: {
+          paymentButton: { show: false },
+        },
+      });
+
+      async function init() {
+        // In production, fetch this from your backend
+        const { access } = await fetch("https://stage.tonder.io/api/secure-token/", {
+          method: "POST",
+          headers: { Authorization: "Token YOUR_SECRET_KEY", "Content-Type": "application/json" },
+        }).then((r) => r.json());
+
+        checkout.configureCheckout({
+          customer: { email: "user@example.com" },
+          secureToken: access,
         });
-        setTonderInstance(inlineCheckout);
-      } catch (error) {
-        console.error("Error initializing Tonder:", error);
-      }
-    };
 
-    init();
-  }, []);
+        await checkout.injectCheckout();
 
-  return (
-    <TonderContext.Provider value={tonderInstance}>
-      {children}
-    </TonderContext.Provider>
-  );
-};
+        const tdsResult = await checkout.verify3dsTransaction();
+        if (tdsResult) {
+          alert("Payment " + tdsResult.transaction_status);
+          return;
+        }
+      }
+
+      document.getElementById("pay-btn").addEventListener("click", async () => {
+        try {
+          const response = await checkout.payment({
+            customer: { firstName: "John", lastName: "Doe", email: "user@example.com" },
+            cart: { total: 100, items: [{ name: "Item", description: "Desc", quantity: 1, price_unit: 100, discount: 0, taxes: 0, product_reference: "SKU-1", amount_total: 100 }] },
+            currency: "MXN",
+          });
+          alert("Transaction status: " + response.transaction_status);
+        } catch (e) {
+          alert("Error: " + e.message);
+        }
+      });
+
+      init();
+    </script>
+  </body>
+</html>
 ```
 
-Then, create a TonderCheckout component:
+---
 
-```jsx
-// TonderCheckout.jsx
-"use client"; // only for Nextjs
-import React, { useEffect, useState } from "react";
-import { useTonder } from "./TonderProvider";
+### 13.2 Vanilla JS — LiteInlineCheckout
 
-const TonderCheckout = () => {
-  const tonder = useTonder();
-  const [loading, setLoading] = useState(false);
+This example shows a complete enrollment flow: mount fields → save card → reveal card data.
 
-  useEffect(() => {
-    if (!tonder) return;
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <script src="https://js.skyflow.com/v1/index.js"></script>
+    <script src="https://zplit-prod.s3.amazonaws.com/v2/bundle.min.js"></script>
+    <style>
+      /* Skyflow iframes need explicit dimensions */
+      .card-field { display: block; width: 100%; height: 44px; margin-bottom: 12px; }
+      .reveal-field { display: block; width: 100%; height: 26px; }
+    </style>
+  </head>
+  <body>
+    <!-- Collect iframes mount here -->
+    <div id="collect_cardholder_name" class="card-field"></div>
+    <div id="collect_card_number" class="card-field"></div>
+    <div id="collect_expiration_month" class="card-field"></div>
+    <div id="collect_expiration_year" class="card-field"></div>
+    <div id="collect_cvv" class="card-field"></div>
+    <button id="save-btn">Save Card</button>
+
+    <!-- Reveal iframes mount here after save -->
+    <div id="card-result" style="display:none">
+      <div id="reveal_cardholder_name" class="reveal-field"></div>
+      <div id="reveal_card_number" class="reveal-field"></div>
+      <div id="reveal_expiration_month" class="reveal-field"></div>
+      <div id="reveal_expiration_year" class="reveal-field"></div>
+    </div>
 
-    tonder.configureCheckout({ customer: { email: "example@email.com" } });
-    tonder.injectCheckout();
+    <script>
+      const { LiteInlineCheckout } = window.TonderSdk;
 
-    tonder.verify3dsTransaction().then((response) => {
-      console.log("Verify 3ds response", response);
-    });
+      const liteCheckout = new LiteInlineCheckout({
+        apiKey: "YOUR_PUBLIC_API_KEY",
+        mode: "stage",
+        returnUrl: window.location.href,
+      });
 
-    return () => {
-      if (tonder.removeCheckout) {
-        tonder.removeCheckout();
-      }
-    };
-  }, [tonder]);
+      async function init() {
+        const { access } = await fetch("https://stage.tonder.io/api/secure-token/", {
+          method: "POST",
+          headers: { Authorization: "Token YOUR_SECRET_KEY", "Content-Type": "application/json" },
+        }).then((r) => r.json());
 
-  const handlePayment = async () => {
-    if (!tonder) return;
-    setLoading(true);
-    try {
-      const response = await tonder.payment(paymentData);
-      console.log("Payment successful:", response);
-      alert("Payment successful");
-    } catch (error) {
-      console.error("Payment failed:", error);
-      alert("Payment failed");
-    } finally {
-      setLoading(false);
-    }
-  };
+        liteCheckout.configureCheckout({
+          customer: { email: "user@example.com" },
+          secureToken: access,
+        });
 
-  return (
-    <div>
-      <div id="tonder-checkout"></div>
-      <button onClick={handlePayment} disabled={loading}>
-        {loading ? "Processing..." : "Pay Now"}
-      </button>
-    </div>
-  );
-};
+        await liteCheckout.injectCheckout();
+
+        const tdsResult = await liteCheckout.verify3dsTransaction();
+        if (tdsResult) {
+          alert("Payment " + tdsResult.transaction_status);
+          return;
+        }
+
+        await liteCheckout.mountCardFields({
+          fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+        });
+      }
 
-export default TonderCheckout;
+      document.getElementById("save-btn").addEventListener("click", async () => {
+        try {
+          const saved = await liteCheckout.saveCustomerCard();
+          console.log("Saved skyflow_id:", saved.skyflow_id);
+
+          document.getElementById("card-result").style.display = "block";
+
+          await liteCheckout.revealCardFields({
+            fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year"],
+            styles: {
+              inputStyles: {
+                base: { fontSize: "16px", color: "#1d1d1f", border: "none", background: "transparent" },
+              },
+            },
+          });
+        } catch (e) {
+          alert("Error: " + e.message);
+        }
+      });
+
+      init();
+    </script>
+  </body>
+</html>
 ```
 
-Finally, use it in your checkout component:
+---
 
-```jsx
-"use client";
-import { useEffect, useState } from "react";
-import { useTonder, TonderProvider } from "./TonderProvider";
-import Script from "next/script";
+### 13.3 React / Next.js
 
-export default function TonderCheckout() {
-  return (
-    <div id="checkout">
-      {/*Provider*/}
-      <TonderProvider>
-        <CheckoutContent />
-      </TonderProvider>
-    </div>
-  );
-}
+```jsx
+import { useEffect, useRef } from "react";
+import { LiteInlineCheckout } from "tonder-web-sdk";
 
-function CheckoutContent() {
-  const tonder = useTonder();
-  const [loading, setLoading] = useState(false);
+export default function CheckoutPage() {
+  const checkoutRef = useRef(null);
 
   useEffect(() => {
-    if (!tonder) return;
-    tonder.configureCheckout({ customer: { email: "example@email.com" } });
-    tonder.injectCheckout();
-    tonder.verify3dsTransaction().then((response) => {
-      console.log("Verify 3ds response", response);
+    const liteCheckout = new LiteInlineCheckout({
+      apiKey: process.env.NEXT_PUBLIC_TONDER_API_KEY,
+      mode: "production",
+      returnUrl: `${window.location.origin}/checkout`,
     });
-    return () => {
-      if (tonder.removeCheckout) {
-        tonder.removeCheckout();
+    checkoutRef.current = liteCheckout;
+
+    async function init() {
+      // Fetch secure token from your Next.js API route
+      const { access } = await fetch("/api/tonder-token", { method: "POST" }).then((r) => r.json());
+
+      liteCheckout.configureCheckout({
+        customer: { email: "user@example.com" },
+        secureToken: access,
+      });
+
+      await liteCheckout.injectCheckout();
+
+      const tdsResult = await liteCheckout.verify3dsTransaction();
+      if (tdsResult) {
+        if (tdsResult.transaction_status === "Success") {
+          // router.push('/order-confirmation')
+        }
+        return;
       }
+
+      await liteCheckout.mountCardFields({
+        fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+      });
+    }
+
+    init();
+
+    return () => {
+      // Cleanup on unmount
+      liteCheckout.unmountCardFields();
     };
-  }, [tonder]);
+  }, []);
 
-  const handlePayment = async () => {
-    if (!tonder) return;
-    setLoading(true);
+  async function handlePay() {
     try {
-      const response = await tonder.payment(paymentData);
-      console.log(response);
-      alert("Payment successful");
+      const response = await checkoutRef.current.payment({
+        customer: { firstName: "John", lastName: "Doe", email: "user@example.com" },
+        cart: { total: 100, items: [{ name: "Product", description: "...", quantity: 1, price_unit: 100, discount: 0, taxes: 0, product_reference: "SKU-1", amount_total: 100 }] },
+        currency: "MXN",
+      });
+      console.log("Status:", response.transaction_status);
     } catch (error) {
-      console.error(error);
-      alert("Payment failed");
-    } finally {
-      setLoading(false);
+      console.error(error.message, error.detail);
     }
-  };
+  }
 
   return (
     <div>
-      <div id="tonder-checkout"></div>
-      <button onClick={handlePayment} disabled={loading}>
-        {loading ? "Processing..." : "Pay"}
-      </button>
+      <div id="collect_cardholder_name" style={{ display: "block", width: "100%", height: 44 }} />
+      <div id="collect_card_number"     style={{ display: "block", width: "100%", height: 44 }} />
+      <div id="collect_expiration_month" style={{ display: "block", width: "100%", height: 44 }} />
+      <div id="collect_expiration_year"  style={{ display: "block", width: "100%", height: 44 }} />
+      <div id="collect_cvv"             style={{ display: "block", width: "100%", height: 44 }} />
+      <button onClick={handlePay}>Pay</button>
     </div>
   );
 }
 ```
 
-### Angular
-
-For Angular, we recommend using a service to manage the Tonder instance:
-
-```typescript
-// tonder.service.ts
-import { Injectable } from "@angular/core";
-import { InlineCheckout } from "tonder-web-sdk";
+**Next.js API route** (`/pages/api/tonder-token.js`):
+```js
+// This runs on the server — safe to use the secret key here
+export default async function handler(req, res) {
+  const { access } = await fetch("https://app.tonder.io/api/secure-token/", {
+    method: "POST",
+    headers: {
+      Authorization: `Token ${process.env.TONDER_SECRET_KEY}`,
+      "Content-Type": "application/json",
+    },
+  }).then((r) => r.json());
 
-@Injectable({
-  providedIn: "root",
-})
-export class TonderService {
-  private inlineCheckout: InlineCheckout;
+  res.json({ access });
+}
+```
 
-  constructor(private sdkParameters: IInlineCheckoutOptions) {
-    this.initializeInlineCheckout();
-  }
+---
 
-  private initializeInlineCheckout(): void {
-    this.inlineCheckout = new InlineCheckout({ ...this.sdkParameters });
-  }
+### 13.4 Angular
 
-  configureCheckout(customerData: IConfigureCheckout): void {
-    this.inlineCheckout.configureCheckout({ ...customerData });
-  }
+**Component template:**
+```html
+<!-- Secure iframes — card values never touch your code -->
+<div id="collect_cardholder_name"  class="card-field"></div>
+<div id="collect_card_number"      class="card-field"></div>
+<div id="collect_expiration_month" class="card-field"></div>
+<div id="collect_expiration_year"  class="card-field"></div>
+<div id="collect_cvv"              class="card-field"></div>
+
+<button (click)="pay()" [disabled]="loading">
+  {{ loading ? 'Processing...' : 'Pay' }}
+</button>
+```
 
-  async injectCheckout(): Promise<void> {
-    await this.inlineCheckout.injectCheckout();
-  }
+**Component class:**
+```typescript
+import { Component, OnInit, OnDestroy } from "@angular/core";
+import { LiteInlineCheckout } from "tonder-web-sdk";
 
-  verify3dsTransaction(): Promise<ITransaction | void> {
-    return this.inlineCheckout.verify3dsTransaction();
-  }
+@Component({ selector: "app-checkout", templateUrl: "./checkout.component.html" })
+export class CheckoutComponent implements OnInit, OnDestroy {
+  private liteCheckout!: LiteInlineCheckout;
+  loading = false;
 
-  // Add more functions, for example for lite sdk: get payment methods
+  async ngOnInit() {
+    this.liteCheckout = new LiteInlineCheckout({
+      apiKey: environment.tonderApiKey,
+      mode: "production",
+      returnUrl: `${window.location.origin}/checkout`,
+    });
 
-  // getCustomerPaymentMethods(): Promise<IPaymentMethod[]> {
-  //     return this.liteCheckout.getCustomerPaymentMethods();
-  // }
-}
+    // Fetch from your Angular backend — never expose the secret key on the frontend
+    const { access } = await this.tonderTokenService.getSecureToken().toPromise();
 
-// checkout.component.ts
-import { Component, OnInit, OnDestroy } from "@angular/core";
-import { TonderService } from "./tonder.service";
+    this.liteCheckout.configureCheckout({
+      customer: { email: "user@example.com" },
+      secureToken: access,
+    });
 
-@Component({
-  selector: "app-tonder-checkout",
-  template: `
-    <div id="tonder-checkout"></div>
-    <button (click)="pay()" [disabled]="loading">
-      {{ loading ? "Processing..." : "Pay" }}
-    </button>
-  `,
-  providers: [
-    {
-      provide: TonderInlineService,
-      // Inicialización del SDK de Tonder Inline
-      // Nota: Reemplace estas credenciales con las suyas propias en desarrollo/producción
-      useFactory: () =>
-        new TonderInlineService({
-          apiKey: "11e3d3c3e95e0eaabbcae61ebad34ee5f93c3d27",
-          returnUrl: "http://localhost:4200/checkout/payment?tabPayment=0",
-          mode: "development",
-        }),
-    },
-  ],
-})
-export class TonderCheckoutComponent implements OnInit, OnDestroy {
-  loading = false;
+    await this.liteCheckout.injectCheckout();
 
-  constructor(private tonderService: TonderService) {}
+    const tdsResult = await this.liteCheckout.verify3dsTransaction();
+    if (tdsResult) {
+      // Handle 3DS return
+      return;
+    }
 
-  ngOnInit() {
-    this.initCheckout();
+    await this.liteCheckout.mountCardFields({
+      fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+    });
   }
 
   ngOnDestroy() {
-    // Limpieza del checkout al destruir el componente
-    this.tonderService.removeCheckout();
-  }
-
-  async initCheckout() {
-    this.tonderService.configureCheckout({
-      customer: { email: "example@email.com" },
-    });
-    await this.tonderService.injectCheckout();
-    this.tonderService.verify3dsTransaction().then((response) => {
-      console.log("Verify 3ds response", response);
-    });
+    this.liteCheckout?.unmountCardFields();
   }
 
   async pay() {
     this.loading = true;
     try {
-      const response = await this.tonderService.payment(paymentData);
-      console.log("Payment successful:", response);
-      alert("Payment successful");
+      const response = await this.liteCheckout.payment({
+        customer: { firstName: "John", lastName: "Doe", email: "user@example.com" },
+        cart: {
+          total: 100,
+          items: [{ name: "Product", description: "Desc", quantity: 1, price_unit: 100, discount: 0, taxes: 0, product_reference: "SKU-1", amount_total: 100 }],
+        },
+        currency: "MXN",
+        order_reference: "ORD-001",
+      });
+      console.log("Transaction status:", response.transaction_status);
     } catch (error) {
-      console.error("Payment failed:", error);
-      alert("Payment failed");
+      console.error(error.message);
     } finally {
       this.loading = false;
     }
@@ -1061,25 +1495,181 @@ export class TonderCheckoutComponent implements OnInit, OnDestroy {
 }
 ```
 
-## Notes
+---
 
-### General
+## 14. HMAC Signature Validation
 
-- Replace `'your-api-key'`, `'http://your-website.com/checkout'`, `customStyles`, and `paymentData` with your actual values.
-- The `paymentData` should be defined according to your specific requirements.
+Tonder supports HMAC validation to ensure request data is not tampered with in transit.
 
-### Script Dependencies
+### Overview
 
-For all implementations, ensure you include the necessary scripts:
+- You receive an **API Secret Key** from Tonder
+- You generate an HMAC-SHA256 signature (Base64-encoded) from the request body
+- Tonder compares your signature with its own calculation
+- A mismatch results in a **403**
 
-```html
-<script src="https://js.skyflow.com/v1/index.js"></script>
-<script src="https://openpay.s3.amazonaws.com/openpay.v1.min.js"></script>
-<script src="https://openpay.s3.amazonaws.com/openpay-data.v1.min.js"></script>
-<!-- Only if not use npm package   -->
-<script src="https://zplit-prod.s3.amazonaws.com/v1/bundle.min.js"></script>
+> **Important:** HMAC generation must be done on your **backend server**, not in client-side code.
+
+### Generating the signature (Node.js)
+
+```js
+const crypto = require("crypto");
+
+function generateHMAC(secretKey, requestBody) {
+  const dataString = JSON.stringify(requestBody);
+  return crypto.createHmac("sha256", secretKey).update(dataString).digest("base64");
+}
+
+const secretKey = "YOUR_SECRET_KEY";
+const requestBody = {
+  customer: { email: "user@example.com", firstName: "John", lastName: "Doe" },
+  currency: "mxn",
+  cart: { total: 100, items: [{ amount_total: 100, description: "Item" }] },
+};
+
+const signature = generateHMAC(secretKey, requestBody);
+```
+
+### Providing signatures in the SDK
+
+```js
+const checkout = new InlineCheckout({
+  apiKey: "YOUR_PUBLIC_API_KEY",
+  returnUrl: "https://myapp.com/checkout",
+  signatures: {
+    transaction: "<Base64 HMAC>",  // For payment requests
+    customer: "<Base64 HMAC>",     // For card operations (save, delete)
+  },
+});
+```
+
+> Always confirm with Tonder which fields must be included in the signed payload and whether alphabetical key ordering is required. A mismatch results in a **403**.
+
+---
+
+## 15. Deprecated API
+
+<details>
+<summary>Show deprecated features</summary>
+
+### Raw card data in `payment()` — removed
+
+Passing raw card fields (`card_number`, `cvv`, etc.) to `payment()` is no longer supported. Card data must be collected through Skyflow secure iframes via `mountCardFields()`.
+
+```js
+// ❌ Removed — no longer works
+await liteCheckout.payment({
+  card: {
+    card_number: "4111111111111111",
+    cvv: "123",
+    expiration_month: "12",
+    expiration_year: "25",
+    cardholder_name: "John Doe",
+  },
+  // ...
+});
+
+// ✅ Current — mount fields first, then pay with no card field (new card)
+await liteCheckout.mountCardFields({
+  fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+});
+await liteCheckout.payment({ customer, cart, currency });
+
+// ✅ Or pay with a saved card using its skyflow_id
+await liteCheckout.payment({ customer, cart, currency, card: "skyflow_id_here" });
+```
+
+### `saveCustomerCard(cardData)` — raw data param removed
+
+`saveCustomerCard()` no longer accepts a `cardData` argument. Mount all 5 card fields first.
+
+```js
+// ❌ Removed
+await liteCheckout.saveCustomerCard({ card_number: "...", cvv: "...", ... });
+
+// ✅ Current
+await liteCheckout.mountCardFields({
+  fields: ["cardholder_name", "card_number", "expiration_month", "expiration_year", "cvv"],
+});
+await liteCheckout.saveCustomerCard();
 ```
 
-## License
+### `InlineCheckout` root-level `styles` — deprecated
+
+Passing `styles` at the root of `InlineCheckout` options is deprecated. Move it to `customization.styles`.
+If both are provided, `customization.styles` takes precedence.
+
+```js
+// ⚠️ Deprecated — still works, but will be removed in a future major version
+new InlineCheckout({
+  styles: { cardForm: { inputStyles: { base: { border: "1px solid #ccc" } } } },
+});
+
+// ✅ Current
+new InlineCheckout({
+  customization: {
+    styles: { cardForm: { inputStyles: { base: { border: "1px solid #ccc" } } } },
+  },
+});
+```
+
+### Flat `styles` format in InlineCheckout — deprecated
+
+Passing a flat `{ inputStyles, labelStyles, errorTextStyles }` object inside `styles` is deprecated.
+Use `{ cardForm: { ... } }` instead. Note the key rename: `errorTextStyles` → `errorStyles`.
+
+```js
+// ⚠️ Deprecated
+new InlineCheckout({
+  customization: {
+    styles: {
+      inputStyles: { base: { border: "1px solid #ccc" } },
+      labelStyles: { base: { fontSize: "12px" } },
+      errorTextStyles: { base: { color: "#f44336" } },
+    },
+  },
+});
+
+// ✅ Current
+new InlineCheckout({
+  customization: {
+    styles: {
+      cardForm: {
+        inputStyles: { base: { border: "1px solid #ccc" } },
+        labelStyles: { base: { fontSize: "12px" } },
+        errorStyles: { base: { color: "#f44336" } },
+      },
+    },
+  },
+});
+```
+
+### Field validation functions — no longer needed
+
+The following validation utilities are still exported but are no longer needed. Skyflow secure iframes handle all card field validation internally.
+
+```js
+// No longer needed — Skyflow iframes validate fields automatically
+import {
+  validateCardNumber,
+  validateCardholderName,
+  validateCVV,
+  validateExpirationDate,
+  validateExpirationMonth,
+  validateExpirationYear,
+} from "tonder-web-sdk";
+```
+
+Use the `events.cardNumberEvents.onBlur` / `onChange` callbacks with `{ isValid }` instead — see [Section 4.4](#44-form-events-icardvents).
+
+### `getSkyflowTokens` — removed
+
+The `getSkyflowTokens` helper has been removed. Use `saveCustomerCard()` to tokenize card data, and `revealCardFields()` to display it — see [Section 9.2](#92-save-a-new-card-enrollment) and [Section 10](#10-revealing-card-data--revealcardfields-liteinlinecheckout).
+
+</details>
+
+---
+
+## 16. License
 
-[MIT](https://choosealicense.com/licenses/mit/)
+Copyright © Tonder. All rights reserved.