@inflow_pay/sdk 0.8.0 → 1.1.0

package/README.md

@@ -1,6 +1,14 @@
-# InflowPay Iframe-based Payment SDK
+# InflowPay SDK v2
 
-Accept card payments with a pre-built, secure payment form. Uses an iframe-based architecture for enhanced security and easy integration.
+Accept card payments with a secure, iframe-based payment form. This version delivers **enhanced security** and **automatic 3D Secure handling** - all with just a few lines of code.
+
+## What's Best in This Version
+
+- 🔒 **Iframe Architecture**: Card data never touches your server (PCI compliant)
+- ✨ **Built-in Success UI**: Beautiful success screen automatically shown after payment - fully customizable or replaceable
+- 🎯 **Auto 3D Secure**: SDK handles authentication modals automatically
+- 🚀 **Zero Configuration**: Works out of the box with sensible defaults
+- 🎨 **Fully Customizable**: Match your brand with comprehensive styling options
 
 ## Installation
 
@@ -8,428 +16,312 @@ Accept card payments with a pre-built, secure payment form. Uses an iframe-based
 npm install @inflow_pay/sdk
 ```
 
-Or use via CDN (jsDelivr) - **for vanilla HTML pages only**:
+**CDN Option** (vanilla HTML pages only):
 
 ```html
-<!-- Main SDK (vanilla JavaScript) -->
-<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@0.8.0/dist/sdk.umd.js"></script>
-<script>
-  // SDK is available as window.InflowPaySDK
-  const provider = new InflowPaySDK.InflowPayProvider({
-    config: { apiKey: 'inflow_pub_xxx' }
-  });
-</script>
+<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@1.1.0/dist/sdk.umd.js"></script>
 ```
 
-**Note:** 
-- The example uses exact version `@0.8.0` for production safety (prevents unexpected changes)
-- You can update to newer versions manually when ready (e.g., `@0.8.0`)
-- If you're building a React app (create-react-app, Next.js, etc.), use `npm install` instead of CDN. See [Migration from React SDK](#migration-from-react-sdk) section.
+## Complete Example
 
-## Quick Start
-
-Get started with the iframe-based SDK:
+### Backend: Create Payment
 
 ```javascript
-import { InflowPayProvider } from '@inflow_pay/sdk';
-
-// Step 1: Create InflowPayProvider (same as React's <InflowPayProvider>)
-const provider = new InflowPayProvider({
-  config: { apiKey: 'inflow_pub_xxx', locale: 'en' }  // locale optional, defaults to browser language
-});
+// backend/api/create-payment.js
+app.post("/api/create-payment", async (req, res) => {
+  const response = await fetch("https://api.inflowpay.xyz/api/server/payment", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Inflow-Api-Key": process.env.INFLOW_PRIVATE_KEY,
+    },
+    body: JSON.stringify({
+      products: [{ name: "Product", price: 4999, quantity: 1 }],
+      currency: "EUR",
+      customerEmail: "customer@example.com",
+      firstName: "John",
+      lastName: "Doe",
+      billingCountry: "FR",
+      postalCode: "75001",
+    }),
+  });
 
-// Step 2: Create CardElement (same as React's <CardElement>)
-const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx', // From your backend
-  container: '#card-container',
-  onComplete: (result) => {
-    if (result.status === 'CHECKOUT_SUCCESS') {
-      window.location.href = '/success';
-    }
-  }
+  const data = await response.json();
+  res.json({ paymentId: data.payment.id });
 });
-
-// Step 3: Mount the CardElement
-cardElement.mount();
 ```
 
-## How It Works
+### Frontend: React
 
-1. **Backend**: Create a payment with billing info (your private key)
-2. **Frontend**: Create `InflowPayProvider` with your API key
-3. **Frontend**: Create `CardElement` with the `paymentId`
-4. **User**: Enters card details and submits
-5. **SDK**: Handles tokenization, 3DS, and payment completion
-6. **Your app**: Receives success/error via callback
-
-## Payment Status
+```tsx
+import {
+  InflowPayProvider,
+  CardElement,
+  PaymentResultStatus,
+} from "@inflow_pay/sdk/react";
 
-Payments progress through these statuses:
+export default function CheckoutPage() {
+  const [paymentId, setPaymentId] = useState<string | null>(null);
 
-| Status | Description | Success? |
-|--------|-------------|----------|
-| `CHECKOUT_SUCCESS` | Payment confirmed | ✅ Yes |
-| `PAYMENT_RECEIVED` | Funds received | ✅ Yes |
-| `PAYMENT_SUCCESS` | Complete | ✅ Yes |
-| `PAYMENT_FAILED` | Failed | ❌ No |
+  useEffect(() => {
+    fetch("/api/create-payment", { method: "POST" })
+      .then((res) => res.json())
+      .then((data) => setPaymentId(data.paymentId));
+  }, []);
 
-**Check for success:**
+  if (!paymentId) return <div>Loading...</div>;
 
-```javascript
-if (result.status === 'CHECKOUT_SUCCESS' ||
-    result.status === 'PAYMENT_RECEIVED' ||
-    result.status === 'PAYMENT_SUCCESS') {
-  // Payment successful
+  return (
+    <InflowPayProvider config={{ publicKey: "inflow_pub_xxx" }}>
+      <CardElement
+        paymentId={paymentId}
+        onComplete={(result) => {
+          if (result.status === PaymentResultStatus.SUCCESS) {
+            setTimeout(() => (window.location.href = "/confirmation"), 2000);
+          }
+        }}
+        style={{
+          fontFamily: "Inter",
+          button: { backgroundColor: "#0070F3", textColor: "#FFFFFF" },
+        }}
+      />
+    </InflowPayProvider>
+  );
 }
 ```
 
-## API Reference
-
-### InflowPayProvider
+### Frontend: Vanilla JavaScript
 
-```javascript
-const provider = new InflowPayProvider({
-  config: {
-    apiKey: 'inflow_pub_xxx',  // Required
-    iframeUrl: 'https://...',   // Optional, auto-detected from API key
-    locale: 'en',               // Optional, UI language (default: auto-detected from browser). Supported: en, de, es, fr, it, nl, pl, pt
-    timeout: 30000,             // Optional, default: 30000
-    debug: false                // Optional, default: false
-  }
-});
-```
-
-**Locale:** Use `locale` in config to set UI language (e.g. `'fr'`); omit to use the browser language. Supported: en, de, es, fr, it, nl, pl, pt.
-
-### CardElement
-
-```javascript
-const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',         // Required
-  container: '#card-container', // Required (CSS selector or HTMLElement)
-  
-  // Styling (optional)
-  style: {
-    fontFamily: 'Inter',
-    button: {
-      backgroundColor: '#0070F3',
-      textColor: '#FFFFFF'
-    }
-  },
-  
-  // Custom button text (optional)
-  buttonText: 'Complete Payment',
-  
-  // Custom placeholders (optional)
-  placeholders: {
-    cardNumber: '1234 5678 9012 3456',
-    expiry: 'MM/YY',
-    cvc: 'CVC'
-  },
-  
-  // Callbacks (same as React SDK)
-  onReady: () => {
-    // Card element is mounted and ready
-  },
-  
-  onChange: (state) => {
-    // Track validation state
-    // state.complete - whether form is valid
-  },
-  
-  onComplete: (result) => {
-    // Payment complete (success or failure)
-    if (result.error) {
-      console.error(result.error.message);
-    }
-  },
-  
-  onError: (error) => {
-    // SDK-level errors (network, validation)
-    console.error(error);
-  },
-  
-  onClose: () => {
-    // User closed the payment
-  }
-});
-
-// Mount the CardElement
-cardElement.mount();
-```
-
-### CardElement Methods
-
-#### `mount(): void`
+```html
+<div id="card-container"></div>
 
-Mounts the CardElement to the DOM. This will create and display the iframe.
+<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@1.1.0/dist/sdk.umd.js"></script>
+<script>
+  const provider = new InflowPaySDK.InflowPayProvider({
+    config: { publicKey: "inflow_pub_xxx" },
+  });
 
-```javascript
-cardElement.mount();
+  fetch("/api/create-payment", { method: "POST" })
+    .then((res) => res.json())
+    .then((data) => {
+      const cardElement = provider.createCardElement({
+        paymentId: data.paymentId,
+        container: "#card-container",
+        onComplete: (result) => {
+          if (result.status === InflowPaySDK.PaymentResultStatus.SUCCESS) {
+            setTimeout(() => (window.location.href = "/confirmation"), 2000);
+          }
+        },
+      });
+      cardElement.mount();
+    });
+</script>
 ```
 
-#### `destroy(): void`
+## Built-in Success UI Explained
 
-Destroys the CardElement and cleans up resources.
+The SDK includes a polished success screen that appears automatically after successful payment:
 
-```javascript
-cardElement.destroy();
-```
+**What it shows:**
 
-## HTML Example
+- ✅ Success icon and "Payment successful!" message
+- 💳 Payment amount (when available from your payment data)
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>My Payment Page</title>
-</head>
-<body>
-  <div id="card-container"></div>
-  
-  <script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@0.8.0/dist/sdk.umd.js"></script>
-  <script>
-    // SDK is available as window.InflowPaySDK
-    const provider = new InflowPaySDK.InflowPayProvider({
-      config: { apiKey: 'inflow_pub_xxx' }
-    });
+**Default vs custom:**
 
-    const cardElement = provider.createCardElement({
-      paymentId: 'pay_xxx',
-      container: '#card-container',
-      onComplete: (result) => {
-        if (result.status === InflowPaySDK.PaymentStatus.CHECKOUT_SUCCESS) {
-          alert('Payment successful!');
-        }
-      }
-    });
+- **Default UI** (default): Built-in success screen shows automatically. You don't need to do anything — quick integration, looks great out of the box.
+- **Custom UI:** Set `showDefaultSuccessUI: false` and add your own success UI. Manage the logic in `onComplete`. Full control for custom branding or additional information. Examples below:
 
-    cardElement.mount();
-  </script>
-</body>
-</html>
-```
-
-## Error Handling
-
-Errors are automatically mapped to user-friendly messages:
+_Vanilla JS:_
 
 ```javascript
-cardElement.onComplete = (result) => {
-  if (result.error) {
-    console.log(result.error.message); // User-friendly
-    console.log(result.error.retryable); // Can retry?
-  }
-};
+const cardElement = provider.createCardElement({
+  paymentId: "pay_xxx",
+  container: "#card-container",
+  showDefaultSuccessUI: false,
+  onComplete: (result) => {
+    if (result.status === PaymentResultStatus.SUCCESS) {
+      document.getElementById("card-container").innerHTML = `
+        <div class="custom-success">
+          <h2>Thank you for your purchase!</h2>
+          <p>Order ID: ${result.paymentId}</p>
+        </div>
+      `;
+    }
+  },
+});
 ```
 
-**Common errors:**
+_React:_
 
-- `card_declined` - Card was declined
-- `insufficient_funds` - Not enough funds
-- `invalid_card_number` - Invalid card
-- `THREE_DS_FAILED` - 3DS authentication failed
-
-## 3D Secure
-
-3DS is handled automatically. When required:
+```tsx
+const [result, setResult] = useState<PaymentResult | null>(null);
+
+return (
+  <>
+    {result ? (
+      <div className="custom-success">
+        <h2>Thank you for your purchase!</h2>
+        <p>Your payment was successful.</p>
+      </div>
+    ) : (
+      <InflowPayProvider config={{ publicKey: "inflow_pub_xxx" }}>
+        <CardElement
+          paymentId="pay_xxx"
+          showDefaultSuccessUI={false}
+          onComplete={(res) => {
+            if (res.status === PaymentResultStatus.SUCCESS) {
+              setResult(res);
+            }
+          }}
+        />
+      </InflowPayProvider>
+    )}
+  </>
+);
+```
 
-1. SDK opens a modal with the authentication page
-2. User completes authentication
-3. Modal closes automatically
-4. Your `onComplete` callback receives the final result
+## Payment Flow
 
-**No setup required!** The SDK automatically handles 3DS redirects.
+1. Backend creates payment → returns `paymentId`
+2. Frontend initializes SDK with `paymentId` and public key
+3. User enters card details in secure iframe
+4. SDK tokenizes card and processes payment
+5. 3D Secure authentication (if required) - automatic modal
+6. `onComplete` callback fires → redirect or update UI
 
-## Backend Integration
+## API Reference
 
-Create payments on your backend with your **private key**:
+### InflowPayProvider
 
 ```javascript
-// Your backend (Node.js example)
-const response = await fetch('https://api.inflowpay.xyz/api/server/payment', {
-  method: 'POST',
-  headers: {
-    'Accept': 'application/json',
-    'Content-Type': 'application/json',
-    'X-Inflow-Api-Key': 'inflow_priv_xxx' // Private key
+const provider = new InflowPayProvider({
+  config: {
+    publicKey: "inflow_pub_xxx", // Required
+    locale: "en", // Optional - defaults to browser language
   },
-  body: JSON.stringify({
-    products: [{ name: 'Product', price: 4999, quantity: 1 }],
-    currency: 'EUR',
-    customerEmail: 'customer@example.com',
-    billingCountry: 'FR',
-    postalCode: '75001',
-    firstName: 'John',
-    lastName: 'Doe',
-    purchasingAsBusiness: false,
-    successUrl: 'https://yourdomain.com/success',
-    cancelUrl: 'https://yourdomain.com/cancel'
-  })
 });
-
-const { payment } = await response.json();
-// Send payment.id to your frontend
 ```
 
-See [API documentation](https://docs.inflowpay.com/v0/reference/createpayment) for full backend API reference.
-
-## Migration from React SDK
-
-The iframe-based SDK maintains similar component APIs, but **styling has changed**. You have two options:
+**Supported locales:** `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`, `pt`
 
-### Option 1: Keep Using React (Recommended for React Apps)
-
-If you're using React, you can use the React components with a similar API:
-
-```tsx
-// Change the import path
-import { InflowPayProvider, CardElement } from '@inflow_pay/sdk/react';
+### CardElement
 
-function App() {
-  return (
-    <InflowPayProvider config={{ apiKey: 'inflow_pub_xxx', locale: 'en' }}>
-      <CardElement
-        paymentId={paymentId}
-        style={{
-          // ⚠️ Styling API has changed - see Styling section below
-          fontFamily: 'Inter',
-          button: {
-            backgroundColor: '#0070F3',
-            textColor: '#FFFFFF'
-          }
-        }}
-        onComplete={(result) => {
-          if (result.status === 'CHECKOUT_SUCCESS') {
-            window.location.href = '/success';
-          }
-        }}
-      />
-    </InflowPayProvider>
-  );
-}
-```
+```javascript
+const cardElement = provider.createCardElement({
+  paymentId: "pay_xxx", // Required - from your backend
+  container: "#card-container", // Required - CSS selector or HTMLElement
 
-**Important:** The component API is similar, but **styling customization has changed**. See the [Styling](#styling) section for the new styling structure.
+  // Callbacks
+  onComplete: (result) => {
+    if (result.status === PaymentResultStatus.SUCCESS) {
+      // Payment successful
+    } else if (result.status === PaymentResultStatus.FAILED) {
+      // Payment failed - result.error contains details
+    }
+  },
 
-### Option 2: Vanilla JavaScript (For Non-React Apps)
+  onReady: () => {
+    // Card element mounted and ready
+  },
 
-If you're not using React, you can use the vanilla JavaScript API:
+  onChange: (state) => {
+    // state.complete - whether form is valid
+  },
 
-```javascript
-import { InflowPayProvider } from '@inflow_pay/sdk';
+  onError: (error) => {
+    // SDK-level errors
+  },
 
-const provider = new InflowPayProvider({
-  config: { apiKey: 'inflow_pub_xxx' }
-});
+  // Styling (optional)
+  style: {
+    fontFamily: "Inter",
+    button: {
+      backgroundColor: "#0070F3",
+      textColor: "#FFFFFF",
+    },
+  },
 
-const cardElement = provider.createCardElement({
-  paymentId: paymentId,
-  container: '#card-container',
-  onComplete: (result) => {
-    if (result.status === 'CHECKOUT_SUCCESS') {
-      window.location.href = '/success';
-    }
-  }
+  // Custom text (optional)
+  buttonText: "Pay Now",
+  placeholders: {
+    cardNumber: "1234 5678 9012 3456",
+    expiry: "MM/YY",
+    cvc: "CVC",
+  },
 });
 
 cardElement.mount();
 ```
 
-**Key differences from React version:**
-- No React required - works with vanilla JavaScript
-- Explicit `container` prop (CSS selector or HTMLElement) instead of JSX
-- Call `mount()` explicitly instead of automatic React mounting
-- Same callbacks, same status codes, same error handling
-- **Styling API has changed** - see [Styling](#styling) section for details
-
-## TypeScript
-
-Full type definitions included:
+### Payment Result
 
 ```typescript
-import { InflowPayProvider, PaymentStatus } from '@inflow_pay/sdk';
-import type { PaymentResult, PaymentError } from '@inflow_pay/sdk';
+interface PaymentResult {
+  status: "SUCCESS" | "FAILED";
+  paymentId: string;
+  error?: {
+    code: string; // Error code (e.g., 'THREE_DS_FAILED')
+    message: string; // User-friendly message
+    retryable: boolean; // Can retry?
+  };
+}
+```
 
-const provider = new InflowPayProvider({
-  config: { apiKey: 'inflow_pub_xxx' }
-});
+### CardElement Methods
 
-const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',
-  container: '#card-container',
-  onComplete: (result: PaymentResult) => {
-    if (result.status === PaymentStatus.CHECKOUT_SUCCESS) {
-      // Success
-    }
-  },
-  onError: (error: PaymentError) => {
-    console.error(error);
-  }
-});
+```javascript
+cardElement.mount(); // Mount to DOM
+cardElement.destroy(); // Cleanup and unmount
 ```
 
 ## Styling
 
-The iframe-based SDK provides a comprehensive styling API to match your brand. **Note: The styling structure is different from the original React SDK.** All styles are fully typed with TypeScript.
-
-### Basic Styling
+Customize the payment form to match your brand:
 
 ```javascript
-const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',
-  container: '#card-container',
-  style: {
-    fontFamily: 'Inter',
-    fillParent: true,
-    inputContainer: {
-      backgroundColor: '#F5F5F5',
-      borderRadius: '8px',
-      borderEnabled: true,
-      borderColor: '#E0E0E0'
-    },
-    input: {
-      textColor: '#1A1A1A',
-      placeholderColor: '#999999'
-    },
-    button: {
-      backgroundColor: '#0070F3',
-      textColor: '#FFFFFF',
-      borderRadius: '8px',
-      fontSize: '16px',
-      fontWeight: 600,
-      opacity: 1,
-      hover: {
-        backgroundColor: '#0051CC'
-      },
-      disabled: {
-        opacity: 0.5
-      }
-    },
-    dark: {
-      button: {
-        backgroundColor: '#0066CC'
-      }
-    }
-  }
-});
-```
+style: {
+  fontFamily: 'Inter',  // 'DM Sans' | 'Inter' | 'Poppins' | 'Nunito' | etc.
+  fillParent: true,
 
-### Dark Mode
+  // Input container
+  inputContainer: {
+    backgroundColor: '#F5F5F5',
+    borderRadius: '8px',
+    borderEnabled: true,
+    borderColor: '#E0E0E0'
+  },
 
-Use the `dark` property to customize dark mode styles:
+  // Input fields
+  input: {
+    textColor: '#1A1A1A',
+    placeholderColor: '#999999',
+    backgroundColor: 'transparent'
+  },
 
-```tsx
-style: {
-  fontFamily: 'Inter',
+  // Button
   button: {
     backgroundColor: '#0070F3',
-    textColor: '#FFFFFF'
+    textColor: '#FFFFFF',
+    borderRadius: '8px',
+    fontSize: '16px',
+    fontWeight: 600,
+    hover: {
+      backgroundColor: '#0051CC'
+    },
+    disabled: {
+      opacity: 0.5
+    }
   },
-  inputContainer: {
-    backgroundColor: '#FFFFFF',
-    borderColor: '#E0E0E0'
+
+  // Success screen (shown by default; customize with successUI)
+  successUI: {
+    backgroundColor: '#F5F5F5',
+    primaryTextColor: '#1A1A1A',   // title and amount
+    secondaryTextColor: '#999999'   // subtitle
   },
+
+  // Dark mode
   dark: {
     inputContainer: {
       backgroundColor: '#1A1A1A',
@@ -437,281 +329,78 @@ style: {
     },
     input: {
       textColor: '#FFFFFF',
-      backgroundColor: '#2A2A2A'
+      placeholderColor: '#959499'
     },
     button: {
       backgroundColor: '#0066CC'
+    },
+    successUI: {
+      backgroundColor: '#1A1A1A',
+      primaryTextColor: '#FFFFFF',
+      secondaryTextColor: '#959499'
     }
   }
 }
 ```
 
-### Available Font Families
+**Available style properties:** `inputContainer`, `input`, `button`, `successUI`, `generalError`, `disclaimerColor`, `fieldErrorColor`, `dark` (for dark mode overrides)
 
-```typescript
-type FontFamily =
-  | 'DM Sans'
-  | 'Inter'
-  | 'Poppins'
-  | 'Nunito'
-  | 'Work Sans'
-  | 'Manrope'
-  | 'Rubik'
-  | 'Karla'
-  | 'Figtree'
-  | 'Outfit'
-  | 'Space Grotesk'
-  | 'Urbanist';
-```
+See full TypeScript types in the package for all styling options.
 
-### Complete Styling API
+## Error Handling
 
-All available styling properties:
+```javascript
+import { PaymentResultStatus, PaymentResultErrorCode } from "@inflow_pay/sdk";
 
-```tsx
-interface CSSProperties {
-  // Global
-  fontFamily?: FontFamily;  // 'DM Sans' | 'Inter' | 'Poppins' | etc.
-  fillParent?: boolean;     // Make element fill parent container
-  
-  // Input container (wrapper around all card inputs)
-  inputContainer?: {
-    backgroundColor?: string;
-    borderColor?: string;
-    borderEnabled?: boolean;  // Must be true to show border
-    borderRadius?: string;
-  };
-  
-  // Individual input fields
-  input?: {
-    backgroundColor?: string;
-    borderColor?: string;
-    borderEnabled?: boolean;
-    borderRadius?: string;
-    textColor?: string;
-    placeholderColor?: string;
-  };
-  
-  // Button styles
-  button?: {
-    backgroundColor?: string;
-    textColor?: string;
-    borderRadius?: string;
-    borderColor?: string;
-    borderEnabled?: boolean;  // Must be true to show border
-    fontSize?: string;
-    fontWeight?: FontWeight;  // 100-900 | 'normal' | 'bold' | 'lighter' | 'bolder'
-    opacity?: Opacity;        // number (0-1) | string ('0.5' | '50%')
-    hover?: {                 // Hover state
-      backgroundColor?: string;
-      textColor?: string;
-      borderRadius?: string;
-      borderColor?: string;
-      borderEnabled?: boolean;
-      fontSize?: string;
-      fontWeight?: FontWeight;
-      opacity?: Opacity;
-    };
-    disabled?: {              // Disabled state
-      backgroundColor?: string;
-      textColor?: string;
-      borderRadius?: string;
-      borderColor?: string;
-      borderEnabled?: boolean;
-      fontSize?: string;
-      fontWeight?: FontWeight;
-      opacity?: Opacity;
-    };
-    loaderColor?: string;    // Loading spinner color
-  };
-  
-  // General error message
-  generalError?: {
-    textColor?: string;
-    backgroundColor?: string;
-    borderEnabled?: boolean;
-    borderRadius?: string;
-    borderColor?: string;
-  };
-  
-  // General success message
-  generalSuccess?: {
-    textColor?: string;
-    backgroundColor?: string;
-    borderEnabled?: boolean;
-    borderRadius?: string;
-    borderColor?: string;
-  };
-  
-  // Other colors
-  disclaimerColor?: string;   // Disclaimer text and icon color
-  fieldErrorColor?: string;   // Field validation error text color
-  
-  // Dark mode overrides
-  dark?: {
-    inputContainer?: InputContainerStyles;
-    input?: InputStyles;
-    button?: ButtonStyles;
-    disclaimerColor?: string;
-    fieldErrorColor?: string;
-    generalError?: GeneralMessageStyles;
-    generalSuccess?: GeneralMessageStyles;
-  };
-}
+onComplete: (result) => {
+  if (result.status === PaymentResultStatus.FAILED && result.error) {
+    console.log(result.error.code); // e.g., 'THREE_DS_FAILED'
+    console.log(result.error.message); // User-friendly message
+    console.log(result.error.retryable); // Can user retry?
+  }
+};
 ```
 
-### Custom Placeholders
+**Common error codes:** `THREE_DS_FAILED`, `PAYMENT_PROCESSING_ERROR`
 
-```javascript
-placeholders: {
-  cardNumber: '1234 5678 9012 3456',
-  expiry: 'MM/YY',
-  cvc: 'CVC'
-}
-```
+## 3D Secure
 
-### Custom Button Text
+3DS is handled automatically by the SDK. When required, a modal opens for bank authentication, then closes automatically. No setup needed.
 
-```javascript
-buttonText: 'Pay Now'
-```
+## Migration from React SDK
 
-### React Example with All Styling Properties
+**For React apps:** Import from `@inflow_pay/sdk/react` instead. The component API is similar, but the styling structure has changed (see [Styling](#styling) section).
 
-```tsx
-import { InflowPayProvider, CardElement } from '@inflow_pay/sdk/react';
+**For non-React apps:** Use the vanilla JavaScript API shown in the examples above.
 
-function App() {
-  return (
-    <InflowPayProvider config={{ apiKey: 'inflow_pub_xxx' }}>
-      <CardElement
-        paymentId="pay_xxx"
-        style={{
-          fontFamily: 'Inter',
-          fillParent: true,
-          
-          // Input container
-          inputContainer: {
-            backgroundColor: '#F5F5F5',
-            borderRadius: '8px',
-            borderEnabled: true,
-            borderColor: '#E0E0E0'
-          },
-          
-          // Input fields
-          input: {
-            textColor: '#1A1A1A',
-            placeholderColor: '#999999',
-            backgroundColor: 'transparent',
-            borderColor: '#CECECE',
-            borderEnabled: true,
-            borderRadius: '6px'
-          },
-          
-          // Button
-          button: {
-            backgroundColor: '#0070F3',
-            textColor: '#FFFFFF',
-            borderRadius: '8px',
-            fontSize: '16px',
-            fontWeight: 600,
-            opacity: 1,
-            borderEnabled: false,
-            hover: {
-              backgroundColor: '#0051CC',
-              opacity: 1
-            },
-            disabled: {
-              opacity: 0.5
-            },
-            loaderColor: '#FFFFFF'
-          },
-          
-          // General messages
-          generalError: {
-            textColor: '#FF443F',
-            backgroundColor: '#ffd6cc',
-            borderColor: '#FF443F',
-            borderEnabled: true,
-            borderRadius: '6px'
-          },
-          
-          generalSuccess: {
-            textColor: '#29a329',
-            backgroundColor: '#d6f5d6',
-            borderColor: '#29a329',
-            borderEnabled: true,
-            borderRadius: '6px'
-          },
-          
-          // Other colors
-          disclaimerColor: '#7A7A7A',
-          fieldErrorColor: '#ef4444',
-          
-          // Dark mode
-          dark: {
-            inputContainer: {
-              backgroundColor: '#2d2d2d',
-              borderColor: '#7A7A7A'
-            },
-            input: {
-              textColor: '#FFFFFF',
-              placeholderColor: '#959499',
-              borderColor: '#7A7A7A'
-            },
-            button: {
-              backgroundColor: '#0066CC'
-            },
-            generalError: {
-              textColor: '#ffc2b3',
-              backgroundColor: '#991f00',
-              borderColor: '#e62e00'
-            },
-            generalSuccess: {
-              textColor: '#adebad',
-              backgroundColor: '#196619',
-              borderColor: '#2eb82e'
-            },
-            disclaimerColor: '#959499',
-            fieldErrorColor: '#ef4444'
-          }
-        }}
-        buttonText="Complete Payment"
-        onComplete={(result) => {
-          if (result.status === 'CHECKOUT_SUCCESS') {
-            alert('Payment successful!');
-          }
-        }}
-      />
-    </InflowPayProvider>
-  );
-}
-```
+## TypeScript
+
+Full type definitions included:
 
-## Security
+```typescript
+import { InflowPayProvider, PaymentResultStatus } from "@inflow_pay/sdk";
+import type { PaymentResult, PaymentError } from "@inflow_pay/sdk";
 
-- ✅ Card data is tokenized before reaching your server (PCI compliant)
-- ✅ Public keys can be safely exposed in browser
-- ✅ Private keys should never be in frontend code
-- ✅ All requests over HTTPS
-- ✅ Iframe isolation for security
+const provider = new InflowPayProvider({
+  config: { publicKey: "inflow_pub_xxx" },
+});
+```
 
 ## Features
 
-- ✅ **Dynamic Height**: Automatically adjusts iframe height based on content
-- ✅ **Skeleton Loader**: Beautiful loading state with shimmer effect
-- ✅ **Dark Mode Support**: Automatic theme detection with manual overrides
-- ✅ **TypeScript**: Full type definitions included
-- ✅ **Responsive**: Works on all screen sizes
-- ✅ **Accessible**: WCAG compliant
-- ✅ **Secure**: PCI compliant, iframe isolation
+- ✅ Dynamic height adjustment
+- ✅ Skeleton loader with shimmer effect
+- ✅ Dark mode support
+- ✅ Responsive design
+- ✅ WCAG compliant
+- ✅ Multi-language support
 
 ## Support
 
-- **Documentation:** https://docs.inflowpay.com/v0/reference/createpayment
+- **Docs:** https://docs.inflowpay.com/v0/reference/createpayment
 - **Email:** support@inflowpay.com
 - **GitHub:** https://github.com/inflowpay/sdk
-- **Changelog:** See [CHANGELOG.md](./CHANGELOG.md) for version history
+- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
 ## License