Paystack Integration Guides by Language and Framework

Paystack does not care what language you write. It is a REST API. You send HTTP requests to https://api.paystack.co, include your secret key in the Authorization header, and send or receive JSON. That is the entire protocol.

Here is what a transaction initialization looks like as a raw HTTP request:

POST https://api.paystack.co/transaction/initialize
Authorization: Bearer sk_test_xxxxxxxxxxxxx
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500000,
  "currency": "KES",
  "callback_url": "https://yourapp.com/payment/callback"
}

That request is the same whether you send it from Node.js, Python, PHP, Go, Ruby, Java, C#, or Dart. The language is just the HTTP client. fetch in JavaScript, requests in Python, Guzzle in PHP, net/http in Go. Different syntax, same bytes on the wire.

This is good news. It means three things:

• No vendor lock-in to a specific SDK. Paystack provides official libraries for some languages, but you never need them. The API is simple enough to call directly.
• You can port integrations between frameworks quickly. If you built Paystack into a Django app and now need it in FastAPI, the API calls are identical. Only the routing and request/response handling change.
• Debugging is framework-independent. When something fails, you check the HTTP status code, the Paystack error message, and your request payload. The framework is rarely the problem. The error reference applies to every stack.

The guides in this cluster take this universal API and show you exactly where to put each piece in your specific framework. Where does the secret key go? How do you set up the route for webhooks? How do you verify a signature in your middleware? Those are framework questions, not Paystack questions, and that is what each guide answers.

For the full picture of how Paystack works before you pick a framework guide, read the complete engineering guide.

JavaScript is the most common language in the Paystack ecosystem. Most African startups run Node.js on the backend and React or Vue on the frontend, so this is where the largest chunk of our guides live.

Next.js App Router

Next.js with the App Router (Next.js 13+) uses React Server Components and Route Handlers. Your Paystack secret key lives in a Route Handler (app/api/paystack/route.ts), and the frontend uses Paystack Inline or redirects. Server Actions can also initialize transactions directly.

• Accept payments in Next.js App Router
• Verify payments in Next.js App Router
• Handle webhooks in Next.js App Router
• Build subscriptions in Next.js App Router

Next.js Pages Router

The Pages Router uses API Routes (pages/api/) instead of Route Handlers. If your project is on Next.js 12 or earlier, or you have not migrated to the App Router yet, these guides are for you.

• Accept payments in Next.js Pages Router
• Verify payments in Next.js Pages Router
• Handle webhooks in Next.js Pages Router
• Build subscriptions in Next.js Pages Router

React (Client-Side with Separate Backend)

Plain React apps (Create React App, Vite, etc.) have no server. You use Paystack Inline on the client to collect payment, then call your own backend API to verify. The backend can be Express, FastAPI, Laravel, or anything else. These guides cover the React side.

• Accept payments in React
• Verify payments in React
• Handle webhooks with a React frontend
• Build subscriptions in React

Vue

Vue integrations follow the same pattern as React: Paystack Inline on the client, backend API for verification and webhooks. Vue's composition API makes the Paystack popup easy to wrap in a composable.

• Accept payments in Vue
• Verify payments in Vue
• Handle webhooks with a Vue frontend
• Build subscriptions in Vue

Nuxt

Nuxt gives you server routes out of the box (server/api/), so you get the full-stack experience without a separate backend. Your Paystack secret key goes in a server route, and Nuxt handles the rest.

• Accept payments in Nuxt
• Verify payments in Nuxt
• Handle webhooks in Nuxt
• Build subscriptions in Nuxt

Angular

Angular uses services and dependency injection. The Paystack integration lives in a service that loads Paystack Inline, and your backend (often a separate Node or .NET API) handles verification and webhooks.

• Accept payments in Angular
• Verify payments in Angular
• Handle webhooks with an Angular frontend
• Build subscriptions in Angular

Svelte and SvelteKit

SvelteKit has server-side load functions and API endpoints (+server.ts files) that make Paystack integration clean. Plain Svelte without SvelteKit needs a separate backend, similar to plain React or Vue.

• Accept payments in Svelte/SvelteKit
• Verify payments in Svelte/SvelteKit
• Handle webhooks in Svelte/SvelteKit
• Build subscriptions in Svelte/SvelteKit

Node.js and Express

Express is still the most common Node.js backend framework in Africa. The integration is straightforward: Express routes handle initialization, verification, and webhook receipt. Use fetch (Node 18+) or axios to call the Paystack API.

• Accept payments in Node.js/Express
• Verify payments in Node.js/Express
• Handle webhooks in Node.js/Express
• Build subscriptions in Node.js/Express

NestJS

NestJS adds structure to Node.js with modules, controllers, services, and decorators. Your Paystack logic lives in a service, the controller handles routes, and guards can protect webhook endpoints. NestJS's dependency injection makes testing Paystack calls easy to mock.

• Accept payments in NestJS
• Verify payments in NestJS
• Handle webhooks in NestJS
• Build subscriptions in NestJS

Supabase Edge Functions

Supabase Edge Functions run on Deno. They are good for serverless Paystack integrations where you want to keep your backend light. The function receives the request, calls Paystack, writes to your Supabase database, and returns. No server to manage.

• Accept payments in Supabase Edge Functions
• Verify payments in Supabase Edge Functions
• Handle webhooks in Supabase Edge Functions
• Build subscriptions in Supabase Edge Functions

Firebase Cloud Functions

Firebase Cloud Functions (v2, based on Cloud Run) let you write Paystack handlers as serverless functions. You deploy them alongside your Firestore rules and Firebase Auth. Good for teams already deep in the Firebase ecosystem.

• Accept payments in Firebase Cloud Functions
• Verify payments in Firebase Cloud Functions
• Handle webhooks in Firebase Cloud Functions
• Build subscriptions in Firebase Cloud Functions

Python is the second most popular backend language among African developers, especially for fintech teams and data-heavy products. Paystack integration in Python means using the requests library (or httpx for async) to call the API, then plugging the routes into your framework of choice.

Django

Django's view system handles Paystack routes. Your webhook endpoint is a Django view with @csrf_exempt (because Paystack cannot send CSRF tokens). Use Django's ORM to record transactions. The guides cover both function-based and class-based views.

• Accept payments in Django
• Verify payments in Django
• Handle webhooks in Django
• Build subscriptions in Django

Django REST Framework (DRF)

If your Django project exposes a REST API through DRF, these guides show you how to build Paystack endpoints as DRF views with serializers and proper response formatting. Useful for mobile apps and SPAs that talk to a Django API.

• Accept payments in DRF
• Verify payments in DRF
• Handle webhooks in DRF
• Build subscriptions in DRF

FastAPI

FastAPI is async-native, so you can use httpx.AsyncClient to call Paystack without blocking. Type hints and Pydantic models give you automatic request validation. FastAPI's dependency injection works well for sharing a Paystack client across routes.

• Accept payments in FastAPI
• Verify payments in FastAPI
• Handle webhooks in FastAPI
• Build subscriptions in FastAPI

Flask

Flask is minimal by design. You add routes, call Paystack with requests, and return JSON. No batteries included means no magic to fight. If you want the simplest possible Python integration, Flask is it.

• Accept payments in Flask
• Verify payments in Flask
• Handle webhooks in Flask
• Build subscriptions in Flask

PHP runs a large share of web applications in Africa, especially in Nigeria where Laravel is the dominant framework. Paystack itself was built in Lagos, so PHP support is first-class. The official paystack-php library exists, but you can also call the API directly with Guzzle or even curl.

Laravel

Laravel is the most popular PHP framework for Paystack integrations. You can use the paystack-php library or call the API through Laravel's HTTP client (which wraps Guzzle). Webhook routes go in routes/api.php to skip CSRF verification. Laravel's event system works well for dispatching jobs after payment confirmation.

• Accept payments in Laravel
• Verify payments in Laravel
• Handle webhooks in Laravel
• Build subscriptions in Laravel

Symfony

Symfony is less common than Laravel in the African dev scene but used in larger enterprise projects. The integration uses Symfony's HttpClient component and controller routes. Webhook handling works through a dedicated controller action.

• Accept payments in Symfony
• Verify payments in Symfony
• Handle webhooks in Symfony
• Build subscriptions in Symfony

These frameworks are less common in the African startup scene but popular in enterprise environments, fintech backends, and teams with specific language preferences.

Ruby on Rails

Rails handles Paystack with Net::HTTP or the httparty gem. Controllers receive webhooks, models store transaction records, and Active Job processes async work after payment. Rails conventions make the integration predictable.

• Accept payments in Ruby on Rails
• Verify payments in Ruby on Rails
• Handle webhooks in Ruby on Rails
• Build subscriptions in Ruby on Rails

Go

Go's net/http standard library is all you need. No external dependencies required. Go's strong typing and built-in JSON marshalling make Paystack response handling clean. Good for high-throughput payment services where you want low latency and small memory footprint.

• Accept payments in Go
• Verify payments in Go
• Handle webhooks in Go
• Build subscriptions in Go

Spring Boot (Java/Kotlin)

Spring Boot is common in African banks and large fintech companies. The integration uses RestTemplate or WebClient (reactive) to call Paystack. Spring's @RestController annotation handles webhook endpoints. Spring Security can validate webhook signatures in a filter.

• Accept payments in Spring Boot
• Verify payments in Spring Boot
• Handle webhooks in Spring Boot
• Build subscriptions in Spring Boot

ASP.NET Core (C#)

ASP.NET Core is used by some enterprise teams in South Africa, Kenya, and Nigeria. The integration uses HttpClient (injected via IHttpClientFactory) and controller actions. ASP.NET Core's middleware pipeline is a natural place for webhook signature verification.

• Accept payments in ASP.NET Core
• Verify payments in ASP.NET Core
• Handle webhooks in ASP.NET Core
• Build subscriptions in ASP.NET Core

Mobile apps cannot safely store your Paystack secret key. The secret key must stay on your server. So every mobile Paystack integration has two parts: the mobile app (which shows the payment UI and collects the result) and a backend API (which initializes transactions, verifies payments, and receives webhooks).

The mobile guides in this cluster cover both parts. They show the mobile-side code and the backend calls your app needs to make.

Flutter

Flutter is the most popular cross-platform framework among African mobile developers. You can use the paystack_flutter package for a pre-built payment UI, or load Paystack Inline in a WebView. The backend is usually Node.js, Django, or Firebase Cloud Functions.

• Accept payments in Flutter
• Verify payments in Flutter
• Handle webhooks for Flutter apps
• Build subscriptions in Flutter

React Native

React Native integrations typically use react-native-paystack-webview to show the Paystack checkout inside your app. The JavaScript side calls your backend API, which does the actual Paystack API calls. If you already have a Node.js backend, the server code is identical to a web integration.

• Accept payments in React Native
• Verify payments in React Native
• Handle webhooks for React Native apps
• Build subscriptions in React Native

Android (Kotlin)

Native Android apps can use Paystack's Android SDK or load the checkout in a WebView using Android's WebViewClient. Kotlin coroutines handle async API calls to your backend. The webhook and verification logic lives on your server, not in the Android app.

• Accept payments in Android/Kotlin
• Verify payments in Android/Kotlin
• Handle webhooks for Android apps
• Build subscriptions in Android/Kotlin

iOS (Swift)

iOS apps can load the Paystack checkout in a WKWebView or use a native form with the Paystack iOS SDK. Swift's URLSession calls your backend to initialize and verify. As with all mobile platforms, the secret key must never appear in your app bundle.

• Accept payments in iOS/Swift
• Verify payments in iOS/Swift
• Handle webhooks for iOS apps
• Build subscriptions in iOS/Swift

No matter what framework you pick, your Paystack integration needs to handle four tasks. Every guide in this cluster is organized around these four tasks.

1. Accept a Payment

This is the starting point. You call POST /transaction/initialize with the customer's email, amount (in the smallest currency unit, e.g., kobo or cents), and a callback URL. Paystack returns an authorization_url where the customer pays. After payment, the customer is redirected back to your callback URL with a reference in the query string.

For frontend frameworks, you can skip the redirect and use Paystack Inline (a JavaScript popup) that handles payment in a modal without leaving your page.

See the accepting payments guide for the full breakdown of initialization, channels, and checkout options.

2. Verify a Payment

After the customer pays (or claims to have paid), you call GET /transaction/verify/:reference using your secret key. You check that the response shows status: "success" and that the amount and currency match what you expected. This is the single most important security step. Never grant access or deliver goods based on a client-side callback alone.

3. Handle Webhooks

Paystack sends POST requests to your webhook URL whenever something happens: a charge succeeds, a transfer completes, a subscription renews, a charge-back is filed. You must validate the x-paystack-signature header using HMAC SHA-512 with your secret key, return a 200 status immediately, then process the event asynchronously.

Webhooks are your safety net. If the customer closes the browser before the redirect, your webhook still fires. If the network drops during verification, the webhook still fires. Build your system so that webhooks are the source of truth, not redirects.

Read the webhooks engineering guide for retry logic, event types, and security patterns.

4. Build Subscriptions

Recurring billing means creating a Plan (with an interval and amount), then subscribing a customer to that plan. Paystack handles the charging schedule. You listen for subscription.create, invoice.payment_failed, and subscription.disable webhook events to keep your app in sync.

Each framework guide in this cluster covers all four tasks for your specific stack. Pick your framework from the lists above and work through the four guides in order.

This is the hub page for the framework integration cluster. It contains 100 spoke articles organized as a matrix of 25 frameworks and 4 tasks.

The 25 frameworks:

• JavaScript/TypeScript (11): Next.js App Router, Next.js Pages Router, React, Vue, Nuxt, Angular, Svelte/SvelteKit, Node.js/Express, NestJS, Supabase Edge Functions, Firebase Cloud Functions
• Python (4): Django, Django REST Framework, FastAPI, Flask
• PHP (2): Laravel, Symfony
• Other server-side (4): Ruby on Rails, Go, Spring Boot, ASP.NET Core
• Mobile (4): Flutter, React Native, Android/Kotlin, iOS/Swift

The 4 tasks:

• Accept payments (initialize a transaction, show checkout, handle callback)
• Verify payments (confirm the transaction server-side before fulfilling)
• Handle webhooks (receive events, validate signatures, process asynchronously)
• Build subscriptions (create plans, subscribe customers, handle renewals and failures)

Every guide follows the same structure: what you need before you start, the complete code, an explanation of each step, and common mistakes to avoid. The code examples are designed to work as-is in a fresh project with your Paystack test keys.

How to Use This Cluster

1. Read the pillar first. The complete engineering guide explains how Paystack works at a conceptual level. Read it before jumping into framework-specific code.
2. Pick your framework. Find your stack in the lists above and open the "Accept payments" guide for that framework. That is your starting point.
3. Work through all four tasks. Accept, verify, webhooks, subscriptions. Do them in order. Each guide builds on the previous one.
4. Check the error reference. When you hit an error, check the error reference before searching Stack Overflow. The answer is probably there.

Which Framework Should You Choose?

If you are starting a new project and want a recommendation:

• Solo developer building a web app: Next.js App Router. Full-stack in one project, great deployment story on Vercel, and the largest community of African developers using it with Paystack.
• Team with Python experience: Django or FastAPI. Django if you want batteries included (admin panel, ORM, auth). FastAPI if you want async performance and modern Python conventions.
• Team with PHP experience: Laravel. Dominant in Nigeria, strong Paystack community support, and plenty of local developers who know it.
• Building a mobile app: Flutter with a Node.js or Supabase backend. Flutter gives you Android and iOS from one codebase. Supabase Edge Functions keep the backend minimal.
• High-throughput payment service: Go. Minimal memory, fast startup, and the standard library is all you need.
• Enterprise or banking environment: Spring Boot or ASP.NET Core. These are the frameworks your compliance team already trusts.

But honestly, it does not matter much. Paystack is a REST API. Pick the framework your team already knows and get building. You can always switch later because the API calls are identical.

Payment APIs in Africa change fast. New channels appear, country-specific rules shift, and frameworks release breaking updates that affect your integration code. We track all of it.

Join the McTaba Labs newsletter for practical updates on Paystack, M-Pesa, Flutterwave, and the full African payment stack. No hype, no filler. Just the technical changes that affect your code.

Subscribe to the newsletter