Paystack in Nigeria: Complete Developer Guide

Paystack launched in Lagos in 2016 and built its product around the Nigerian payments landscape. That history matters for developers because it means Nigeria gets features first, has the most supported banks, and has the most battle-tested infrastructure. When Paystack releases a new payment channel or API endpoint, Nigeria is almost always the first market where it is available.

The Nigerian market has specific characteristics that shape how you build payment flows:

• Card penetration is growing but not universal. Millions of Nigerians have debit cards (mostly Verve, then Mastercard and Visa), but a significant portion of the population still relies on bank transfers and USSD.
• Bank transfers are dominant for certain segments. For B2B transactions, high-value purchases, and tech-savvy users, bank transfers via Paystack's dedicated virtual accounts often convert better than cards.
• USSD fills the gap. Customers without smartphones or stable data connections can pay via USSD by dialing their bank's code. This is critical if your product serves mass-market or rural users.
• The naira (NGN) is the local currency. All domestic transactions happen in NGN. Amounts in the API are always in kobo. One naira equals 100 kobo.
• Regulatory environment is active. The Central Bank of Nigeria (CBN) regulates payment processors and periodically issues directives that affect settlement, KYC requirements, and cross-border transactions.

If you are building for the Nigerian market, Paystack gives you the most options of any African payment gateway. The question is not whether Paystack supports what you need, but which combination of payment channels will convert best for your specific audience.

Setting up Paystack for a Nigerian business follows a straightforward path, but there are specific documents and verifications required. Here is the process from signup to your first live transaction.

Step 1: Create a Paystack account

Sign up at paystack.com with your business email. You get immediate access to test mode with test API keys. You can start building and testing your integration before completing business verification.

Step 2: Complete business verification

To go live, Paystack requires your CAC registration certificate (or Business Name registration for sole proprietors), BVN of the business owner or director, a valid government-issued ID, and your bank account details for settlement. The verification process typically takes a few business days.

Step 3: Get your live API keys

Once verified, your live secret key and public key become available in the Paystack dashboard. The secret key is used server-side for initializing transactions and verifying payments. The public key is used client-side with Paystack Popup or Inline JS.

Step 4: Initialize your first transaction

// Initialize a transaction for a Nigerian customer
const response = await fetch('https://api.paystack.co/transaction/initialize', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.com',
    amount: 500000, // 5,000 NGN in kobo
    currency: 'NGN',
    reference: 'order_' + Date.now(),
    callback_url: 'https://yoursite.com/payment/callback',
  }),
});

const data = await response.json();
// Redirect customer to data.data.authorization_url
// Or use data.data.access_code with Paystack Popup

The currency defaults to NGN for Nigerian Paystack accounts, but it is good practice to pass it explicitly. The amount is in kobo, so 500000 means 5,000 NGN. Always double-check your kobo conversion before going live. A common launch-day bug is charging customers 100x the intended amount because someone passed naira instead of kobo.

For the full Paystack onboarding process including document requirements and common rejection reasons, see Paystack onboarding and compliance requirements in Nigeria.

Nigeria has the widest selection of payment channels on Paystack. Each channel serves a different customer segment and has different conversion characteristics. Here is what is available and when to use each one.

Cards (Visa, Mastercard, Verve)

Card payments are the default channel and work for most customers with bank-issued debit or credit cards. Verve cards are Nigeria-specific and widely issued by Nigerian banks. Card payments require the customer to enter their card number, expiry, and CVV, then complete OTP or PIN verification depending on the card type. Cards work well for recurring payments because Paystack can store the authorization for future charges.

Bank Transfer (Dedicated Virtual Accounts)

Paystack generates a unique bank account number for each transaction. The customer transfers the exact amount to that account from their banking app, and the payment is confirmed automatically. This channel has high conversion rates because many Nigerian customers are more comfortable with bank transfers than entering card details online. No card needed, no OTP, no PIN entry.

USSD

The customer dials a bank-specific USSD code (like *737# for GTBank), enters the payment amount and a reference code, then authorizes with their PIN. USSD works on any phone, feature phones included, and does not require internet access. This is essential for reaching customers outside of urban areas or those without smartphones.

Mobile Money

Paystack supports mobile money payments in Nigeria through select providers. This is a growing channel as mobile money adoption increases in the country.

QR Code

Paystack can generate QR codes that customers scan with their banking app to complete payment. This works well for in-person transactions, POS scenarios, and situations where you want to display a payment option on screen.

Apple Pay

Nigerian merchants can accept Apple Pay through Paystack after completing domain verification. This channel serves iPhone users who have added their cards to Apple Wallet.

You can restrict which channels appear at checkout by passing the channels parameter when initializing a transaction. For a deep dive into each channel with code examples, read payment methods available on Paystack in Nigeria.

Every amount in the Paystack API is in the smallest currency unit. For Nigeria, that means kobo. One naira equals 100 kobo. This is the single most important thing to get right because getting it wrong means charging your customers the wrong amount.

// Converting naira to kobo for the API
function nairaToKobo(naira) {
  return Math.round(naira * 100);
}

// Converting kobo back to naira for display
function koboToNaira(kobo) {
  return kobo / 100;
}

// Examples
nairaToKobo(5000);    // 500000 kobo = 5,000 NGN
nairaToKobo(99.99);   // 9999 kobo = 99.99 NGN
nairaToKobo(0.50);    // 50 kobo = 0.50 NGN

Common mistakes with NGN amounts:

• Passing naira instead of kobo. If your product costs 5,000 NGN and you pass amount: 5000, Paystack charges 50 NGN. If you pass amount: 500000, Paystack charges 5,000 NGN. Always multiply by 100.
• Floating point errors. JavaScript floating point arithmetic can produce unexpected results. Use Math.round() when converting to kobo to avoid amounts like 999.9999999 kobo.
• Minimum transaction amounts. Paystack has a minimum transaction amount in Nigeria. Check the current minimum in your dashboard or documentation. Attempting to charge below the minimum returns an error.

When you verify a transaction, the response includes the amount in kobo. Always verify that the amount matches what you expected before granting value to the customer. A mismatch between the amount you initialized and the amount that was actually paid is a sign of tampering or a bug in your code.

// Verify a transaction and check the amount
const verifyResponse = await fetch(
  'https://api.paystack.co/transaction/verify/' + reference,
  {
    headers: {
      Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
    },
  }
);

const verifyData = await verifyResponse.json();

if (verifyData.data.status === 'success') {
  var expectedAmountKobo = 500000; // 5,000 NGN
  if (verifyData.data.amount !== expectedAmountKobo) {
    // Amount mismatch. Do not grant value.
    console.error('Amount mismatch: expected ' + expectedAmountKobo + ', got ' + verifyData.data.amount);
    return;
  }
  // Amount matches. Grant value to the customer.
}

Webhooks are how Paystack tells your server that something happened: a payment succeeded, a transfer completed, a subscription renewed. In Nigeria, webhooks are especially important because some payment channels (bank transfers, USSD) are asynchronous. The customer might complete the payment minutes after the checkout page has closed.

Set up your webhook URL in the Paystack dashboard under Settings. Paystack sends a POST request to this URL for every event on your account. The most critical event for payment confirmation is charge.success.

// Express.js webhook handler
var crypto = require('crypto');

app.post('/webhooks/paystack', function(req, res) {
  // Immediately return 200 to acknowledge receipt
  res.sendStatus(200);

  // Verify the webhook signature
  var hash = crypto
    .createHmac('sha512', process.env.PAYSTACK_SECRET_KEY)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (hash !== req.headers['x-paystack-signature']) {
    console.error('Invalid webhook signature');
    return;
  }

  var event = req.body;

  if (event.event === 'charge.success') {
    var reference = event.data.reference;
    var amount = event.data.amount;
    var currency = event.data.currency;
    var channel = event.data.channel; // 'card', 'bank', 'ussd', etc.

    // Process the successful payment
    // Check idempotency: have you already processed this reference?
    // Verify amount matches your expected amount
    // Grant value to the customer
  }
});

Key rules for webhook handling in Nigeria:

• Return 200 immediately. Do your processing after sending the response. Paystack retries webhooks that do not get a 200 response, and if your processing is slow, you might get duplicate deliveries.
• Verify the signature. The x-paystack-signature header contains an HMAC SHA512 hash of the request body using your secret key. Always verify this before processing.
• Handle idempotency. You might receive the same webhook more than once. Use the transaction reference as an idempotency key. If you have already processed a reference, skip it.
• Do not rely solely on callbacks. The redirect callback (customer returning to your site) can fail if the customer closes their browser. The webhook is the reliable signal. Build your payment confirmation logic around webhooks, and treat the redirect as a UI convenience.

After a customer pays, the money does not land in your bank account instantly. Paystack holds the funds and settles them to your registered bank account on a schedule. Understanding this schedule is critical for cash flow planning and for setting customer expectations.

Settlement in Nigeria follows these general patterns:

• Card transactions typically settle within 24 hours on business days. Weekends and public holidays may extend the timeline.
• Bank transfer transactions may have different settlement timelines depending on your account configuration and the volume of transactions.
• Settlement is automatic. You do not need to trigger it manually. Paystack batches your transactions and sends the net amount (total payments minus fees and refunds) to your bank account.

You can track settlements through the Paystack dashboard under Settlements, or via the API:

// Fetch recent settlements
var response = await fetch('https://api.paystack.co/settlement', {
  headers: {
    Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
  },
});

var data = await response.json();
// data.data contains an array of settlement objects
// Each shows the total amount, the settled amount, and the settlement date

Important things to know about Nigerian settlements:

• Fees are deducted before settlement. The amount that hits your bank account is the transaction amount minus Paystack's processing fee. Your dashboard shows both the gross and net amounts.
• Failed settlements are retried. If your bank account cannot receive funds (wrong account, bank downtime), Paystack retries on the next settlement cycle. Contact support if settlements consistently fail.
• Refunds reduce your settlement. If you refund a transaction, the refund amount is deducted from your next settlement batch.

For a detailed breakdown of settlement timelines, fee calculations, and how to reconcile settlements against your database, see settlement and payouts on Paystack in Nigeria.

Paystack's test mode lets you simulate every payment channel without moving real money. Use your test secret key (starts with sk_test_) and test public key (starts with pk_test_) during development.

Test cards

Paystack provides test card numbers that simulate successful payments, failed payments, and various error scenarios. The most common test card for successful payments uses card number 4084 0840 8408 4081, expiry 12/30, CVV 408, and OTP 123456. Check the Paystack documentation for the full list of test cards and what each one simulates.

Test bank transfers

In test mode, bank transfer transactions auto-complete after a short delay. You do not need to actually send money. The webhook fires with a simulated successful transfer.

Test USSD

USSD payments in test mode can be simulated through the Paystack test dashboard. The actual USSD flow (dialing a code on a phone) cannot be fully simulated in test mode, but the API responses and webhook payloads mirror production behavior.

A common testing checklist before going live in Nigeria:

1. Initialize a transaction and complete payment with a test card
2. Verify the transaction server-side and confirm amount matching
3. Receive and process the charge.success webhook
4. Test the bank transfer flow and confirm webhook delivery
5. Test a failed payment and confirm your error handling works
6. Test a refund and confirm the refund webhook
7. If using recurring billing, test authorization reuse
8. If using splits, test subaccount creation and split settlement

Do not skip testing. The gap between test mode and production in Nigeria is small, but the consequences of bugs in production (charging wrong amounts, not granting value, losing webhooks) are real money problems.

After working with dozens of Nigerian Paystack integrations, these are the mistakes that come up repeatedly. Avoid them and your launch will go smoother.

• Ignoring Verve cards. Verve is the most widely issued card brand in Nigeria, but it has different behavior from Visa and Mastercard. Verve cards use PIN authentication instead of OTP in many cases. If your checkout flow only handles OTP, Verve card holders will get stuck. Test with a Verve test card before launch.
• Not offering bank transfer. If you only offer card payments, you are excluding a large segment of Nigerian customers who prefer or can only use bank transfers. At minimum, offer both cards and bank transfers. For many products, bank transfer will be your highest-converting channel.
• Hardcoding fee calculations. Paystack's fee structure can change. Do not hardcode fee percentages or caps in your application. Instead, let Paystack calculate fees and read the fee from the transaction verification response.
• Forgetting about the fee cap. Paystack caps fees on Nigerian transactions at a certain amount. For transactions above a certain threshold, the fee is flat rather than percentage-based. This affects your unit economics on high-value transactions.
• Not handling network timeouts. Nigerian internet can be unreliable. Your integration needs to handle cases where the API call to Paystack times out, where the customer's bank OTP delivery is delayed, and where the webhook takes longer than expected to arrive. Build retry logic and do not assume instant responses.
• Trusting the redirect over the webhook. The callback redirect (customer returning to your site) should show a "checking payment" state and poll or wait for webhook confirmation. Do not grant value based solely on the customer landing on your callback URL.

For checkout design patterns that maximize conversion in the Nigerian market, see building a local checkout experience for Nigeria.

Paystack in Nigeria gives you the most complete set of payment tools available to any African developer. The depth of channels, the speed of settlement, and the maturity of the documentation make it the default choice for Nigerian products.

If you are building a product that accepts payments in Nigeria and want to learn how to architect the full payment flow from checkout to reconciliation, the McTaba bootcamp covers payment integration as a core module. Every graduate ships code that moves real naira.

Create a free McTaba account