JJuma Pay Documentation

Merchant URLs

Browser redirects and merchant webhooks are different things. Use redirect_url or return_url for the payer's browser, and use webhook_url for your backend to…

Merchant URLs

Browser redirects and merchant webhooks are different things. Use redirect_url or return_url for the payer's browser, and use webhook_url for your backend to update order status safely.

Redirect / Continue URL

This is the browser-based return path after payment. It should be visible to the customer and safe to open in a browser.

Use redirect_url or return_url in API create-payment requests.
callback_url is kept as a legacy browser-return alias when older integrations still send it.
Normal JJuma payment links continue to https://jjuma.com unless a merchant return URL is present on an API checkout.

JSON

{
  "amount": 50000,
  "currency": "UGX",
  "customer_name": "John Doe",
  "redirect_url": "https://yourwebsite.com/success",
  "return_url": "https://yourwebsite.com/success"
}

Webhook URL

This is a server-to-server notification. JJuma posts to your webhook after a verified payment succeeds or fails, so your system can update orders even if the customer closes the browser.

Use webhook_url for payment status updates.
Do not rely on the browser redirect alone to mark orders paid.
Verify the X-Jjuma-Signature and X-Jjuma-Timestamp headers before updating your database.
Return HTTP 200 when the webhook is accepted.

JSON

{
  "event": "payment.completed",
  "event_id": "evt_123",
  "delivery_id": "wh_456",
  "transaction_id": "TXN-A1B2C3D4E5F6",
  "reference": "REF-12345678",
  "tx_ref": "REF-12345678",
  "amount": 50000,
  "currency": "UGX",
  "status": "successful",
  "payment_status": "successful",
  "settlement_status": "waiting_settlement",
  "timestamp": "2026-07-14T10:00:00Z",
  "metadata": { "order_id": "ORD-001" }
}

Payment Status Verification

Your backend can also query JJuma directly to double-check a transaction after the webhook arrives.

GET /api/v1/payments/verify/{transaction_id}
Use your API key from the server, not from browser JavaScript.
Support the existing transaction_id and reference_code lookup flow for older merchants.

HTTP

GET https://api.jjuma.com/api/v1/payments/verify/TXN-A1B2C3D4E5F6

Existing merchant fields keep working: redirect_url, return_url, callback_url, success_url, merchant_site_url, and webhook_url. For browser return use the redirect fields; for status updates use webhook_url.