@vindhq/sloud-payment-sdk

v1.0.8

Published

9 days ago

A custom payment SDK for seamless payment processing integration

Downloads

322

0High
0Medium
0Low

seunjay

saburahmed

vind-admin

payment payment-sdk payment-gateway payment-widget react payment-processing checkout payment-form sloud payment-integration fintech

Sloud Payment SDK

A secure, embeddable payment widget for straightforward customer payments, built in React and usable in any JavaScript application (React, Angular, Vue, or vanilla JS). Ships with ESM, CJS, and UMD builds for easy integration in any environment.

Features

Developer-friendly: authored in React for easy maintenance and composability.
Framework-agnostic: works in any JavaScript environment.
Multiple build formats: ESM and CJS for npm/React apps, UMD for browser usage.
Bundled CSS via PostCSS.
Asset support (SVG icons) included in the build.
Built-in validation using Formik and Yup.
Toast notifications via react-hot-toast.

Installation

For npm/React Projects

# Using npm
npm install @vindhq/sloud-payment-sdk

# Using yarn
yarn add @vindhq/sloud-payment-sdk

Note: For npm projects, this widget has peer dependencies on React 18+. Make sure you have React and ReactDOM installed:

npm install react react-dom

For Browser Usage (No Bundler)

For direct browser usage without a bundler, use the UMD build which includes React bundled:

<!DOCTYPE html>
<html>
  <head>
    <title>Payment Widget</title>
  </head>
  <body>
    <!-- Load the UMD bundle (includes React) -->
    <script src="https://unpkg.com/@vindhq/sloud-payment-sdk@latest/dist/index.umd.js"></script>

    <script>
      // Access via PaymentWidget.default for UMD builds
      const widget = new PaymentWidget.default({
        type: "external",
        public_key: "your-public-api-key",
        amount: 10000,
        customer: {
          first_name: "John",
          last_name: "Doe",
          phone_number: "+2348012345678",
          email: "[email protected]",
        },
      });

      widget.showPopup();
    </script>
  </body>
</html>

Usage

The payment widget is designed for straightforward payments with customer details.

Note: When using the UMD build in the browser (via script tag), access the widget via PaymentWidget.default. For npm/ES module imports, use the standard import PaymentWidget from "sloud-payment-sdk".

import PaymentWidget from "@vindhq/sloud-payment-sdk";

const widget = new PaymentWidget({
  type: "external",
  public_key: "your-public-api-key",
  amount: 10000, // Amount in smallest currency unit (e.g., kobo for NGN)
  customer: {
    first_name: "John",
    last_name: "Doe",
    phone_number: "+2348012345678",
    email: "[email protected]",
  },
  isLocalEnv: false, // Optional: set to true for local development
  onSuccess: () => {
    console.log("Payment successful!");
    // Navigate to a confirmation page, update your UI, etc.
  },
});

widget.showPopup();

Handling Payment Success

Use the onSuccess callback to be notified when a payment completes successfully:

import PaymentWidget from "@vindhq/sloud-payment-sdk";

const widget = new PaymentWidget({
  type: "external",
  public_key: "your-public-api-key",
  amount: 10000,
  customer: {
    first_name: "John",
    last_name: "Doe",
    phone_number: "+2348012345678",
    email: "[email protected]",
  },
  onSuccess: () => {
    console.log("Payment successful!");
    // Navigate to a confirmation page, update your UI, etc.
  },
});

widget.showPopup();

API

`new PaymentWidget(options: PaymentWidgetOptions)`

Creates a new payment widget instance.

Payment Widget Options

| Parameter | Type | Required | Description | | ------------ | ------------------------------------ | -------- | ----------------------------------------------- | | type | "external" | Yes | Payment type (must be "external") | | public_key | string | Yes | Your public API key for secure payments | | amount | number | Yes | Payment amount in smallest currency unit | | customer | Customer | Yes | Customer information object | | isLocalEnv | boolean | No | Set to true for local development environment | | onSuccess | (data: PaymentSuccessData) => void | No | Callback invoked after a successful payment |

Type Definitions

Customer

interface Customer {
  first_name: string;
  last_name: string;
  phone_number: string;
  email: string;
}

PaymentSuccessData

interface PaymentSuccessData {
  reference: string;
  amount: number;
  currency: string;
}

Methods

`showPopup()`

Displays the payment widget popup modal.

widget.showPopup();

`hidePopup()`

Hides and unmounts the payment widget popup.

widget.hidePopup();

Validation and Error Handling

The SDK includes built-in validation:

import {
  PaymentWidget,
  validatePaymentWidgetOptions,
  PaymentWidgetValidationError,
} from "@vindhq/sloud-payment-sdk";

try {
  const options = {
    type: "external",
    public_key: "pk_test_123",
    amount: 10000,
    customer: {
      first_name: "John",
      last_name: "Doe",
      phone_number: "+2348012345678",
      email: "invalid-email", // Invalid email format
    },
  };

  // Validate before creating widget
  validatePaymentWidgetOptions(options);

  const widget = new PaymentWidget(options);
  widget.showPopup();
} catch (error) {
  if (error instanceof PaymentWidgetValidationError) {
    console.error("Validation error:", error.message);
  }
}

Advanced Usage

Payload Builders

The SDK uses a builder pattern for payment payloads:

import { buildPaymentInstrumentPayload } from "@vindhq/sloud-payment-sdk";

// Build payload from options
const payload = buildPaymentInstrumentPayload({
  type: "external",
  public_key: "pk_test_123",
  amount: 10000,
  customer: {
    first_name: "John",
    last_name: "Doe",
    phone_number: "+2348012345678",
    email: "[email protected]",
  },
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  PaymentWidgetOptions,
  PaymentSuccessData,
  Customer,
} from "@vindhq/sloud-payment-sdk";

// TypeScript will enforce correct fields
const options: PaymentWidgetOptions = {
  type: "external",
  public_key: "pk_test_123",
  amount: 10000,
  customer: {
    first_name: "John",
    last_name: "Doe",
    phone_number: "+2348012345678",
    email: "[email protected]",
  },
};

Development

# Install dependencies
yarn install

# Run dev server with live reload (UMD build for browser testing)
yarn dev

# Run dev server for library development (ESM/CJS builds)
yarn dev:lib

# Build all production bundles (ESM, CJS, UMD, and type definitions)
yarn build

Development Server

yarn dev: Starts development server with UMD build at http://localhost:3000
- Bundles React for standalone browser testing
- Live reload enabled
- Serves dist and public folders
- Use public/index.html to test the widget
yarn dev:lib: Starts development server with ESM/CJS builds
- Externalizes React (for library development)
- Watch mode for rapid iteration

Folder Structure

Payment-Widget/
├─ src/
│  ├─ index.ts              # Entry point
│  ├─ widget.tsx            # Widget class
│  ├─ components/           # React components
│  └─ styles/               # SCSS/CSS files
├─ dist/                    # Bundled output
│  ├─ index.esm.js          # ES Module build
│  ├─ index.cjs.js          # CommonJS build
│  ├─ index.umd.js          # UMD browser build
│  └─ index.d.ts            # Type definitions
├─ public/                  # Dev server HTML for testing
├─ rollup.config.ts         # ESM/CJS build config
├─ rollup.config.umd.ts     # UMD build config
├─ rollup.config.dts.ts     # Type definitions config
└─ package.json

Build Details

Output Files

dist/index.esm.js - ES Module build (externalizes React)
dist/index.cjs.js - CommonJS build (externalizes React)
dist/index.umd.js - UMD build for browsers (bundles React, ~2MB)
dist/index.d.ts - TypeScript type definitions

Build Configuration

ESM/CJS → Externalizes React as peer dependency for React apps
UMD → Bundles React for standalone browser usage
PostCSS → Injects and minifies CSS into JS bundle
Assets → SVG/PNG files handled automatically
TypeScript → Full type definitions included

License

Specify your license here (e.g., MIT).