@vindhq/sloud-payment-sdk

v1.0.1

Published

4 days ago

A custom payment SDK for seamless payment processing integration

Downloads

199

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 built in React, 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 supports three payment types: external, storefront, and sloudfront. Each type has its own set of required fields.

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".

External Payment (Simple Payments)

For straightforward payments with customer details:

import PaymentWidget from "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
});

widget.showPopup();

Storefront Payment (E-commerce Orders)

For e-commerce orders with products and delivery:

import PaymentWidget from "sloud-payment-sdk";

const widget = new PaymentWidget({
  type: "storefront",
  public_key: "your-public-api-key",
  slug: "my-store",
  amount: 5000, // Additional amount (e.g., shipping fees)
  discount: 1000, // Optional discount
  channel: "delivery", // "pickup" or "delivery"
  customer: {
    first_name: "Jane",
    last_name: "Smith",
    phone_number: "+2348098765432",
    email: "[email protected]",
  },
  delivery_details: {
    street: "123 Main Street",
    city: "Lagos",
    state: "Lagos",
    country: "Nigeria",
    note: "Please call on arrival", // Optional
  },
  products: [
    {
      product_id: "prod_123",
      quantity: 2,
      variation: ["Large", "Blue"], // Optional
    },
    {
      product_id: "prod_456",
      quantity: 1,
    },
  ],
});

// Payment method will be selected by the user in the widget UI

widget.showPopup();

Sloudfront Payment (Manual Orders)

For manual orders with existing transaction/customer/business IDs:

import PaymentWidget from "sloud-payment-sdk";

const widget = new PaymentWidget({
  type: "sloudfront",
  public_key: "your-public-api-key",
  transaction_id: "txn_abc123",
  customer_id: "cust_xyz789",
  business_id: "biz_def456",
  amount: 5000,
  discount: 500,
  channel: "pickup", // "pickup" or "delivery"
  customer: {
    first_name: "Alice",
    last_name: "Johnson",
    phone_number: "+2348011223344",
    email: "[email protected]",
  },
  delivery_details: {
    street: "456 Oak Avenue",
    city: "Abuja",
    state: "FCT",
    country: "Nigeria",
  },
  products: [
    {
      product_id: "prod_789",
      quantity: 1,
    },
  ],
});

// Payment method will be selected by the user in the widget UI

widget.showPopup();

API

`new PaymentWidget(options: PaymentWidgetOptions)`

Creates a new payment widget instance.

Common Options (All Payment Types)

| Parameter | Type | Required | Description | | --------------- | --------- | -------- | -------------------------------------------------- | | type | PaymentType | Yes | Payment type: "external", "storefront", or "sloudfront" | | public_key | string | Yes | Your public API key for secure payments | | isLocalEnv | boolean | No | Set to true for local development environment |

External Payment Options

| Parameter | Type | Required | Description | | ---------- | --------- | -------- | ------------------------------------------ | | amount | number | Yes | Payment amount in smallest currency unit | | customer | Customer | Yes | Customer information object |

Storefront Payment Options

| Parameter | Type | Required | Description | | -------------------- | ------------------ | -------- | ------------------------------------------ | | slug | string | Yes | Store identifier | | amount | number | Yes | Additional amount (e.g., shipping fees) | | discount | number | No | Discount amount | | channel | ChannelType | Yes | Delivery channel: "pickup" or "delivery" | | customer | Customer | Yes | Customer information object | | delivery_details | DeliveryDetails | Yes | Delivery address and notes | | products | Product[] | Yes | Array of products in the order |

Note: Payment method is selected by the user within the widget UI based on available payment options.

Sloudfront Payment Options

| Parameter | Type | Required | Description | | -------------------- | ------------------ | -------- | ------------------------------------------ | | transaction_id | string | Yes | Existing transaction ID | | customer_id | string | Yes | Existing customer ID | | business_id | string | Yes | Existing business ID | | amount | number | Yes | Additional amount | | discount | number | No | Discount amount | | channel | ChannelType | Yes | Delivery channel: "pickup" or "delivery" | | customer | Customer | Yes | Customer information object | | delivery_details | DeliveryDetails | Yes | Delivery address and notes | | products | Product[] | Yes | Array of products in the order |

Note: Payment method is selected by the user within the widget UI based on available payment options.

Type Definitions

Customer

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

DeliveryDetails

interface DeliveryDetails {
  street: string;
  city: string;
  state: string;
  country: string;
  note?: string;
}

Product

interface Product {
  product_id: string;
  quantity: number;
  variation?: string[];
}

PaymentType

type PaymentType = "external" | "storefront" | "sloudfront";

ChannelType

type ChannelType = "pickup" | "delivery";

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 for all payment types:

import {
  PaymentWidget,
  validatePaymentWidgetOptions,
  PaymentWidgetValidationError,
} from "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

Extensible Payload Builders

The SDK uses a builder pattern for payment payloads and can be extended with custom payment types:

import {
  buildPaymentInstrumentPayload,
  registerPayloadBuilder,
  getRegisteredPaymentTypes,
} from "sloud-payment-sdk";

// Get all registered payment types
const types = getRegisteredPaymentTypes();
console.log(types); // ["external", "storefront", "sloudfront"]

// Build payload from options
const payload = buildPaymentInstrumentPayload({
  type: "external",
  // ... other options
});

TypeScript Support

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

import type {
  PaymentWidgetOptions,
  ExternalPaymentWidgetOptions,
  StorefrontPaymentWidgetOptions,
  SloudfrontPaymentWidgetOptions,
  PaymentType,
  ChannelType,
  Customer,
  DeliveryDetails,
  Product,
} from "sloud-payment-sdk";

// TypeScript will enforce correct fields based on payment type
const options: StorefrontPaymentWidgetOptions = {
  type: "storefront",
  public_key: "pk_test_123",
  slug: "my-store",
  // ... TypeScript ensures all required fields are present
};

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).