How to Build a Mobile App With Online Payments: Payment Methods, Architecture and Nigerian Realities

What online payments in an app actually involve

Online payments in a mobile app involve five components working together, not one "payment button":

• A payment gateway licensed to process payments in Nigeria, which handles cards, bank accounts and settlement to your business account.
• A checkout experience in the app: the gateway's native SDK, a hosted payment page in a web view, or a custom form for transfer details.
• A backend that creates payment intents with the right amount and reference, verifies results, and updates orders.
• Webhooks, which are messages the gateway sends to your backend when a payment succeeds or fails, independent of what the app reports.
• Reconciliation and reporting so finance can match orders, gateway settlements and bank credits.

The phone is the least trustworthy part of this system. Any amount, status or reference the app sends can be tampered with, so the backend must be the source of truth for what was paid.

Which payment methods should a Nigerian app support?

For a Nigerian consumer app, the main payment methods are cards, bank transfer, USSD and mobile wallets, and the right mix depends on your customers' habits and your average order value. The table summarises the trade-offs.

A sensible default for most apps: card plus bank transfer at launch, USSD if your customers include low-data users, wallets once volume justifies the extra integration, and pay on delivery only with clear limits.

Choosing a gateway and an integration approach

Nigerian gateways are broadly similar in what they offer; the differences that matter are the methods they support for in-app use, the quality of their SDKs and webhooks, settlement timing, and how they handle disputes. Evaluate rather than assume:

• Does the gateway offer a native SDK for your framework (Flutter, React Native, Swift, Kotlin), or only a hosted page?
• Does it support dynamic virtual accounts for bank transfer with reliable webhooks?
• What are the settlement schedules and fees for each method, and how are they displayed to you? (Fees change; treat any published number as something to verify.)
• Can you issue partial and full refunds through the API, and how long do they take?
• Does it provide a test environment with realistic failure cases?
• What identity and business documents does it require (CAC registration, bank details, director identification), and how long does merchant approval take?

There are three integration approaches:

• Native SDK. Best user experience and card handling stays inside the gateway's components. Recommended for consumer apps.
• Hosted checkout in a web view. Fastest to build; adequate for low-volume apps; can feel clunky on slow networks.
• Custom flow using the gateway's API for transfer details and status polling. Useful for bank transfer and USSD screens where you want to control the layout and messaging.

Most production apps combine a native SDK for cards with a custom screen for transfer instructions and a webhook-driven status page.

Payment architecture: how money should move through the app

The difference between a reliable payment system and a fragile one is whether the backend controls every step. A robust flow works like this:

1. The customer confirms an order in the app.
2. The app asks the backend to create the order and a payment record with a unique reference.
3. The backend calculates the amount (never trust the app's number), stores the order as "pending payment", and initialises the payment with the gateway using that reference.
4. The app opens the gateway checkout with the reference the backend returned.
5. The customer pays.
6. The gateway sends a webhook to the backend. The backend checks the webhook signature, matches the reference, confirms the amount and currency, and moves the order to "paid" exactly once.
7. Separately, the app asks the backend for the order status (or the backend pushes a notification). The app never decides the order is paid on its own.
8. Background jobs handle fulfilment, receipts and reconciliation.

Model the order and payment as explicit states, because every support conversation will be about which state something is in.

Two rules that prevent most disasters: webhook handling must be idempotent (receiving the same webhook twice must not mark two orders paid or credit a wallet twice), and every state change must be logged with who or what triggered it.

Step-by-step: building the payment flow

1. Register with the gateway early. Merchant approval needs CAC documents, a settlement bank account and director identification, and can take days. Start before development so test and live keys are ready.
2. Design the order and payment data model with the states above, unique references, amounts in kobo (integers, never floating-point naira), currency, method, gateway reference and timestamps.
3. Build the backend endpoints: create order, initialise payment, get order status, request refund, and a webhook receiver that verifies the gateway's signature.
4. Integrate the checkout in the app using the gateway SDK for cards and a custom screen for transfer or USSD instructions, showing the amount, the account number, the expiry time, and a "I have paid" refresh that polls the backend.
5. Handle every outcome in the app: success, decline, cancelled, timed out, network lost mid-payment. Each needs a clear message and a next step, not a spinner.
6. Implement receipts by email, in-app history and, where customers expect it, a WhatsApp message with the reference.
7. Build the admin views: payment log, reconciliation, refunds with approval, and a "find by gateway reference" search for support.
8. Test with the gateway's sandbox for each method and failure case, then run a small live pilot with real cards and transfers from different banks before public launch.
9. Monitor. Alert on webhook failures, on orders stuck in pending for too long, and on mismatches between orders marked paid and gateway settlements.

App store rules: when you cannot use your own gateway

Both Apple and Google require digital goods and services consumed within the app (premium features, subscriptions to content, virtual currency, paid game levels) to be sold through their in-app purchase systems, which charge a commission. Physical goods and real-world services (food, groceries, gas, transport, hotel stays, school fees, tickets to physical events) may use your own gateway. Practical consequences for Nigerian app owners:

• Classify every product before building the checkout. A meal-kit subscription is physical; a recipe-video subscription is digital.
• Where a product is digital, budget for the store commission (historically 15–30% depending on programme and revenue; verify current terms) and for the extra work of receipt validation.
• Reviewers test payment flows. An app that sells digital goods through Paystack on iOS will be rejected under Guideline 3.1.1. Policies and exceptions change, and some regions have alternative rules, so confirm the current text for both stores before launch.

Security, fraud and compliance

Using a licensed gateway keeps card data out of your systems, which is the single most important security decision. Beyond that:

• Never store card numbers. Use the gateway's tokenisation for saved cards and recurring billing.
• Keep secret keys on the server. The app should hold only public keys.
• Verify webhooks using the gateway's signature and reject anything that fails.
• Enforce amounts server-side and compare the amount in the webhook to the order.
• Rate-limit and monitor payment initialisation to detect card-testing attacks.
• Chargebacks and disputes. Keep delivery proof, timestamps and communication logs; the admin dashboard should attach these to each order.
• Data protection. Payment references, names, phone numbers and addresses fall under the Nigeria Data Protection Act 2023. State the purpose in your privacy policy, restrict staff access and follow the Nigeria Data Protection Commission's current guidance.
• Wallets and stored value. If your app holds customer balances (a top-up wallet, for example), you may be entering regulated territory under Central Bank of Nigeria rules. Take advice before designing a wallet; many apps avoid the issue by using a gateway's regulated wallet products instead.

What changes for Nigerian businesses

Payment design in Nigeria is shaped by a few realities that overseas tutorials ignore.

• Transfer is often the preferred method. Many customers trust a bank transfer more than entering a card in an app. Dynamic virtual accounts with instant webhook confirmation make transfer a first-class method rather than a manual "send proof on WhatsApp" process.
• Cards fail more than you expect. Daily limits, OTP delivery delays and international-spend blocks all cause declines. Offer transfer as an immediate fallback on any card failure.
• Networks drop mid-payment. A customer can be debited while the app loses connection. Because the webhook reaches the backend regardless, the order still becomes paid; the app just needs to refresh status and reassure the customer. Design the "checking your payment" screen carefully.
• Settlement timing affects cash flow. Gateway settlements arrive on their own schedule per method. Finance needs the dashboard to show "paid but not yet settled" clearly.
• Naira volatility affects dollar costs. If any part of the stack (hosting, SMS, an international service) is billed in US dollars, payments income in naira must cover a moving cost. Budget conservatively.
• Receipts live on WhatsApp. Customers screenshot and forward receipts. Include the reference, amount and business name on every receipt and make them easy to share.

Example (hypothetical): a Port Harcourt cooking-gas delivery app

Example (hypothetical): a gas retailer in Port Harcourt builds an app for cylinder refills and delivery. Orders average a few thousand naira, customers span office workers with cards and households that only use bank transfer, and riders collect cylinders from customers' homes. The team designs the payment flow as follows:

• Methods at launch: card (gateway SDK) and dynamic virtual account transfer, with a 30-minute transfer window and a countdown in the app. Pay on delivery is allowed only for repeat customers with two completed orders.
• Backend states as described above; amounts stored in kobo; webhook handler idempotent and signature-checked.
• On card decline, the app immediately offers the transfer option with the same reference, so the order is not recreated.
• Receipts sent as in-app history plus a WhatsApp template message with the reference (via the WhatsApp Business Platform once volume justified it; email at first).
• The admin dashboard shows a daily reconciliation screen matching paid orders to gateway settlements and flags anything unmatched for finance.

The result the team cared about was operational: support conversations moved from "did you receive my transfer?" to "your order is paid and assigned to a rider", because the backend, not a staff member checking a bank app, decided when an order was paid.

How much does it cost to build an app with payments?

Payments are one module inside an app project, but they also touch the backend, admin dashboard and testing. The figures below are indicative 2026 ranges; actual quotes vary with scope, vendor and exchange rate. Compare two or three written quotations on identical scope.

For context, a medium-complexity app with accounts, payments, admin dashboard and notifications falls in the indicative ₦5,000,000–₦15,000,000 band overall. Recurring costs include gateway transaction fees (a percentage per transaction, with caps on some methods; verify current schedules), hosting, SMS or WhatsApp messages for receipts, and maintenance at roughly 15–25% of build cost per year.

Mistakes to avoid

• Letting the app declare a payment successful. Verify on the backend through webhooks and API verification, or you will ship orders that were never paid for.
• Trusting the amount from the app. Calculate totals server-side; a tampered request can set the price to ₦1.
• Non-idempotent webhook handling. Gateways retry webhooks; double credits and double orders follow.
• Using floating-point naira. Store amounts as integer kobo to avoid rounding errors in totals and refunds.
• No transfer fallback. A card decline with no alternative is an abandoned order.
• Ignoring reconciliation until month end. Build the matching view before launch and check it daily.
• Selling digital goods through your own gateway on iOS or Android. Expect rejection; classify products early.
• Building a customer wallet without regulatory advice. Stored value can bring licensing obligations.
• Skipping the live pilot. Sandbox success does not prove that real transfers from every major bank arrive with the right reference.

Conclusion

Building a mobile app with online payments is mostly a backend and operations design problem. Choose a licensed gateway and register early, offer card and bank transfer from day one with USSD and wallets as needed, make the backend the only authority on what has been paid, treat webhooks as the source of truth with idempotent handling, and give finance a reconciliation view before launch. Respect the app stores' rules on digital goods, keep card data out of your systems, and design for the realities of Nigerian networks and banking. Do that, and payments become the most reliable part of the app rather than the most argued-over. If you are planning an app that takes payments and want the checkout, backend, webhooks and reconciliation designed as one system, Linestech builds payment-enabled mobile apps for Nigerian businesses and can advise on gateway choice and store compliance before you commit.

Frequently asked questions

Can I accept payments in my app without a payment gateway?

Not safely. You could show your bank account number and ask customers to send proof, but confirmation is then manual, references are unreliable and fraud is easy. A licensed gateway gives you instant confirmation via webhooks, refunds through an API, and keeps card data out of your systems.

What documents does a gateway need before we can go live?

Typically your CAC registration, a settlement bank account in the business name, identification for a director, and sometimes proof of address and a description of what you sell. Requirements vary by gateway and business type, so check the provider's onboarding checklist early; approval can take days.

Do I need my own PCI DSS certification to take cards in an app?

If you use a gateway's SDK or hosted page so that card details never touch your servers, you rely on the gateway's compliance and your own obligations are limited. Building your own card entry form that sends card numbers to your backend would put you in scope for PCI DSS, which is expensive and unnecessary for almost every Nigerian business app.

Why do bank transfers sometimes fail to confirm in apps?

Usually because the app was waiting for the customer to tap "I have paid" instead of the backend listening for the gateway's webhook, or because the transfer arrived after the virtual account expired. Webhook-driven confirmation with a clear expiry timer and a backend match on amount solves most cases.

Can my app charge customers automatically every month?

Yes, for physical goods and services, using the gateway's card tokenisation and subscription features, with the customer's consent and clear cancellation. For digital subscriptions on iOS and Android the stores' subscription systems are generally required. Recurring debits in Nigeria fail more often than one-off payments, so plan retries and reminders.

How should refunds work in the app?

The customer requests a refund in the app or through support; finance approves it in the admin dashboard; the backend calls the gateway's refund API; the order moves to "refund pending" until the gateway confirms by webhook. Communicate expected timelines, because refunds to cards can take days to appear.

Sources and further reading

Figures, platform rules and regulations change. These are the primary references behind this article and the places to check before you act on it.

• Corporate Affairs Commission (CAC)
• Nigeria Data Protection Commission (NDPC)
• Central Bank of Nigeria (CBN)
• Paystack developer documentation
• WhatsApp Business Platform — Meta for Developers
• Flutter documentation
• Node.js documentation