FAQ — Technical

API

Is the API REST?

Yes. All endpoints accept JSON input, return JSON, and use standard HTTP verbs and codes.

What is the base API URL?

https://api.wajub.com

A single URL for sandbox and production. The API key determines the environment.

How does authentication work?

Three key types, all in the Authorization header, no Bearer prefix:

• Public key (pk./pk_test.) — for standard operations (initializing a payment, verifying a transaction).
• Secret key (sk./sk_test.) — for sensitive operations (refunding, creating transfers).
• Restricted key (rk./rk_test.) — scoped to only the permissions it was granted.

What are the recommended timeouts?

• Connection: 10 seconds.
• Read: 30 seconds.
• Total request: 60 seconds.

Transfer and account verification operations may take longer than payment initializations.

Are there rate limits?

Yes, per minute, plan-based (not per-second, and there's no separate sandbox multiplier): 120 requests/minute by default, up to 360–720/minute on higher plans. Beyond that, you'll receive a 429 Too Many Requests. See Rate limits for exact tiers.

async function apiWithRetry(fn, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
  try {
    return await fn();
  } catch (err) {
    if (err.status === 429 && attempt < maxRetries - 1) {
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
      continue;
    }
    throw err;
  }
}
}

Webhooks

How do I verify that a webhook really comes from Wajub?

Each webhook includes an X-Wajub-Signature: v1={hmac} header and an X-Wajub-Timestamp header. Verify with HMAC-SHA256 over "{timestamp}.{payload}" using your webhook secret — see Signature Verification for the exact mechanics and code samples.

What is the webhook delivery delay?

Webhooks are sent in real time, usually within a second of the event. On failure, Wajub retries with exponential backoff for 72 hours.

Does my endpoint need to respond quickly?

Yes. You must respond with a 2xx status in under 5 seconds. Beyond that, Wajub considers the delivery as failed and will retry. Handle the event asynchronously (queue, worker) after acknowledging receipt.

What events are available?

See the full reference in Webhooks > Events. The most common: payment.succeeded, payment.failed, transfer.succeeded, transfer.failed, refund.succeeded.

Environments and SDKs

Can I use the same key for sandbox and production?

No. pk_test.… and pk.… keys are distinct. A test key triggers sandbox transactions, a live key triggers real charges.

Which SDKs are available?

Wajub does not currently publish an official backend SDK for Node.js, Python, PHP, or Go — see SDKs & Libraries for what's actually available (a checkout-embed widget SDK, and the @wajub/cli command-line tool).

Can I use the API directly?

Yes — the API is standard REST/JSON. Send HTTP requests with curl, fetch, requests, HttpClient, or any other HTTP library.

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

{
"status": "Created",
"code": 201,
"transaction": { "id": "trx_01JXXXXXXXXXXXXX", "status": "pending" },
"authorization_url": "https://pay.wajub.com/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Security

Do I need to be PCI DSS compliant?

No. Since you redirect the customer to the Wajub-hosted payment page, you never handle card data or sensitive Mobile Money numbers. Wajub handles PCI compliance for you.

How do I secure my API keys?

• Store them in environment variables (.env, never committed).
• Use secret managers in production (Vault, AWS Secrets Manager, GitHub Secrets).
• Perform regular rotation of your keys via the Dashboard.
• The secret key (sk./sk_test.) must never leave your backend.

What encryption method do you use?

All communications go through TLS 1.3. Sensitive data at rest is encrypted with AES-256. Webhooks are signed with HMAC-SHA256.