Jayb Developer Documentation

Jayb provides non-custodial financial infrastructure for applications operating in Africa and globally. Integrate once to accept payments across Safaricom M-Pesa, Hormuud EVC+, Telesom Zaad, Dahabshiil eDahab, Ethiopian Telebirr & CBE Birr, domestic mobile money and bank transfers in 30+ African countries, international cards, and high-value US/UK/EU domestic bank wires with zero interchange fees.

Authenticate your requests by including your secret API key in the standard HTTP Authorization header:

Authorization: Bearer YOUR_JAYB_API_KEY

The Jayb Widget opens an interactive, mobile-responsive checkout modal. It handles mobile money number input, fee calculation, STK status polling, and card authorization.

<!-- 1. Include SDK in your HTML -->
<script src="https://jayb.page.ke/widget.js"></script>

<!-- 2. Launch when user clicks your Checkout button -->
<script>
  async function pay() {
    // Call your backend to generate a session
    const res = await fetch("/api/my-checkout-session", { method: "POST" });
    const { sessionToken } = await res.json();

    // Launch Jayb modal
    JaybPay.open({
      sessionToken: sessionToken,
      host: "https://jayb.page.ke",
      onSuccess: (data) => {
        console.log("Payment successful! Ref: " + data.reference);
        window.location.href = "/receipt?id=" + data.reference;
      },
      onCancel: () => {
        console.log("Checkout modal dismissed.");
      }
    });
  }
</script>

Create a checkout session from your backend. A session calculates fee additions (if enabled), records metadata, and returns a session_token for the widget or a hosted_checkout_url.

{
  "amount": 5000,
  "currency": "KES",
  "cover_fees": true,
  "payer_name": "Amina Warsame",
  "payer_phone": "+254712345678",
  "recurring": false,
  "metadata": {
    "invoice_id": "INV-2026-901"
  }
}

{
  "session_token": "chk_live_a1b2c3d4e5f6...",
  "reference": "CHK-890123-X9Y2",
  "status": "pending",
  "amount": 5000.0,
  "fee_covered_amount": 250.0,
  "total_charged_amount": 5250.0,
  "currency": "KES",
  "hosted_checkout_url": "https://jayb.page.ke/checkout/chk_live_a1b2c3d4e5f6...",
  "embed_url": "https://jayb.page.ke/embed/checkout?token=chk_live_a1b2c3d4e5f6..."
}

Unlike cards that charge in the background, African mobile money (M-Pesa, EVC+, Zaad) requires the user to enter their PIN on their phone screen. If an unexpected STK prompt appears, users reject or cancel it. Jayb solves this with an end-to-end automated subscriber communication loop:

8. Custom Fee Coverage Configuration

In platforms like eSadaqa, donors frequently opt to cover gateway processing fees so that 100% of their donation reaches the intended charity. Jayb allows each client application to configure fee rules directly in their Client App Portal:

When an event occurs, Jayb sends a POST request to your configured webhook_url. Verify signatures using your application's webhook_secret.

{
  "event": "payment.success",
  "data": {
    "reference": "CHK-890123-X9Y2",
    "amount": 5000.0,
    "fee_covered_amount": 250.0,
    "total_charged_amount": 5250.0,
    "currency": "KES",
    "channel": "mpesa",
    "payer_name": "Amina Warsame",
    "payer_phone": "+254712345678",
    "channel_reference": "QHJ891K20X",
    "metadata": {
      "invoice_id": "INV-2026-901"
    },
    "completed_at": "2026-10-10T23:30:00Z"
  }
}

10. Cross-Border Supplier Settlements (China & Dubai)

Settle freight supplier invoices or diaspora landlord payouts directly via locked FX quotes and local clearing:

# 1. Request Guaranteed Quote
curl -X POST https://jayb.page.ke/api/v1/transfers/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_currency": "KES", "destination_currency": "CNY", "source_amount": 1000000}'

# 2. Request Payout
curl -X POST https://jayb.page.ke/api/v1/transfers/request_payout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "QUO-781923",
    "supplier_name": "Yiwu Cargo Express Ltd",
    "supplier_bank_account": "62220210010098231",
    "supplier_bank_name": "Industrial and Commercial Bank of China (ICBC)"
  }'

11. Sandbox Testing & Test Numbers

In sandbox mode, use the following test phone numbers to verify your app's handling of success, insufficient balance, or PIN cancellation: