payfastt

PayFast payments for Convex apps

Features · Quick Start · Docs · Structure

---

Features

@bazileros/payfast is a Convex component that integrates the PayFast payment gateway into your Convex application. Drop it in with app.use(payfast) and start accepting payments.

• One-time payments via PayFast Custom Integration (signed form redirect — PCI-compliant)
• Recurring billing — create, pause, unpause, cancel, and update subscriptions
• Tokenized charges — ad-hoc charges against existing subscription tokens
• Refunds — full and partial via PayFast REST API
• Onsite payments — hosted iframe widget via POST /onsite/process
• Transaction history — query PayFast transaction records
• Stored credit cards — query saved cards via REST API
• ITN webhook — echo-back-validated + source IP checked + signature verified
• React hooks — usePayfastCheckout, useTransactions, useSubscriptions, useSubscriptionActions, usePayfastOnsite, useAdhocCharge, useRefund
• Context provider — PayfastProvider eliminates passing components.payfast to every hook
• Sandbox mode — toggle via PAYFAST_SANDBOX env var
• Type-safe — full TypeScript types for requests, responses, and webhook events

Quick Start

npm install @bazileros/payfast

1. Register the component

// convex/convex.config.ts
import { defineApp } from "convex/server";
import payfast from "@bazileros/payfast/convex.config";

const app = defineApp();
app.use(payfast);
export default app;

2. Set environment variables

npx convex env set PAYFAST_MERCHANT_ID    your_merchant_id
npx convex env set PAYFAST_MERCHANT_KEY   your_merchant_key
npx convex env set PAYFAST_PASSPHRASE     your_passphrase
npx convex env set PAYFAST_SANDBOX        true

3. Mount the ITN webhook

// convex/http.ts
import { httpRouter } from "convex/server";
import { registerRoutes } from "@bazileros/payfast/http";
import { components } from "./_generated/api";

const http = httpRouter();
registerRoutes(http, components.payfast);
export default http;

4. Use it

import { PayfastProvider, usePayfastCheckout } from "@bazileros/payfast/react";
import { components } from "../convex/_generated/api";

function Root() {
  return (
    <PayfastProvider component={components.payfast}>
      <DonateButton />
    </PayfastProvider>
  );
}

function DonateButton() {
  const { generateCheckout, loading } = usePayfastCheckout({
    amount: 100,
    itemName: "Donation",
  });
  return <button onClick={generateCheckout} disabled={loading}>Donate R100</button>;
}

See the full documentation →

Project Structure

payfastt/
├── packages/
│   ├── payfast/          # @bazileros/payfast — the Convex component
│   │   ├── src/
│   │   │   ├── client/   # Payfast class + registerRoutes helper
│   │   │   ├── component/  # Queries, mutations, actions, schema, HTTP routes
│   │   │   └── react/    # React hooks
│   │   └── SKILL.md      # AI agent skill file (skills.sh compatible)
│   ├── backend/          # Example Convex backend using the component
│   ├── ui/               # Shared shadcn/ui primitives
│   └── infra/            # Deployment (Cloudflare Workers via Alchemy)
├── apps/
│   ├── web/              # Example TanStack Router SPA
│   └── docs/             # Documentation site (Astro Starlight)
└── .github/
    └── workflows/        # CI/CD: test, deploy, publish

Scripts

Command	Description
bun run dev	Start all apps in development mode
bun run build	Build all packages and apps
bun run bootstrap	First-time setup (codegen + build)
bun run check	Biome lint + format check
bun run check-types	TypeScript type check all packages

Agent / AI Support

A SKILL.md ships with the npm package for AI agent discoverability. Compatible with Claude Code, Cursor, opencode, Cline, Windsurf, and 30+ other agents via skills.sh.

License

Apache 2.0 — see LICENSE.