https://github.com/bazileros/payfastt
Payfast Component
https://github.com/bazileros/payfastt
convex convex-component payfast payment-integration typescript
Last synced: 15 days ago
JSON representation
Payfast Component
- Host: GitHub
- URL: https://github.com/bazileros/payfastt
- Owner: bazileros
- License: apache-2.0
- Created: 2026-06-18T20:34:19.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-07-03T05:10:44.000Z (21 days ago)
- Last Synced: 2026-07-03T06:23:55.591Z (21 days ago)
- Topics: convex, convex-component, payfast, payment-integration, typescript
- Language: TypeScript
- Homepage: https://pfdocs.surestrat.xyz
- Size: 694 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
payfastt
PayFast payments for Convex apps
Features ·
Quick Start ·
Docs ·
Structure
---
## Features
**@bazileros/payfast** is a [Convex](https://convex.dev) component that integrates the [PayFast](https://www.payfast.co.za) 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
```bash
npm install @bazileros/payfast
```
### 1. Register the component
```ts
// 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
```bash
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
```ts
// 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
```tsx
import { PayfastProvider, usePayfastCheckout } from "@bazileros/payfast/react";
import { components } from "../convex/_generated/api";
function Root() {
return (
);
}
function DonateButton() {
const { generateCheckout, loading } = usePayfastCheckout({
amount: 100,
itemName: "Donation",
});
return Donate R100;
}
```
See the full [documentation →](https://payfastt.dev/docs)
## 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](https://skills.sh).
## License
Apache 2.0 — see [LICENSE](LICENSE).