@inflow_pay/sdk 1.0.0 → 1.2.0-beta.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-02-23
+
+### Added
+- **Default success UI customization** – Style the built-in success screen via `style.successUI` (e.g. `backgroundColor`, `primaryTextColor`, `secondaryTextColor`). Use `dark.successUI` for dark mode overrides.
+
+### Fixed
+- **Dynamic height for success UI** – Iframe now reports content height when the success screen is shown, so the SDK container resizes correctly and no longer leaves extra empty space or overflow.
+
+### Deprecated
+- **General success styling** – `style.generalSuccess` and `style.dark.generalSuccess` are deprecated and have no effect (general success UI was removed from the iframe). They will be removed in the next major version. Use the default success UI and `style.successUI` instead.
+
 ## [0.8.0] - 2026-01-30
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # InflowPay SDK v2
 
-Accept card payments with a secure, iframe-based payment form. This version delivers **enhanced security**, a **built-in success UI**, and **automatic 3D Secure handling** - all with just a few lines of code.
+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
 
@@ -9,6 +9,7 @@ Accept card payments with a secure, iframe-based payment form. This version deli
 - 🎯 **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
+- 💳 **Save card (setup)**: Collect and tokenize a card without charging, using a `CustomerPaymentMethodRequest` ID (`setupId`)
 
 ## Installation
 
@@ -16,10 +17,16 @@ Accept card payments with a secure, iframe-based payment form. This version deli
 npm install @inflow_pay/sdk
 ```
 
+**React apps** — import from `@inflow_pay/sdk/react` and ensure peer dependencies are installed:
+
+```bash
+npm install @inflow_pay/sdk react react-dom
+```
+
 **CDN Option** (vanilla HTML pages only):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@1.0.0/dist/sdk.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@1.1.0/dist/sdk.umd.js"></script>
 ```
 
 ## Complete Example
@@ -28,22 +35,22 @@ npm install @inflow_pay/sdk
 
 ```javascript
 // 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',
+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
+      "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'
-    })
+      products: [{ name: "Product", price: 4999, quantity: 1 }],
+      currency: "EUR",
+      customerEmail: "customer@example.com",
+      firstName: "John",
+      lastName: "Doe",
+      billingCountry: "FR",
+      postalCode: "75001",
+    }),
   });
 
   const data = await response.json();
@@ -54,32 +61,64 @@ app.post('/api/create-payment', async (req, res) => {
 ### Frontend: React
 
 ```tsx
-import { InflowPayProvider, CardElement, PaymentResultStatus } from '@inflow_pay/sdk/react';
+import {
+  InflowPayProvider,
+  CardElement,
+  PaymentResultStatus,
+} from "@inflow_pay/sdk/react";
 
 export default function CheckoutPage() {
   const [paymentId, setPaymentId] = useState<string | null>(null);
 
   useEffect(() => {
-    fetch('/api/create-payment', { method: 'POST' })
-      .then(res => res.json())
-      .then(data => setPaymentId(data.paymentId));
+    fetch("/api/create-payment", { method: "POST" })
+      .then((res) => res.json())
+      .then((data) => setPaymentId(data.paymentId));
   }, []);
 
   if (!paymentId) return <div>Loading...</div>;
 
   return (
-    <InflowPayProvider config={{ publicKey: 'inflow_pub_xxx' }}>
+    <InflowPayProvider config={{ publicKey: "inflow_pub_xxx" }}>
       <CardElement
         paymentId={paymentId}
-        showDefaultSuccessUI={true}
         onComplete={(result) => {
           if (result.status === PaymentResultStatus.SUCCESS) {
-            setTimeout(() => window.location.href = '/confirmation', 2000);
+            setTimeout(() => (window.location.href = "/confirmation"), 2000);
           }
         }}
         style={{
-          fontFamily: 'Inter',
-          button: { backgroundColor: '#0070F3', textColor: '#FFFFFF' }
+          fontFamily: "Inter",
+          button: { backgroundColor: "#0070F3", textColor: "#FFFFFF" },
+        }}
+      />
+    </InflowPayProvider>
+  );
+}
+```
+
+### Save card (setup) — React
+
+Use **`setupId`** (ID returned when you create a **CustomerPaymentMethodRequest** on your server) instead of **`paymentId`**. The two are mutually exclusive. On success, `onComplete` receives a **`SaveCardResult`** with `status` and `setupId`.
+
+```tsx
+import {
+  InflowPayProvider,
+  CardElement,
+  PaymentResultStatus,
+  type SaveCardResult,
+} from "@inflow_pay/sdk/react";
+
+export default function AddCardPage({ setupId }: { setupId: string }) {
+  return (
+    <InflowPayProvider config={{ publicKey: "inflow_pub_xxx" }}>
+      <CardElement
+        setupId={setupId}
+        onComplete={(result) => {
+          if (result.status === PaymentResultStatus.SUCCESS) {
+            const save = result as SaveCardResult;
+            console.log("Card saved for request:", save.setupId);
+          }
         }}
       />
     </InflowPayProvider>
@@ -87,94 +126,139 @@ export default function CheckoutPage() {
 }
 ```
 
+Your backend should create the customer payment method request with your **private** API key and expose only the returned request ID to the browser as `setupId`.
+
 ### Frontend: Vanilla JavaScript
 
 ```html
 <div id="card-container"></div>
 
-<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/sdk@0.8.0/dist/sdk.umd.js"></script>
+<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' }
+    config: { publicKey: "inflow_pub_xxx" },
   });
 
-  fetch('/api/create-payment', { method: 'POST' })
-    .then(res => res.json())
-    .then(data => {
+  fetch("/api/create-payment", { method: "POST" })
+    .then((res) => res.json())
+    .then((data) => {
       const cardElement = provider.createCardElement({
         paymentId: data.paymentId,
-        container: '#card-container',
-        showDefaultSuccessUI: true,
+        container: "#card-container",
         onComplete: (result) => {
           if (result.status === InflowPaySDK.PaymentResultStatus.SUCCESS) {
-            setTimeout(() => window.location.href = '/confirmation', 2000);
+            setTimeout(() => (window.location.href = "/confirmation"), 2000);
           }
-        }
+        },
       });
       cardElement.mount();
     });
 </script>
 ```
 
+### Save card (setup) — Vanilla JavaScript
+
+```javascript
+const provider = new InflowPaySDK.InflowPayProvider({
+  config: { publicKey: "inflow_pub_xxx" },
+});
+
+fetch("/api/create-card-setup", { method: "POST" })
+  .then((res) => res.json())
+  .then((data) => {
+    const cardElement = provider.createCardElement({
+      setupId: data.setupId,
+      container: "#card-container",
+      onComplete: (result) => {
+        if (result.status === InflowPaySDK.PaymentResultStatus.SUCCESS) {
+          console.log("setupId:", result.setupId);
+        }
+      },
+    });
+    cardElement.mount();
+  });
+```
+
 ## Built-in Success UI Explained
 
 The SDK includes a polished success screen that appears automatically after successful payment:
 
 **What it shows:**
+
 - ✅ Success icon and "Payment successful!" message
 - 💳 Payment amount (when available from your payment data)
-- 🎨 Automatically matches your brand colors and theme
-- 🌙 Dark mode support
 
-**How to use it:**
+**Default vs custom:**
 
-```javascript
-// Option 1: Use default success UI (recommended)
-const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',
-  container: '#card-container',
-  showDefaultSuccessUI: true,  // Shows built-in success screen
-  onComplete: (result) => {
-    if (result.status === PaymentResultStatus.SUCCESS) {
-      // Success UI is already showing in the iframe
-      // Optional: redirect after 2 seconds
-      setTimeout(() => window.location.href = '/confirmation', 2000);
-    }
-  }
-});
+- **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:
 
-// Option 2: Use your own custom success UI
+_Vanilla JS:_
+
+```javascript
 const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',
-  container: '#card-container',
-  showDefaultSuccessUI: false,  // Iframe unmounts on success
+  paymentId: "pay_xxx",
+  container: "#card-container",
+  showDefaultSuccessUI: false,
   onComplete: (result) => {
     if (result.status === PaymentResultStatus.SUCCESS) {
-      // Show your custom success UI
-      document.getElementById('card-container').innerHTML = `
+      document.getElementById("card-container").innerHTML = `
         <div class="custom-success">
           <h2>Thank you for your purchase!</h2>
           <p>Order ID: ${result.paymentId}</p>
         </div>
       `;
     }
-  }
+  },
 });
 ```
 
-**When to use each option:**
-- **Default UI** (`showDefaultSuccessUI: true`): Quick integration, consistent experience, looks great out of the box
-- **Custom UI** (`showDefaultSuccessUI: false`): Full control when you need custom branding or additional information
+_React:_
+
+```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>
+    )}
+  </>
+);
+```
+
+## Payment flow
+
+**Charge (payment)**
+
+1. Backend creates a payment → returns `paymentId`
+2. Frontend mounts `CardElement` with `paymentId` and your public key
+3. User enters card details in the secure iframe
+4. SDK tokenizes the card and processes the payment
+5. 3D Secure (if required) — handled automatically
+6. `onComplete` fires with a **`PaymentResult`** → redirect or update UI
 
-## Payment Flow
+**Save card (setup)**
 
-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. Success UI displays (built-in or custom)
-7. `onComplete` callback fires → redirect or update UI
+1. Backend creates a **CustomerPaymentMethodRequest** → returns its ID as `setupId`
+2. Frontend mounts `CardElement` with **`setupId`** (not `paymentId`)
+3. User completes the card form; 3DS may still run when the issuer requires it
+4. `onComplete` fires with a **`SaveCardResult`** (`setupId` + `status`, and `error` on failure)
 
 ## API Reference
 
@@ -183,9 +267,9 @@ const cardElement = provider.createCardElement({
 ```javascript
 const provider = new InflowPayProvider({
   config: {
-    publicKey: 'inflow_pub_xxx',  // Required
-    locale: 'en'                   // Optional - defaults to browser language
-  }
+    publicKey: "inflow_pub_xxx", // Required
+    locale: "en", // Optional - defaults to browser language
+  },
 });
 ```
 
@@ -193,12 +277,14 @@ const provider = new InflowPayProvider({
 
 ### CardElement
 
+Pass exactly one of **`paymentId`** (checkout) or **`setupId`** (save card). Passing both or neither throws.
+
 ```javascript
 const cardElement = provider.createCardElement({
-  paymentId: 'pay_xxx',         // Required - from your backend
-  container: '#card-container', // Required - CSS selector or HTMLElement
-  showDefaultSuccessUI: true,   // Optional - default true
-  
+  paymentId: "pay_xxx", // XOR setupId — from your backend
+  // setupId: "cus_pm_req_xxx", // save-card flow (CustomerPaymentMethodRequest ID)
+  container: "#card-container", // Required - CSS selector or HTMLElement
+
   // Callbacks
   onComplete: (result) => {
     if (result.status === PaymentResultStatus.SUCCESS) {
@@ -207,59 +293,71 @@ const cardElement = provider.createCardElement({
       // Payment failed - result.error contains details
     }
   },
-  
+
   onReady: () => {
     // Card element mounted and ready
   },
-  
+
   onChange: (state) => {
     // state.complete - whether form is valid
   },
-  
+
   onError: (error) => {
     // SDK-level errors
   },
-  
+
   // Styling (optional)
   style: {
-    fontFamily: 'Inter',
+    fontFamily: "Inter",
     button: {
-      backgroundColor: '#0070F3',
-      textColor: '#FFFFFF'
-    }
+      backgroundColor: "#0070F3",
+      textColor: "#FFFFFF",
+    },
   },
-  
+
   // Custom text (optional)
-  buttonText: 'Pay Now',
+  buttonText: "Pay Now",
   placeholders: {
-    cardNumber: '1234 5678 9012 3456',
-    expiry: 'MM/YY',
-    cvc: 'CVC'
-  }
+    cardNumber: "1234 5678 9012 3456",
+    expiry: "MM/YY",
+    cvc: "CVC",
+  },
 });
 
 cardElement.mount();
 ```
 
-### Payment Result
+### Payment and save-card results
 
 ```typescript
 interface PaymentResult {
-  status: 'SUCCESS' | 'FAILED';
+  status: "SUCCESS" | "FAILED";
   paymentId: string;
   error?: {
-    code: string;          // Error code (e.g., 'THREE_DS_FAILED')
-    message: string;       // User-friendly message
-    retryable: boolean;    // Can retry?
-  }
+    code: string; // Error code (e.g., 'THREE_DS_FAILED')
+    message: string; // User-friendly message
+    retryable: boolean; // Can retry?
+  };
+}
+
+interface SaveCardResult {
+  status: "SUCCESS" | "FAILED";
+  setupId: string;
+  error?: {
+    code: string;
+    message: string;
+    retryable: boolean;
+  };
 }
 ```
 
+In **React**, `onComplete` is typed as `(result: PaymentResult | SaveCardResult) => void`. Use `result.status` and narrow with `'paymentId' in result` vs `'setupId' in result`, or cast when you know which mode you mounted.
+
 ### CardElement Methods
 
 ```javascript
-cardElement.mount();    // Mount to DOM
-cardElement.destroy();  // Cleanup and unmount
+cardElement.mount(); // Mount to DOM
+cardElement.destroy(); // Cleanup and unmount
 ```
 
 ## Styling
@@ -270,7 +368,7 @@ Customize the payment form to match your brand:
 style: {
   fontFamily: 'Inter',  // 'DM Sans' | 'Inter' | 'Poppins' | 'Nunito' | etc.
   fillParent: true,
-  
+
   // Input container
   inputContainer: {
     backgroundColor: '#F5F5F5',
@@ -278,14 +376,14 @@ style: {
     borderEnabled: true,
     borderColor: '#E0E0E0'
   },
-  
+
   // Input fields
   input: {
     textColor: '#1A1A1A',
     placeholderColor: '#999999',
     backgroundColor: 'transparent'
   },
-  
+
   // Button
   button: {
     backgroundColor: '#0070F3',
@@ -300,7 +398,14 @@ style: {
       opacity: 0.5
     }
   },
-  
+
+  // Success screen (shown by default; customize with successUI)
+  successUI: {
+    backgroundColor: '#F5F5F5',
+    primaryTextColor: '#1A1A1A',   // title and amount
+    secondaryTextColor: '#999999'   // subtitle
+  },
+
   // Dark mode
   dark: {
     inputContainer: {
@@ -313,27 +418,32 @@ style: {
     },
     button: {
       backgroundColor: '#0066CC'
+    },
+    successUI: {
+      backgroundColor: '#1A1A1A',
+      primaryTextColor: '#FFFFFF',
+      secondaryTextColor: '#959499'
     }
   }
 }
 ```
 
-**Available style properties:** `inputContainer`, `input`, `button`, `generalError`, `generalSuccess`, `disclaimerColor`, `fieldErrorColor`, `dark` (for dark mode overrides)
+**Available style properties:** `inputContainer`, `input`, `button`, `successUI`, `generalError`, `disclaimerColor`, `fieldErrorColor`, `dark` (for dark mode overrides)
 
 See full TypeScript types in the package for all styling options.
 
 ## Error Handling
 
 ```javascript
-import { PaymentResultStatus, PaymentResultErrorCode } from '@inflow_pay/sdk';
+import { PaymentResultStatus, PaymentResultErrorCode } from "@inflow_pay/sdk";
 
 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.code); // e.g., 'THREE_DS_FAILED'
+    console.log(result.error.message); // User-friendly message
     console.log(result.error.retryable); // Can user retry?
   }
-}
+};
 ```
 
 **Common error codes:** `THREE_DS_FAILED`, `PAYMENT_PROCESSING_ERROR`
@@ -350,17 +460,28 @@ onComplete: (result) => {
 
 ## TypeScript
 
-Full type definitions included:
+Full type definitions are included for both entry points:
 
 ```typescript
-import { InflowPayProvider, PaymentResultStatus } from '@inflow_pay/sdk';
-import type { PaymentResult, PaymentError } from '@inflow_pay/sdk';
-
-const provider = new InflowPayProvider({
-  config: { publicKey: 'inflow_pub_xxx' }
-});
+// Vanilla (InflowPayProvider, PaymentSDK, CardElement)
+import {
+  InflowPayProvider,
+  PaymentResultStatus,
+} from "@inflow_pay/sdk";
+import type { PaymentResult, SaveCardResult, PaymentError } from "@inflow_pay/sdk";
+
+// React components and hooks
+import {
+  InflowPayProvider,
+  CardElement,
+  useInflowPay,
+  PaymentResultStatus,
+} from "@inflow_pay/sdk/react";
+import type { PaymentResult, SaveCardResult } from "@inflow_pay/sdk/react";
 ```
 
+`useInflowPay()` returns the shared `PaymentSDK` instance from `InflowPayProvider` (e.g. for advanced use).
+
 ## Features
 
 - ✅ Dynamic height adjustment