Developer Guide to Commerce APIs in Africa

The API-First Commerce Landscape in Africa

Africa's commerce infrastructure is fundamentally different from the rest of the world. In North America or Europe, a developer can spin up a Stripe account, connect it to a Next.js frontend, and start accepting payments within hours. The payment stack is standardized. Credit cards dominate. Address systems are structured and reliable. Shipping carriers have well-documented APIs. Tax rules are complex but well-defined.

Africa presents a different set of engineering challenges — and opportunities. Mobile money processes more transaction volume than cards in most Sub-Saharan markets. MTN Mobile Money, Orange Money, M-Pesa, and Airtel Money each have different integration patterns, settlement timelines, and failure modes. Address systems are informal or non-existent in many cities — "turn left after the blue gate" is a real delivery instruction. Tax regulations vary dramatically across 54 countries, and many are still being defined. Currency controls, cross-border transfer restrictions, and settlement complexities add layers that don't exist in Western markets.

For developers building commerce applications targeting Africa, this means you can't simply plug in Stripe and call it done. You need infrastructure that abstracts these complexities — payment method fragmentation, multi-currency settlement, fulfillment logistics, tax compliance — while exposing clean, well-documented APIs that your application can integrate with. This is the domain of API-first commerce platforms built specifically for Africa.

The market data supports the opportunity. Africa's digital payments market grew 39% year-over-year in the last reporting period. E-commerce penetration is still below 5% in most markets, meaning the growth runway is enormous. Developers who build on the right infrastructure now are positioning their applications for a market that's doubling every 2-3 years.

The Technical Blueprint

1. Define Your Integration Architecture

Before writing a single line of integration code, define how commerce will fit into your application architecture. There are three primary patterns. Embedded commerce: your application owns the entire user experience and calls commerce APIs server-side for payments, order creation, and fulfillment. This gives you maximum control but requires the most engineering effort. Hosted checkout: your application redirects users to a hosted payment page and receives webhooks when payment completes. Lower development effort, but you hand off the UX. Hybrid: you build a custom frontend but use hosted components for sensitive operations like payment collection (reducing PCI scope). Choose based on your team's capacity and the UX requirements of your product.

2. Implement Payment Processing

Payment processing in Africa requires handling multiple payment methods with fundamentally different flows. Card payments (Visa, Mastercard) are synchronous — you get an immediate success or failure. Mobile money payments are asynchronous — you initiate a request, the customer gets a USSD prompt on their phone, they enter their PIN, and you receive a callback minutes later (or never, if they don't complete). Your code must handle both patterns gracefully. Implement idempotency keys for all payment creation requests. Build retry logic with exponential backoff for webhook delivery failures. And always, always store the raw provider response — you'll need it for debugging reconciliation issues.

3. Design Your Webhook Architecture

Webhooks are the backbone of asynchronous commerce. You'll receive events for payment completion, payment failure, refund processing, order status changes, fulfillment updates, and more. Design your webhook handler as an idempotent processor: receive the event, validate the signature (critical for security — never process unsigned webhooks), store the raw payload, then process it asynchronously via a job queue. Return a 200 OK immediately — don't do heavy processing in the webhook handler itself or you'll hit timeout issues. Implement a dead letter queue for failed processing attempts and build a manual retry mechanism for production debugging.

4. Handle Multi-Currency and Exchange Rates

If your application serves customers across multiple African markets, you'll deal with XOF (West African CFA), XAF (Central African CFA), NGN (Nigerian Naira), KES (Kenyan Shilling), ZAR (South African Rand), GHS (Ghanaian Cedi), and more. Display prices in local currencies — showing USD to a customer paying with MTN Mobile Money in Cameroon creates friction. Your commerce API should handle the currency conversion and settlement, but your application needs to store and display the correct currency for each market. Build currency handling as a first-class concern in your data model, not an afterthought.

5. Implement API Key Management and Security

Commerce APIs handle financial data, so security is non-negotiable. Use separate API keys for test and production environments — never cross them. Store keys in environment variables or a secrets manager (never in your codebase or client-side code). Implement IP allowlisting if your API provider supports it. For webhook signature verification, use HMAC-SHA256 with a timing-safe comparison to prevent timing attacks. Audit log every API call your application makes to the commerce provider — when something goes wrong at 3 AM, these logs are the difference between a 20-minute fix and a 4-hour investigation.

6. Build for Fulfillment Complexity

If your application involves physical product delivery, brace yourself — fulfillment in Africa is a different beast. Many addresses can't be geocoded accurately. Delivery zones and pricing vary by neighborhood, not just city. Last-mile delivery partners have wildly different API maturity levels. Your integration should abstract the fulfillment layer so you can swap providers without rewriting your order flow. Build order state machines that handle the full lifecycle: pending → confirmed → processing → shipped → in-transit → delivered (or returned). Track each state transition with timestamps for operational visibility.

7. Implement Proper Error Handling and Monitoring

Commerce API failures have direct revenue impact — a payment that fails silently means lost revenue. Categorize errors into retryable (network timeouts, 5xx responses) and non-retryable (invalid parameters, insufficient funds, expired cards). Implement circuit breakers for payment providers that experience prolonged outages. Monitor key metrics: payment success rate by method, average API response time, webhook delivery success rate, and reconciliation discrepancy rate. Set up alerting thresholds — if your mobile money success rate drops below 85%, something is wrong with the provider and you need to know immediately, not three days later during a manual review.

8. Plan for Testing and Sandbox Environments

Test every payment flow in sandbox before going live. Test the happy path, but more importantly, test failure modes: what happens when a mobile money payment times out? What if the webhook is delivered twice? What if the customer's session expires between payment initiation and callback? Build automated integration tests that run against the sandbox environment in your CI/CD pipeline. Use test mode API keys to simulate specific scenarios (successful payment, declined card, network timeout). Document your test scenarios — the next developer on your team will thank you.

Building with Porsa's APIs

Porsa's API-first architecture is built specifically for the complexities of African commerce. Here's how each API surface maps to the technical requirements outlined above.

Whether you're building a marketplace, a cross-border commerce platform, or integrating payments into an existing SaaS product, Porsa's API-first infrastructure gives you the building blocks to ship faster while handling Africa's commerce complexities at the infrastructure layer.