Wave Business API: integrating Wave payments into your website in 2026

Why Wave took over Dakar

In 2026, Wave processes more mobile payments in Senegal than Orange Money in several SME segments. Fees at 1% (versus 5% elsewhere), ultra-simple UX, mass adoption — if your e-commerce site does not accept Wave, you are leaving 30-40% of your revenue on the table.

Good news: Wave launched a proper Business API in 2024, and it is clean.

What Wave Business API enables

• Hosted checkout: redirect to a secure Wave page
• Payouts: send money to suppliers or referral partners
• Webhooks: real-time notifications of successful payments
• Multi-country: Senegal, Ivory Coast, Mali, Burkina Faso, Uganda

Getting started: 4 steps

1. Get a Wave Business account

Sign up on business.wave.com, verify your identity with national ID + business registration (NINEA). Expect 48-72 hours of validation. No NINEA = no API, so prepare it first.

2. Retrieve your API keys

In the Wave Business dashboard → *Developers*:

• API Key (keep it in your .env)
• Webhook Secret (to verify signatures)
• Business ID

Never commit those keys to GitHub. I have seen it happen three times this year.

3. Create a checkout session

The main endpoint is POST https://api.wave.com/v1/checkout/sessions. You send:

• amount (in FCFA, integer, no decimal)
• currency: "XOF"
• success_url and error_url
• client_reference (your internal order ID)

Wave returns a wave_launch_url. You redirect the user there. They pay. Wave redirects to your success_url.

4. Handle the webhook

This is where 80% of integrations fail. Wave sends a POST to your endpoint with an X-Wave-Signature header. You must:

• Verify the HMAC-SHA256 signature with your webhook secret
• Return 200 within 10 seconds
• Make the endpoint idempotent — Wave can send the same event 3 times

Pitfalls nobody documents

The amount problem

Wave expects integer FCFA values. Sending 15,000.50 or "15000" (string) = HTTP 400. Always parseInt.

The lying sandbox

Wave's sandbox accepts webhooks over HTTP for testing. In production, HTTPS is mandatory (see my SSL article). Many teams discover this on launch day.

Mobile timeouts

Wave users complete the payment inside the Wave app, not on your site. If your success_url takes 8 seconds to load on Tigo 3G, the customer will assume it crashed. Pre-load a lightweight confirmation page.

Accounting reconciliation

Wave does not provide automatic VAT. You must reconcile payments manually with your accountant via the monthly CSV export. Automate this in your admin panel.

Recommended stack for a clean setup

• Next.js 14 + App Router: API route /api/wave/webhook
• Prisma + PostgreSQL: Payment table with unique waveSessionId
• Zod: validate every webhook payload
• Sentry: instant alert if a webhook fails
• Retry queue: if your DB goes down during a webhook

We integrate Wave for you in 5 days

At Kolonell, we have plugged Wave Business API into more than 15 Dakar-based e-commerce sites, including fashion stores and a food-delivery restaurant doing 800 orders/month via Wave. Clean integration, idempotent webhooks, automated tests, reconciliation dashboard.

Request a free quote or message me on WhatsApp +221 77 596 93 33. You will have a working Wave checkout next week.