@inflow_pay/sdk

v0.0.1

Published

a month ago

InflowPay SDK - payment SDK with React and vanilla JS support

0High
0Medium
0Low

dev_in

inflowpay payment sdk payments typescript

InflowPay SDK v2 - Iframe-based Payment SDK

Accept card payments with a pre-built, secure payment form. Same API as the React SDK for easy migration.

Installation

npm install @inflow_pay/sdk

Quick Start

Same API as React SDK! Easy migration from React SDK to iframe-based SDK:

import { InflowPayProvider } from "@inflow_pay/sdk";

// Step 1: Create InflowPayProvider (same as React's <InflowPayProvider>)
const provider = new InflowPayProvider({
  config: { apiKey: "inflow_pub_xxx" },
});

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

// Step 3: Mount the CardElement
cardElement.mount();

How It Works

Backend: Create a payment with billing info (your private key)
Frontend: Create InflowPayProvider with your API key
Frontend: Create CardElement with the paymentId
User: Enters card details and submits
SDK: Handles tokenization, 3DS, and payment completion
Your app: Receives success/error via callback

Payment Status

Payments progress through these statuses:

| Status | Description | Success? | | ------------------ | ----------------- | -------- | | CHECKOUT_SUCCESS | Payment confirmed | ✅ Yes | | PAYMENT_FAILED | Failed | ❌ No |

Check for success:

if (result.status === "CHECKOUT_SUCCESS") {
  // Payment successful
}

API Reference

InflowPayProvider

const provider = new InflowPayProvider({
  config: {
    apiKey: "inflow_pub_xxx", // Required
    iframeUrl: "https://...", // Optional, auto-detected from API key
    timeout: 30000, // Optional, default: 30000
    debug: false, // Optional, default: false
  },
});

CardElement

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

  // 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`

Mounts the CardElement to the DOM. This will create and display the iframe.

cardElement.mount();

`destroy(): void`

Destroys the CardElement and cleans up resources.

cardElement.destroy();

HTML Example

<!DOCTYPE html>
<html>
  <head>
    <title>My Payment Page</title>
  </head>
  <body>
    <div id="card-container"></div>

    <script src="https://cdn.inflowpay.com/sdk/v2/inflowpay-sdk.js"></script>
    <script>
      // Same API as React SDK!
      const provider = new InflowPaySDK.InflowPayProvider({
        config: { apiKey: "inflow_pub_xxx" },
      });

      const cardElement = provider.createCardElement({
        paymentId: "pay_xxx",
        container: "#card-container",
        onComplete: (result) => {
          if (result.status === InflowPaySDK.PaymentStatus.CHECKOUT_SUCCESS) {
            alert("Payment successful!");
          }
        },
      });

      cardElement.mount();
    </script>
  </body>
</html>

Error Handling

Errors are automatically mapped to user-friendly messages:

cardElement.onComplete = (result) => {
  if (result.error) {
    console.log(result.error.message); // User-friendly
    console.log(result.error.retryable); // Can retry?
  }
};

Common errors:

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:

SDK opens a modal with the authentication page
User completes authentication
Modal closes automatically
Your onComplete callback receives the final result

No setup required! The SDK automatically handles 3DS redirects.

Backend Integration

Create payments on your backend with your private key:

// 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
  },
  body: JSON.stringify({
    products: [{ name: "Product", price: 4999, quantity: 1 }],
    currency: "EUR",
    customerEmail: "[email protected]",
    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 for full backend API reference.

Migration from React SDK

The SDK v2 uses the same API as the React SDK, making migration easy. You have two options:

Option 1: Keep Using React (Recommended for React Apps)

If you're using React, you can use the React components which work exactly like the original SDK:

// Just change the import path!
import { InflowPayProvider, CardElement } from "@inflow_pay/sdk/react";

function App() {
  return (
    <InflowPayProvider config={{ apiKey: "inflow_pub_xxx" }}>
      <CardElement
        paymentId={paymentId}
        onComplete={(result) => {
          if (result.status === "CHECKOUT_SUCCESS") {
            window.location.href = "/success";
          }
        }}
      />
    </InflowPayProvider>
  );
}

No changes needed! Same API, same behavior, just a different import path.

Option 2: Vanilla JavaScript (For Non-React Apps)

If you're not using React, you can use the vanilla JavaScript API:

import { InflowPayProvider } from "@inflow_pay/sdk";

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

const cardElement = provider.createCardElement({
  paymentId: paymentId,
  container: "#card-container",
  onComplete: (result) => {
    if (result.status === "CHECKOUT_SUCCESS") {
      window.location.href = "/success";
    }
  },
});

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

TypeScript

Full type definitions included:

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

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

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

Security

✅ 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

Support

Documentation: https://docs.inflowpay.com/v0/reference/createpayment
Email: [email protected]
GitHub: https://github.com/inflowpay/sdk

License

MIT - See LICENSE