How to Integrate Paystack: A Developer's Guide for Nigeria

Paystack is Nigeria's most widely used payment processing platform. It handles card payments, bank transfers, USSD payments, and mobile wallets. If you are building a product for the Nigerian market, Paystack integration is one of the most practical skills you can learn.

Step 1: Create a Paystack account. Go to paystack.com and sign up. The registration process includes KYC (Know Your Customer) verification, which requires your BVN and business details for live transactions. For testing and development, you can start immediately with test mode.

Step 2: Get your API keys. In your Paystack dashboard, go to Settings, then API Keys & Webhooks. You will find two sets of keys: test keys (prefixed with sk_test_ and pk_test_) and live keys (prefixed with sk_live_ and pk_live_). Use test keys during development. Store your secret key securely. Never expose it in client-side code or commit it to Git.

Step 3: Understand the payment flow. Paystack follows a straightforward pattern: your backend initializes a transaction, the user completes payment on Paystack's interface (either a redirect page or an inline popup), Paystack redirects the user back to your site with a reference, and your backend verifies the payment using that reference. Additionally, Paystack sends a webhook to your server for real-time notification.

To start a payment, your backend sends a POST request to Paystack's initialize endpoint. Here is what that looks like conceptually (the exact implementation depends on your backend language and framework).

Endpoint: POST https://api.paystack.co/transaction/initialize

Required fields: email (the customer's email address) and amount (in kobo, so NGN 1,000 is sent as 100000). Optional fields include reference (your own transaction ID), callback_url (where to redirect after payment), and metadata (any additional data you want attached to the transaction).

Authentication: Include your secret key in the Authorization header as "Bearer sk_test_your_key_here".

Response: Paystack returns an authorization_url (the checkout page URL) and a reference. Redirect your user to the authorization_url, or use the Paystack inline JavaScript library to open a popup instead.

The inline popup option: Instead of redirecting users to a separate Paystack page, you can embed the Paystack checkout as a popup on your own page using their JavaScript SDK. Include the Paystack script tag in your HTML, then call PaystackPop.setup() with your public key, email, amount, and callback function. This provides a smoother user experience because the customer never leaves your site.

Common mistake: Sending the amount in naira instead of kobo. If you want to charge NGN 5,000, send 500000, not 5000. This is the single most common Paystack integration bug.

After a customer completes payment, Paystack redirects them back to your callback_url with a reference parameter. You must verify this payment on your backend before fulfilling the order.

Endpoint: GET https://api.paystack.co/transaction/verify/:reference

Authentication: Same Bearer token with your secret key.

What to check in the response: The status field should be "success". The amount should match what you expected. The currency should be NGN. If any of these do not match, do not fulfill the order.

Why this matters: A malicious user could modify the client-side callback to fake a successful payment. Server-side verification catches this because you are asking Paystack directly whether the money was received. This is not optional security. It is a fundamental requirement. Skipping verification is how developers lose money.

Idempotency: Your verification and order fulfillment logic should be idempotent. If a user refreshes the callback page, your server might receive the verification request twice. Make sure processing the same reference twice does not create duplicate orders or double-charge the customer. Check whether the transaction reference has already been processed before fulfilling.

Webhooks are Paystack's way of notifying your server about events in real time. When a payment succeeds, fails, or is abandoned, Paystack sends a POST request to a URL you specify in your dashboard settings.

Setting up: In your Paystack dashboard, go to Settings, then API Keys & Webhooks, and enter your webhook URL. This should be a publicly accessible endpoint on your server (not localhost during development, but you can use tools like ngrok for testing).

Webhook verification: Paystack signs every webhook with a hash using your secret key. Your server must verify this signature before processing the event. Compute an HMAC SHA-512 hash of the request body using your secret key and compare it to the x-paystack-signature header. If they do not match, reject the request.

Why webhooks matter: The callback URL redirect depends on the user's browser. If the user closes their browser during payment, or if their network drops after payment completes, the redirect never happens. Your server never gets the verification request. Without webhooks, you would miss successful payments. Webhooks give you a server-to-server notification that does not depend on the user's browser behavior.

Webhook best practice: Return a 200 status code immediately when you receive a webhook, then process it asynchronously. If your processing takes too long and you do not return 200 quickly, Paystack will retry the webhook, potentially causing duplicate processing.

Paystack supports multiple payment methods, and Nigerian customers use all of them.

Card payments: The default. Customers enter their card details on the Paystack checkout. Supported cards include Visa, Mastercard, and Verve (Nigeria's local card network). Verve support is important because many Nigerian bank cards are Verve cards.

Bank transfers: Paystack generates a temporary bank account number. The customer transfers to that account from their banking app or USSD. Payment is confirmed when the transfer settles. This is increasingly popular in Nigeria because it avoids card details and works for customers whose cards have online transaction limits.

USSD: Customers dial a USSD code (like *737# for GTBank) to authorize the payment from their phone. No internet required on the customer's end. This matters in Nigeria where not every customer has a smartphone or consistent data.

Mobile money: Paystack supports mobile money in some markets. In Nigeria, the mobile money ecosystem is different from East Africa. Focus on card, bank transfer, and USSD as your primary channels.

You can specify which channels to display using the channels parameter when initializing a transaction. For the broadest reach in Nigeria, include card, bank, and ussd.

The best way to learn Paystack integration is to build it. Start with a simple project: a donation page or a product purchase page. Initialize a transaction, handle the redirect, verify the payment, and process the webhook. Deploy it using test keys and walk through the full flow.

Paystack's official documentation (paystack.com/docs) is well-written and includes code examples in multiple languages. Their API reference is comprehensive. Start there.

For a more structured learning experience, McTaba's Full-Stack Software and AI Engineering course (KES 120,000, roughly NGN 140,000 to 220,000; exchange rates fluctuate, check current price at checkout) teaches payment integration as part of its full-stack curriculum. McTaba accepts NGN and card payments via Paystack. The course covers the architecture patterns (webhook handling, idempotency, async flows) that apply to any payment gateway.

Once you have a working Paystack integration in your portfolio, you have a skill that directly translates to job opportunities in Nigerian fintech. Read our Flutterwave integration guide next to learn the second major payment gateway. Having both on your resume covers the majority of Nigerian payment processing.