SDK Quickstart

The shortest path to a working payment is four steps. You create a key in the Dashboard, you put it in an environment variable, you install one package, and you make one call. What comes back is a URL. Open it and you are looking at a real Wajub payment page.

Everything else in this section builds on that call.

1. Get a key

Keys live in the Dashboard, under Settings, then Developer, then API keys. Every account has two sets from the first day, and the prefix is what tells them apart.

Server SDKs take the secret key.

2. Store it

Python, Ruby, Go, Java and C# read WAJUB_API_KEY from the environment on their own, and every server SDK falls back to WAJUB_WEBHOOK_SECRET, so a .env file is usually the whole configuration step.

WAJUB_API_KEY=sk_test.xxxxxxxxxxxxxxxx…
WAJUB_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxx

Node.js and PHP are the exceptions for the key: they do not read WAJUB_API_KEY, so you pass it explicitly, as the examples below do.

3. Install

One package per language, from the registry you already use.

4. Create a payment

This is the call. An amount, a currency, a way to reach the customer, and a URL to come back to.

curl https://api.wajub.com/payments \
  -H "Authorization: $WAJUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "email": "amina@example.com",
    "description": "Order 4172",
    "reference": "order-4172",
    "callback": "https://shop.example.com/complete"
  }'

Only amount and currency are truly required. Beyond those you need one way to identify the payer, which is email, phone or customer_id, any one of the three. callback is what makes the redirect flow work, and reference is your own order number coming back on every webhook.

5. Read what came back

The SDKs flatten the API envelope, so you get one object with the transaction fields and the two authorization fields together.

Open authorization_url in a browser now. That page is the checkout, already carrying your account branding, and the sandbox accepts the test cards and numbers.

6. Confirm it server side

The redirect brings the customer back to your callback URL with a status parameter. Use it to pick the page you show them, never to release the goods.

curl https://api.wajub.com/payments/trx_test_8kQ2mW9vB4nL6hR1cY3d \
  -H "Authorization: $WAJUB_API_KEY"

The browser is not a reliable reporter. A customer can close the tab on a successful payment, and a Mobile Money confirmation can land minutes after the redirect. The webhook is the event that is guaranteed to arrive, so fulfilment belongs there and this call is the fallback.

What the SDK is doing for you

The same behaviour in all seven, and it is the reason to use a package rather than a raw HTTP call.

When the call fails

Every SDK raises a typed error rather than returning a status. The class is the decision: retry, fix the request, or tell the payer something.

Three spellings differ from that list. PHP suffixes its subclasses with Exception, so the row above reads InvalidRequestException, while the base stays WajubError. Java suffixes every class with Exception, the base included: WajubException, InvalidRequestException, ApiConnectionException, all unchecked. Go capitalizes the initialism, so its connection class is APIConnectionError.

Whatever the class, four fields are always there: the message, a code, the HTTP status, and an errors map keyed by field name. That last one is what you show back on a form.

import { WajubError, WajubInvalidRequestError, WajubRateLimitError } from '@wajub/node';

try {
  await wajub.payments.create({ amount, currency: 'XAF', email });
} catch (error) {
  if (error instanceof WajubInvalidRequestError) {
    return res.status(422).json({ fields: error.errors });
  }
  if (error instanceof WajubRateLimitError) {
    return res.status(503).set('Retry-After', String(error.retryAfter ?? 5)).end();
  }
  if (error instanceof WajubError) {
    logger.error({ code: error.code, status: error.httpStatus });
  }
  throw error;
}

Where to go next