Quickstart

This guide takes you from an empty account to a verified payment with a working webhook. You'll need a Wajub account (free) and a few minutes.

1. Create your account and get your keys

Create an account on the Dashboard. Once logged in, open Developers → API Keys. Each account has two sets of keys:

2. Install the SDK for your language

npm install @wajub/node

For a detailed SDK reference — configuration, all resources, webhooks — see the SDK guides.

3. Initialize a payment

Server-side, create a payment. Wajub returns an id and a hosted authorization_url to redirect your customer to.

curl https://api.wajub.com/payments \
-H "Authorization: pk_test.8f2b91c4d7e6a0f3" \
-H "Content-Type: application/json" \
-d '{
  "amount": 5000,
  "currency": "XAF",
  "email": "client@example.com",
  "callback": "https://example.com/return"
}'

Official server SDKs are available for Node.js, Python, PHP, Go, Ruby, Java, and C# — see Server SDKs.

4. Test with sandbox Mobile Money numbers

On the payment page (in test mode), use a test number to simulate each outcome:

The outcome is controlled by the number's last 6 digits, not the country — the same suffixes work for every operator:

Example numbers by country/operator:

Use any PIN when prompted on the sandbox payment page.

5. Verify the payment server-side

Never rely solely on the browser return: verify the status server-side before fulfilling the order.

curl https://api.wajub.com/payments/trx_01JXXXXXXXXXXXXX \
-H "Authorization: pk_test.8f2b91c4d7e6a0f3"

{
"status": "OK",
"code": 200,
"transaction": {
  "id": "trx_01JXXXXXXXXXXXXX",
  "status": "succeeded",
  "amount": 5000,
  "currency": "XAF",
  "channel": "cm.mtn"
}
}

6. Set up a webhook endpoint

The browser return URL is not reliable — the customer can close the tab. Webhooks are the source of truth for payment status. Set one up now, before going further.

First, initialize the SDK with your private key and webhook secret:

import { Wajub } from '@wajub/node';

export const wajub = new Wajub({
privateKey: process.env.WAJUB_SECRET_KEY!,
// webhookSecret is used by webhooks.constructEvent() to verify signatures
});

app.post('/webhooks/wajub', express.raw({ type: '*/*' }), async (req, res) => {
// Step 1: verify the signature (required in production)
// webhookSecret is configured at construction: new Wajub({ webhookSecret: process.env.WAJUB_WEBHOOK_SECRET })
const event = wajub.webhooks.constructEvent(
  req.body,
  req.headers['x-wajub-signature'],
  req.headers['x-wajub-timestamp'],
);

// Step 2: acknowledge immediately (before processing)
res.sendStatus(200);

// Step 3: act on the event
if (event.event === 'payment.succeeded') {
await fulfillOrder(event.data.id); // your logic here
}
});

Register your endpoint URL in Konsole → Webhooks → Endpoints (or Developers → Webhooks in the Dashboard):

1. Click Add Endpoint.
2. Enter your public URL (e.g. https://yourapp.com/webhooks/wajub).
3. Select the events to receive (start with payment.* for all payment events).
4. Save and copy the Signing Secret (whsec_…) — add it to your environment as WAJUB_WEBHOOK_SECRET.

To test locally without deploying, use the CLI tunnel:

npm install -g @wajub/cli
wajub listen --forward-to localhost:3000/webhooks/wajub

This creates a secure tunnel and forwards all sandbox events to your local server. See the CLI listen command for all options.

What's next?