@ngelekanyo/payfast-subscribe-client

A lightweight TypeScript SDK for initiating and submitting PayFast subscription payments from the browser.

🔗 Designed to work with @ngelekanyo/payfast-subscribe — a backend package for handling PayFast signatures, subscriptions, and ITN.

✨ Features

• Initiate subscription or once-off payments
• Submit payment forms to PayFast securely
• Pause, unpause, cancel, and fetch subscriptions
• Written in TypeScript, works in all frontend frameworks

📦 Installation

npm install @ngelekanyo/payfast-subscribe-client

🧩 Prerequisites

This package requires a backend using @ngelekanyo/payfast-subscribe to:

• Sign and prepare payment data
• Handle PayFast's ITN (Instant Transaction Notifications)
• Manage subscriptions securely

🚀 Usage

import {
  initPayFastClient,
  PayFastService,
  PaymentData
} from "@ngelekanyo/payfast-subscribe-client";

// 1. Set your backend API base URL
initPayFastClient("https://your-backend.com");

// 2. Prepare payment data
const paymentData: PaymentData = {
  amount: "99.00",
  item_name: "Pro Plan",
  item_description: "Monthly subscription to Pro Plan",
  name_first: "John",
  name_last: "Doe",
  email_address: "[email protected]",
  m_payment_id: "uuid-123",
  subscription_type: "1",
  billing_date: "2025-07-05",
  recurring_amount: "99.00",
  frequency: "3",
  cycles: "0",
  subscription_notify_email: "[email protected]",
  subscription_notify_buyer: "1"
};

const payfast = new PayFastService();

// 3. Initiate payment via backend
const response = await payfast.initiatePayment(paymentData);

// 4. Submit to PayFast
payfast.submitPayment(response.paymentData, response.payfastUrl);

 const handlePause = async (token: string) => {
    setLoading(true);
    setError(null);
    try {
      const payfast = new PayFastService();
      const response: PayFastActionResponse = await payfast.pauseSubscription(
        token
      );

      const success =
        response?.data?.code === 200 && response?.data?.status === "success";
      if (!success) {
        throw new Error(response?.data?.data?.message || "Pause failed");
      }

      await fetchSubscriptions();
    } catch (err: any) {
      setError(err.message || "Failed to pause subscription");
    } finally {
      setLoading(false);
    }
  };

🔧 Available Methods

| Method | Description | |--------|-------------| | initPayFastClient(url) | Set the backend base URL | | initiatePayment(data) | Call backend to prepare PayFast form | | submitPayment(data, url) | Submit a form to PayFast | | pauseSubscription(token) | Pause a subscription | | unpauseSubscription(token) | Resume a paused subscription | | cancelSubscription(token, subscriptionId) | Cancel a subscription | | cancelSubscription(token) | Cancel a subscription | | fetchSubscription(token) | Retrieve PayFast subscription details |

⚠️ Pause/Unpause Disclaimer

Important Notice:
The pause and unpause subscription features provided by this package rely on PayFast's native subscription behavior. Please review the following carefully before implementing:

• Pausing a subscription does not cancel it — it only delays future billing by the number of paused cycles (e.g. cycles: 1 = 1 billing interval).
• The subscription end date is automatically extended by PayFast for each paused cycle.
• Unpausing early (before the pause period ends) will not adjust the next billing date — billing still resumes after the full pause duration.
• ⚠️ This may result in a user receiving more than a full billing cycle of access without being charged, unless you enforce access control on your side.
• This package does not automatically manage user access during pause periods. You must implement that logic in your backend or authorization layer.

📚 For accurate and up-to-date details on PayFast's pause/unpause behavior, refer to the official PayFast documentation:

👉 PayFast Developer Docs

📚 Backend Setup

Use @ngelekanyo/payfast-subscribe in your Node.js/Express backend to:

• Handle /api/payfast/initiate
• Handle /api/payfast/notify (ITN callback)
• Handle /api/payfast/cancel/:token
• Handle /api/payfast/cancel/:token/:subscriptionId
• (And optionally) pause/unpause/fetch routes

🔒 Your backend should manage signing, verifying, and securing transactions.

👥 Maintainers

• @ngelekanyo (author & maintainer)

🤝 Contributing

Contributions, suggestions, and issues welcome!
Please open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.
See the LICENSE file for details.

MIT — © 2025 Ngelekanyo Masera