feat: add Paystack payment integration

[MarvelNwachukwu]

Summary

Adds Paystack as a payment provider for Cal.com. Paystack is Africa's leading payment gateway, processing payments for 200,000+ businesses across Nigeria, Ghana, South Africa, Kenya, and more.

Why: Cal.com currently supports Stripe, PayPal, and a few crypto payment options — none of which serve the African market well. Paystack fills this gap by providing a payment option that supports local currencies (NGN, GHS, ZAR, KES, USD) and local payment methods (bank transfers, mobile money, USSD) that African users expect.

What's included

• PaymentService — Implements IAbstractPaymentService with create, refund, update, and deletePayment methods
• PaystackClient — REST API wrapper for Paystack (initialize transaction, verify, refund)
• Webhook endpoint — Receives Paystack events with HMAC-SHA512 signature verification for secure payment confirmation
• Verify endpoint — Callback-based payment verification (Paystack redirects here after payment)
• Event type configuration UI — App card interface for setting price, currency, refund policy, and payment option
• Setup page — Authenticated form for entering Paystack API keys (public key + secret key)
• Payment component — Uses Paystack's inline popup checkout on the /payment/[uid] page
• App install flow — Uses isOAuth: true pattern (same as HitPay) to route through the accounts step → add.ts → setup page

Architecture

Follows the established Cal.com payment app patterns used by HitPay and Stripe:

packages/app-store/paystack/
├── _metadata.ts                          # App metadata
├── config.json                           # App store config
├── zod.ts                                # Zod schemas (appDataSchema, appKeysSchema)
├── api/
│   ├── add.ts                            # Install handler → redirects to setup
│   ├── verify.ts                         # Payment callback verification
│   └── webhook.ts                        # Webhook with signature verification
├── components/
│   ├── EventTypeAppCardInterface.tsx      # Event type app card
│   ├── EventTypeAppSettingsInterface.tsx  # Price/currency/refund settings
│   └── PaystackPaymentComponent.tsx       # Inline checkout popup
├── lib/
│   ├── PaymentService.ts                 # IAbstractPaymentService implementation
│   ├── PaystackClient.ts                 # Paystack REST API client
│   ├── verifyWebhookSignature.ts         # HMAC-SHA512 verification
│   ├── currencyOptions.ts                # Supported currencies
│   └── __tests__/                        # Unit tests
└── pages/setup/
    └── _getServerSideProps.ts            # Authenticated setup page props

Payment flow

1. Host installs Paystack app → enters API keys on setup page
2. Host enables Paystack on event type → sets price, currency, refund policy
3. Attendee books event → clicks "Pay to book"
4. Booking created with PENDING status → redirect to /payment/[uid]
5. Paystack inline popup opens → attendee completes payment
6. Paystack sends webhook → signature verified → booking confirmed
7. Alternatively: Paystack redirects to /api/integrations/paystack/verify → payment verified → booking confirmed

Test plan

• Install Paystack from /apps/paystack → verify setup page appears
• Enter Paystack test API keys → verify they save correctly
• Configure event type with Paystack payment (price, currency) → verify app card shows
• Book event as attendee → verify "Pay to book" button and price display
• Complete payment via Paystack popup → verify booking is confirmed
• Test refund flow from bookings page
• Test webhook endpoint with Paystack test events

Screenshots

[CLAassistant]

All committers have signed the CLA.

[cubic-dev-ai]

3 issues found across 24 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/app-store/paystack/api/webhook.ts">

<violation number="1" location="packages/app-store/paystack/api/webhook.ts:112">
P1: Webhook idempotency check is non-atomic, allowing concurrent duplicate events to both process payment success and trigger duplicate side effects.</violation>
</file>

<file name="packages/app-store/paystack/components/EventTypeAppSettingsInterface.tsx">

<violation number="1" location="packages/app-store/paystack/components/EventTypeAppSettingsInterface.tsx:146">
P2: Clearing the number input stores NaN in refundDaysCount because parseInt("") is NaN; this can propagate into saved app data and the controlled value prop.</violation>
</file>

<file name="packages/app-store/paystack/components/PaystackPaymentComponent.tsx">

<violation number="1" location="packages/app-store/paystack/components/PaystackPaymentComponent.tsx:43">
P2: Paystack amount display incorrectly divides by 100 for all currencies, causing 100× under-display for zero-decimal currencies (e.g., XOF/RWF).</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

2 issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/app-store/paystack/api/add.ts">

<violation number="1" location="packages/app-store/paystack/api/add.ts:15">
P2: Invalid `teamId` query values are coerced to `NaN` and treated as falsy, bypassing team-admin validation and silently falling back to user-scoped install instead of returning a validation error.</violation>

<violation number="2" location="packages/app-store/paystack/api/add.ts:22">
P2: Non-atomic `findFirst`→`create` install flow can create duplicate credentials under concurrent requests.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/app-store/paystack/api/webhook.ts">

<violation number="1" location="packages/app-store/paystack/api/webhook.ts:114">
P1: Idempotency lock conflates processing lock with final success state, causing unrecoverable stuck payments when exceptions occur after setting `success: true`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/app-store/paystack/api/webhook.ts">

<violation number="1" location="packages/app-store/paystack/api/webhook.ts:145">
P1: New rollback catch resets `payment.success` even after successful processing (because `handlePaymentSuccess` throws 200 by design), breaking idempotency and enabling duplicate side effects.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P1: New rollback catch resets payment.success even after successful processing (because handlePaymentSuccess throws 200 by design), breaking idempotency and enabling duplicate side effects.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/app-store/paystack/api/webhook.ts, line 145:

<comment>New rollback catch resets `payment.success` even after successful processing (because `handlePaymentSuccess` throws 200 by design), breaking idempotency and enabling duplicate side effects.</comment>

<file context>
@@ -120,31 +120,36 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
+        appSlug: "paystack",
+        traceContext,
+      });
+    } catch (processingError) {
+      // Rollback so webhook retries can re-process this payment
       await prisma.payment.update({
</file context>

[Adebesin-Cell]

This would be a great addition 🔥