InflowPay SDK v2

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

npm install @inflow_pay/sdk

CDN Option (vanilla HTML pages only):

<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/[email protected]/dist/sdk.umd.js"></script>

Complete Example

Backend: Create Payment

// 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: "[email protected]",
      firstName: "John",
      lastName: "Doe",
      billingCountry: "FR",
      postalCode: "75001",
    }),
  });

  const data = await response.json();
  res.json({ paymentId: data.payment.id });
});

Frontend: 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));
  }, []);

  if (!paymentId) return <div>Loading...</div>;

  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>
  );
}

Frontend: Vanilla JavaScript

<div id="card-container"></div>

<script src="https://cdn.jsdelivr.net/npm/@inflow_pay/[email protected]/dist/sdk.umd.js"></script>
<script>
  const provider = new InflowPaySDK.InflowPayProvider({
    config: { publicKey: "inflow_pub_xxx" },
  });

  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>

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)

Default vs custom:

• 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:

Vanilla JS:

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>
      `;
    }
  },
});

React:

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

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

API Reference

InflowPayProvider

const provider = new InflowPayProvider({
  config: {
    publicKey: "inflow_pub_xxx", // Required
    locale: "en", // Optional - defaults to browser language
  },
});

Supported locales: en, de, es, fr, it, nl, pl, pt

CardElement

const cardElement = provider.createCardElement({
  paymentId: "pay_xxx", // Required - from your backend
  container: "#card-container", // Required - CSS selector or HTMLElement

  // Callbacks
  onComplete: (result) => {
    if (result.status === PaymentResultStatus.SUCCESS) {
      // Payment successful
    } else if (result.status === PaymentResultStatus.FAILED) {
      // 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",
    button: {
      backgroundColor: "#0070F3",
      textColor: "#FFFFFF",
    },
  },

  // Custom text (optional)
  buttonText: "Pay Now",
  placeholders: {
    cardNumber: "1234 5678 9012 3456",
    expiry: "MM/YY",
    cvc: "CVC",
  },
});

cardElement.mount();

Payment Result

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?
  };
}

CardElement Methods

cardElement.mount(); // Mount to DOM
cardElement.destroy(); // Cleanup and unmount

Styling

Customize the payment form to match your brand:

style: {
  fontFamily: 'Inter',  // 'DM Sans' | 'Inter' | 'Poppins' | 'Nunito' | etc.
  fillParent: true,

  // Form background is transparent by default, so your page color shows through.
  // Use this only when you need to set the form background explicitly.
  formBackgroundColor: '#211e19',

  // Input container
  inputContainer: {
    backgroundColor: '#F5F5F5',
    borderRadius: '8px',
    borderEnabled: true,
    borderColor: '#E0E0E0'
  },

  // Input fields
  input: {
    textColor: '#1A1A1A',
    placeholderColor: '#999999',
    backgroundColor: 'transparent'
  },

  // Button
  button: {
    backgroundColor: '#0070F3',
    textColor: '#FFFFFF',
    borderRadius: '8px',
    fontSize: '16px',
    fontWeight: 600,
    hover: {
      backgroundColor: '#0051CC'
    },
    disabled: {
      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: {
      backgroundColor: '#1A1A1A',
      borderColor: '#333333'
    },
    input: {
      textColor: '#FFFFFF',
      placeholderColor: '#959499'
    },
    button: {
      backgroundColor: '#0066CC'
    },
    successUI: {
      backgroundColor: '#1A1A1A',
      primaryTextColor: '#FFFFFF',
      secondaryTextColor: '#959499'
    }
  }
}

Available style properties: formBackgroundColor, inputContainer, input, button, successUI, generalError, disclaimerColor, fieldErrorColor, dark (for dark mode overrides)

By default, the form background is transparent and inherits your page color. Set formBackgroundColor only when you need to override that.

See full TypeScript types in the package for all styling options.

Error Handling

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.retryable); // Can user retry?
  }
};

Common error codes: THREE_DS_FAILED, PAYMENT_PROCESSING_ERROR

3D Secure

3DS is handled automatically by the SDK. When required, a modal opens for bank authentication, then closes automatically. No setup needed.

Migration from React SDK

For React apps: Import from @inflow_pay/sdk/react instead. The component API is similar, but the styling structure has changed (see Styling section).

For non-React apps: Use the vanilla JavaScript API shown in the examples above.

TypeScript

Full type definitions included:

import { InflowPayProvider, PaymentResultStatus } from "@inflow_pay/sdk";
import type { PaymentResult, PaymentError } from "@inflow_pay/sdk";

const provider = new InflowPayProvider({
  config: { publicKey: "inflow_pub_xxx" },
});

Features

• ✅ Dynamic height adjustment
• ✅ Skeleton loader with shimmer effect
• ✅ Dark mode support
• ✅ Responsive design
• ✅ WCAG compliant
• ✅ Multi-language support

Support

• Docs: https://docs.inflowpay.com/v0/reference/createpayment
• Email: [email protected]
• GitHub: https://github.com/inflowpay/sdk
• Changelog: CHANGELOG.md

License

MIT - See LICENSE