Sloud Payment SDK

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

Features

• Developer-friendly: authored in React for easy maintenance and composability.
• Framework-agnostic: works with React (peer dependency required).
• ESM build format for modern npm/React apps.
• 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

# Using npm
npm install sloud-payment-sdk

# Using yarn
yarn add sloud-payment-sdk

Note: This widget has peer dependencies on React 19.1.1+. Make sure you have React and ReactDOM installed:

npm install react react-dom

Usage

Basic Usage (React/ESM)

import PaymentWidget from "sloud-payment-sdk";

const widget = new PaymentWidget({
  public_key: "your-public-api-key",
  amount: 10000, // Amount in smallest currency unit (e.g., kobo for NGN)
  first_name: "John",
  last_name: "Doe",
  phone_number: "+2348012345678",
  email: "[email protected]",
  isLocalEnv: false, // Optional: set to true for local development
});

// Show the payment popup
widget.showPopup();

// Hide the payment popup (optional)
widget.hidePopup();

API

new PaymentWidget(options: PaymentWidgetOptions)

Creates a new payment widget instance.

Options

| Parameter | Type | Required | Description | | -------------------- | ------------- | -------- | ------------------------------------------ | | public_key | string | Yes | Your public API key for secure payments. | | amount | number | Yes | Payment amount in smallest currency unit. | | first_name | string | Yes | Customer's first name. | | last_name | string | Yes | Customer's last name. | | phone_number | string | Yes | Customer's phone number. | | email | string | Yes | Customer's email address. | | isLocalEnv | boolean | No | Set to true for local development environment. |

Methods

showPopup()

Displays the payment widget popup modal.

widget.showPopup();

hidePopup()

Hides and unmounts the payment widget popup.

widget.hidePopup();

Example:

const widget = new PaymentWidget({
  public_key: "pk_test_abc123",
  amount: 50000, // 500.00 in currency
  first_name: "Jane",
  last_name: "Smith",
  phone_number: "+2348098765432",
  email: "[email protected]",
});

widget.showPopup();

Development

# Install dependencies
yarn install

# Run dev server with live reload
yarn dev

# Build production bundles
yarn build

• Development server serves dist and public folders at http://localhost:8080.
• Includes live reload for fast iteration.

Folder Structure

Payment-Widget/
├─ src/
│  ├─ index.ts         # Entry point
│  ├─ widget.ts        # Widget class
│  ├─ components/      # React components
│  └─ styles/          # SCSS/CSS files
├─ dist/               # Bundled output (ESM, CJS, UMD)
├─ public/             # Dev server HTML
├─ rollup.config.ts    # Rollup configuration
└─ package.json

Build Details

• ESM/CJS → externalizes React for React apps.
• PostCSS → injects and minifies CSS.
• Assets → SVG/PNG handled automatically.

License

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