Overview

This document provides updated usage guidelines for the MzuniPay SDK, including how to integrate and customize the payment form in various environments.

Installation

Using NPM

Install the SDK into your project using npm:

npm install mzunipay-sdk

Using CDN (Normal JS)

For Normal JavaScript integration, include the SDK via a CDN:

<script src="https://cdn.jsdelivr.net/npm/mzunipay-sdk@latest/dist/index.umd.js"></script>

Quick Start

Here is a simple example of integrating the MzuniPay SDK with its updated API:

Basic Example

import MzuniPay from "mzunipay-sdk";

const mzuniPay = new MzuniPay("your-api-key-here");

mzuniPay.renderForm({
  containerId: "payment-form-container", // ID of the container element
  onSuccess: (response) => {
    console.log("Payment Successful!", response);
  },
  onError: (error) => {
    console.error("Payment Failed!", error);
  },
  styled: true, // Enable default styling (optional, default is true)
  buttonText: "Pay Now", // Custom button text
  defaultValues: {
    amount: 150.0, // Pre-fill the amount field
    description: "Product Purchase", // Pre-fill the description field
  },
});

Customization Options

You can customize the form layout, styles, and behavior using the options provided. Below is a table of the options:

Option	Type	Description	Default Value
`containerId`	`string`	The ID of the HTML element to mount the form into.	Required
`onSuccess`	`(response: any) => void`	Callback function invoked when the payment is successful.	Required
`onError`	`(error: any) => void`	Callback function invoked when the payment fails.	Required
`styled`	`boolean`	Whether to render the form with default styles.	`true`
`buttonText`	`string`	Custom text for the submit button.	`"Pay Now"`
`defaultValues`	`{ amount?: number; description?: string; }`	Default values for the `amount` and `description` fields.	`undefined`
`customStyles`	`{ form?, input?, button?, status? }`	Custom styles for the form, input fields, button, and status message using CSS properties.	`undefined`

Advanced Customization Example

import MzuniPay from "mzunipay-sdk";

const mzuniPay = new MzuniPay("your-api-key-here");

mzuniPay.renderForm({
  containerId: "custom-payment-form",
  onSuccess: (response) => {
    console.log("Payment Successful!", response);
  },
  onError: (error) => {
    console.error("Payment Failed!", error);
  },
  styled: true, // Use styled form
  buttonText: "Submit Payment", // Custom button text
  defaultValues: {
    amount: 200.0,
    description: "Order #1234",
  },
  customStyles: {
    form: {
      backgroundColor: "#f9f9f9",
      padding: "20px",
      borderRadius: "8px",
    },
    input: {
      padding: "10px",
      border: "1px solid #ddd",
    },
    button: {
      backgroundColor: "#007bff",
      color: "#fff",
    },
    status: {
      marginTop: "10px",
      fontSize: "14px",
    },
  },
});

Input Validation

The amount field has built-in validation to ensure:

Only numeric characters and one decimal point are allowed.
Invalid characters are automatically removed.

Handling Payments

To process payments, the form collects the following fields:

customer_email (required)
password (required)
amount (required, numeric)
description (optional)

The SDK interacts with the payment API via the processPayment method, sending the collected data to your backend.

Using with CDN

For developers who prefer Normal JavaScript or CDN-based integration:

<head>
  <script src="https://cdn.jsdelivr.net/npm/mzunipay-sdk@latest/dist/index.umd.js"></script>
</head>
<body>
  <div id="payment-form-container"></div>
  <script>
    const mzuniPay = new MzuniPay("your-api-key-here");
    mzuniPay.renderForm({
      containerId: "payment-form-container",
      onSuccess: (response) => console.log("Success:", response),
      onError: (error) => console.error("Error:", error),
      styled: true,
      buttonText: "Submit",
      defaultValues: {
        amount: 100.0,
        description: "Purchase Item A",
      },
      customStyles: {
        button: { backgroundColor: "blue", color: "white" },
      },
    });
  </script>
</body>

Notes

Replace "your-api-key-here" with your actual API key.
Ensure the container ID (e.g., payment-form-container) exists in the DOM.
Use the onSuccess and onError callbacks to handle the results of the payment process.
Test your integration in a staging environment before going live.