Jayb Developer Documentation

# 1. Create or Look Up a Wallet (supports multi-currency fiat & loyalty points)
POST https://jayb.page.ke/api/v1/wallets
{
  "phone_number": "+254712345678",
  "full_name": "Amina Hassan",
  "wallet_type": "individual",
  "currencies": ["KES", "USD", "CNY", "AED"]
}

# 2. Fetch Wallet Balances (Points + All Open Currency Sub-Accounts)
GET https://jayb.page.ke/api/v1/wallets/+254712345678/balance

# 3. Fetch Wallet Transactions (Points Ledger + Fiat Ledger)
GET https://jayb.page.ke/api/v1/wallets/+254712345678/transactions?limit=25&offset=0

# 4. Open Any Supported Currency Sub-Account (KES, USD, EUR, GBP, CNY, AED, UGX, TZS, RWF)
POST https://jayb.page.ke/api/v1/wallets/+254712345678/open_currency
{ "currency": "EUR" }

# 5. Upgrade a Points-Only Wallet to Fiat / Current Account via KYC
POST https://jayb.page.ke/api/v1/wallets/+254712345678/upgrade_fiat
{ "id_number": "29481023", "kra_pin": "A009182736Z", "currencies": ["KES", "USD"] }

# 6. Top Up Wallet (channels: "mpesa", "airtel_money", "card", "pesalink")
POST https://jayb.page.ke/api/v1/wallets/+254712345678/top_up
{ "amount": 20000.0, "currency": "KES", "channel": "mpesa" }

# 7. Transfer Money, Pay Business, or Withdraw to Mobile Money / Bank
# - Internal personal P2P ("channel": "jayb"): 0% fee
# - Internal business payment ("channel": "jayb"): follows business fee_bearer ("business", "customer", "split")
# - External mobile/bank withdrawal or payout ("channel": "mpesa" | "airtel_money" | "pesalink"): 1.0% fee
# - funding_source: "wallet:KES", "wallet:USD", "direct:mpesa", "direct:airtel_money", or "direct:pesalink"
POST https://jayb.page.ke/api/v1/wallets/+254712345678/transfer
{
  "recipient": "582910",
  "amount": 4000.0,
  "currency": "KES",
  "funding_source": "wallet:KES",
  "channel": "jayb",
  "note": "Order #1042"
}

# 8. Instant Multi-Currency Wallet Conversion
POST https://jayb.page.ke/api/v1/wallets/+254712345678/convert_currency
{ "from_currency": "KES", "to_currency": "USD", "amount": 12950.0 }

# 1. Create a Separate Business Owned by an Individual
POST https://jayb.page.ke/api/v1/businesses
{
  "owner_phone": "+254712345678",
  "business_name": "Kasoko Hardware Depot",
  "business_type": "Wholesale",
  "fee_bearer": "split",
  "fee_percentage": 1.5,
  "currencies": ["KES", "USD", "CNY"]
}

# 2. List All Separate Businesses Managed by an Individual
GET https://jayb.page.ke/api/v1/wallets/+254712345678/businesses

# 3. Update Wallet Fee Bearer Policy ("business", "customer", or "split")
POST https://jayb.page.ke/api/v1/wallets/fee_policy
{ "merchant_code": "582910", "fee_bearer": "customer", "fee_percentage": 1.5 }

# 4. Provision an Ecosystem Merchant Subaccount (or Standalone Client App)
POST https://jayb.page.ke/api/v1/merchants/provision
{
  "name": "Mombasa Auto Spares Ltd",
  "external_reference": "kasoko-acc-441",
  "contact_email": "accounts@mombasaspares.co.ke",
  "contact_phone": "+254722111222"
}

# 5. Submit Merchant KYB Dossier & Check KYB Status
POST https://jayb.page.ke/api/v1/merchants/kyb
{
  "external_reference": "kasoko-acc-441",
  "legal_business_name": "Mombasa Auto Spares Limited",
  "registration_number": "PVT-2024-88219",
  "tax_id": "P051928374K",
  "director_name": "Salim Bakari",
  "director_id_number": "22819201"
}
GET https://jayb.page.ke/api/v1/merchants/kyb_status?external_reference=kasoko-acc-441

# 6. Configure or Query Checkout Fee Coverage Policy for a Subaccount
POST https://jayb.page.ke/api/v1/merchants/fee_policy
{ "external_reference": "kasoko-acc-441", "mode": "split" }
GET https://jayb.page.ke/api/v1/merchants/fee_policy?external_reference=kasoko-acc-441

# 1. Award Points (explicit points or auto-calculated from event_type & amount_kes)
POST https://jayb.page.ke/api/v1/points/earn
{ "phone_number": "+254712345678", "event_type": "payment_received", "amount_kes": 5000, "reference_id": "ORD-901" }

# 2. Redeem Points Immediately
POST https://jayb.page.ke/api/v1/points/redeem
{ "phone_number": "+254712345678", "points": 250, "purpose": "checkout_discount", "reference_id": "RED-901" }

# 3. Two-Phase Points Reservation (Reserve -> Commit or Release)
POST https://jayb.page.ke/api/v1/points/reserve
{ "phone_number": "+254712345678", "points": 500, "purpose": "cart_hold", "reference_id": "HOLD-402" }

POST https://jayb.page.ke/api/v1/points/commit
{ "reference_id": "HOLD-402", "description": "Order completed" }

POST https://jayb.page.ke/api/v1/points/release
{ "reference_id": "HOLD-402" }

# 4. Refund Redeemed Points
POST https://jayb.page.ke/api/v1/points/refund
{ "phone_number": "+254712345678", "points": 250, "reference_id": "REFUND-901", "description": "Cancelled order" }

<script src="https://jayb.page.ke/widget.js"></script>
<script>
  JaybPay.open({
    sessionToken: "chk_live_a1b2c3d4...",
    host: "https://jayb.page.ke",
    onSuccess: (data) => window.location.href = "/receipt?id=" + data.reference,
    onCancel: () => console.log("Checkout closed")
  });
</script>

<!-- Or embed directly via responsive iFrame -->
<iframe src="https://jayb.page.ke/embed/checkout?session=chk_live_a1b2c3d4..." allow="payment"></iframe>

# 1. Create a Hosted / Embedded Checkout Session
POST https://jayb.page.ke/api/v1/checkout/sessions
{
  "amount": 5000,
  "currency": "KES",
  "title": "Invoice #INV-2026-901",
  "subaccount": "kasoko-acc-441",
  "fee_coverage": { "mode": "split", "percentage": 2.5 },
  "award_points": true,
  "customer": {
    "name": "Amina Hassan",
    "phone": "+254712345678",
    "email": "amina@example.com"
  },
  "metadata": { "invoice_id": "INV-2026-901" },
  "success_url": "https://yourapp.com/orders/success",
  "cancel_url": "https://yourapp.com/orders/cancel"
}
# Response (Checkout & Payment Completion):
# {
#   "success": true,
#   "token": "chk_...",
#   "reference": "CHK-...",
#   "amount": 5000.0,
#   "covered_fee_amount": 62.5,
#   "total_charged_amount": 5062.5,
#   "currency": "KES",
#   "status": "pending",
#   "checkout_url": "https://jayb.page.ke/checkout/chk_...",
#   "embed_url": "https://jayb.page.ke/embed/checkout?session=chk_...",
#   "points_earned": 50,
#   "points_balance": 150,
#   "wallet_claimed": false,
#   "points_only": true,
#   "claim_wallet_url": "https://jayb.page.ke/claim?phone=%2B254712345678",
#   "kyc_url": "https://jayb.page.ke/portal/individual/kyc",
#   "transaction_message": "Payment of KSh 5,062.50 confirmed (Ref: CHK-...). You earned +50 Jayb Points! Your points balance is 150 PTS (worth KSh 150). Claim your wallet to redeem points anytime (complete KYC at your own time to hold fiat): https://jayb.page.ke/claim?phone=%2B254712345678"
# }

# 2. Retrieve, Initiate Payment, or Poll a Checkout Session
GET  https://jayb.page.ke/api/v1/checkout/sessions/:token_or_reference
POST https://jayb.page.ke/api/v1/checkout/sessions/:token_or_reference/pay
{ "payment_method": "mpesa", "phone_number": "+254712345678" }
GET  https://jayb.page.ke/api/v1/checkout/sessions/:token_or_reference/poll

# 3. Direct Headless Invoice Collection (M-Pesa STK Push or Dedicated Virtual Account)
POST https://jayb.page.ke/api/v1/checkout/invoice
{
  "invoice_id": "INV-2026-902",
  "amount_kes": 15000,
  "phone_number": "+254712345678",
  "customer_name": "Amina Hassan",
  "payment_channel": "mpesa_stk" # or "virtual_account" for PesaLink / Bank Transfer
}

# 1. Fetch Live Customer FX Rates Across All 9 Currencies
GET https://jayb.page.ke/api/v1/fx/rates?base_currency=KES

# 2. Request a 15-Minute Locked FX Quote
POST https://jayb.page.ke/api/v1/fx/quote
{ "from_currency": "KES", "to_currency": "CNY", "amount": 250000 }

# 3. Create (and Optionally Auto-Approve & Dispatch) an International Supplier Payout
POST https://jayb.page.ke/api/v1/transfers/request_payout
{
  "merchant_code": "582910",
  "corridor": "china_cny",              # "china_cny", "dubai_aed", "global_usd", "europe_eur", "uk_gbp"
  "funding_source": "wallet:KES",       # or "wallet:USD", "direct:mpesa", "direct:airtel_money", "direct:pesalink"
  "amount_local": 250000,               # or specify "amount_foreign": 13680.75
  "validate_balance": true,
  "auto_approve": true,                 # set true to debit & dispatch immediately; false to queue for approval
  "shipping_mark": "CRG-YW-889",
  "invoice_url": "https://cargo.ke/invoices/CRG-YW-889.pdf",
  "beneficiary_details": {
    "name": "Guangzhou Electronics Trading Co.",
    "bank_name": "ICBC Guangzhou Branch",
    "account_number": "6228480019283746519",
    "bank_code": "ICBKCNBJCAN"
  }
}

# 4. Approve a Queued Payout, Confirm Choice Bank OTP, or List / Inspect Transfers
POST https://jayb.page.ke/api/v1/transfers/:id/approve
{ "funding_source": "wallet:KES" }

POST https://jayb.page.ke/api/v1/transfers/:id/confirm_otp
{ "otp_code": "482910" }

GET  https://jayb.page.ke/api/v1/transfers?corridor=china_cny&status=processing
GET  https://jayb.page.ke/api/v1/transfers/:id

# 1. Bulk M-Pesa B2C Disbursement (Requires Idempotency-Key Header)
POST https://jayb.page.ke/api/v1/payouts/bulk_mpesa
Idempotency-Key: payroll_batch_2026_11
{
  "funding_phone_number": "+254712345678",
  "purpose": "November Payroll",
  "recipients": [
    { "phone_number": "+254711000001", "amount": 25000, "name": "John Kamau" },
    { "phone_number": "+254722000004", "amount": 32000, "name": "Grace Otieno" }
  ]
}

# 2. Configure & Inspect Automated Bank Settlement Sweeps
POST https://jayb.page.ke/api/v1/sweeps/configure
{
  "destination_bank_name": "Equity Bank Kenya",
  "destination_bank_code": "68",
  "destination_account_number": "0180291827361",
  "destination_account_name": "Kasoko Marketplace Ltd",
  "sweep_mode": "threshold",
  "threshold_amount": 100000.0,
  "batch_time": "17:00"
}
GET https://jayb.page.ke/api/v1/sweeps/status

computed = OpenSSL::HMAC.hexdigest("SHA256", webhook_secret, "#{timestamp}.#{raw_body}")
Rack::Utils.secure_compare(computed, request.headers["X-Jayb-Signature"])