Developer Documentation

Endpoints

SikaaHub API Endpoints

Base URL: https://api.sikaahub.com/v1

All responses use:

{"success":true,"message":"Human readable message","data":{},"meta":{}}

Errors use:

{"success":false,"message":"Human readable error","error":{"code":"ERROR_CODE","details":{}}}

Health

• GET /health
• GET /status

Authentication

• POST /auth/register/customer
• POST /auth/register/merchant
• POST /auth/login
• POST /auth/logout
• POST /auth/refresh
• POST /auth/forgot-password
• POST /auth/reset-password
• POST /auth/verify-phone
• POST /auth/verify-device
• POST /auth/resend-otp
• POST /auth/request-password-reset
• POST /auth/change-pin
• POST /auth/change-transaction-pin
• POST /auth/set-transaction-pin
• POST /auth/verify-transaction-pin

Login supports X-Device-ID and X-App-Version. Access tokens expire. Refresh tokens are stored hashed and rotated.

Customer and merchant registrations start as pending_verification until OTP verification succeeds.

Customers

• GET /customers/me
• PUT /customers/me
• GET /customers/me/wallets
• POST /customers/me/link-wallet
• DELETE /customers/me/wallets/{id}
• GET /customers/me/transactions
• GET /customers/me/payments
• GET /customers/me/withdrawals

Merchants

• POST /merchants/apply
• GET /merchants/me
• PUT /merchants/me
• GET /merchants/me/qr
• POST /merchants/me/qr/regenerate
• POST /merchants/me/submit-kyc
• GET /merchants/me/wallet
• GET /merchants/me/transactions
• GET /merchants/me/payments
• GET /merchants/me/withdrawals
• GET /merchants/me/commissions
• GET /merchants/verify/{merchantCode}

Merchant QR payloads expose only the merchant code and a SikaaHub type marker, never internal numeric IDs.

KYC

• POST /kyc/customer/basic
• POST /kyc/merchant/basic
• POST /kyc/merchant/documents
• GET /kyc/me/status

Devices

• GET /devices
• POST /devices/trust
• DELETE /devices/{id}

QR Verification

• POST /qr/verify

Payments

• POST /payments/initiate
• POST /payments/confirm
• GET /payments/{paymentId}
• GET /payments
• POST /payments/{paymentId}/cancel

Financial creation endpoints require Idempotency-Key. Confirmation requires transaction PIN. Wallet balance updates run inside database transactions with row-level locks.

Payment lifecycle: pending, processing, successful, failed, cancelled, reversed.

Confirmed payments create one transaction record and immutable ledger entries:

• customer wallet debit
• merchant wallet credit
• optional commission debit/credit when an active commission rule applies

Wallets and Ledger

• GET /wallets/me
• GET /wallets/me/balance
• GET /wallets/me/ledger

Wallet balances are stored for fast reads. The immutable ledger is the source of truth. Every financial movement writes at least two ledger entries, one debit and one credit. Corrections must use reversal entries, not edits or deletes.

Wallet owner types:

• customer
• merchant
• system

Ledger entry types:

• payment
• withdrawal
• commission
• settlement
• refund
• reversal
• adjustment

Withdrawals

• POST /withdrawals/initiate
• POST /withdrawals/approve
• POST /withdrawals/confirm
• POST /withdrawals/complete
• GET /withdrawals/{withdrawalId}
• GET /withdrawals

Statuses: pending_customer_confirmation, pending_merchant_approval, approved, completed, failed, cancelled, reversed.

Withdrawal lifecycle:

1. Customer initiates withdrawal from merchant.

2. Merchant approves.

3. Customer confirms with transaction PIN.

4. Merchant completes after cash payout.

5. Merchant wallet is debited.

6. System settlement placeholder wallet is credited.

7. Commission is calculated and ledgered when applicable.

Transactions

• GET /transactions
• GET /transactions/{transactionId}
• GET /transactions/summary
• GET /transactions/export

Supported filters: type, status, from, to, cursor, limit. Default limit is 20, maximum is 100.

Cursor format is opaque to clients. Use the next_cursor returned in meta.

{
  "meta": {
    "limit": 20,
    "next_cursor": "MjAyNi0wNS0xMSAwNjowMDowMHwxMjM=",
    "has_more": true
  }
}

Merchant Commissions

• GET /merchants/me/commissions
• GET /merchants/me/commission-summary

Admin Commission Rules

• GET /admin/commission-rules
• POST /admin/commission-rules
• PUT /admin/commission-rules/{id}
• POST /admin/commission-rules/{id}/activate
• POST /admin/commission-rules/{id}/deactivate

Rules support flat and percentage commissions with optional caps.

Admin Wallet Monitoring

• GET /admin/wallets
• GET /admin/wallets/{id}
• GET /admin/wallets/{id}/ledger

Risk

• GET /admin/risk-alerts
• POST /admin/risk-alerts/{id}/resolve
• POST /admin/risk-alerts/{id}/dismiss

Basic risk checks currently flag high amounts, velocity, failed PIN attempts, new devices, and suspicious merchant/customer patterns as placeholder hooks for a stronger fraud engine.

Webhooks

• POST /webhooks/payment-provider
• POST /webhooks/bank
• POST /webhooks/ghipss-partner
• POST /webhooks/{providerCode}
• GET /webhooks/events
• POST /webhooks/retry/{eventId}

Provider Operations

• GET /admin/provider-configs
• POST /admin/provider-configs
• GET /admin/provider-configs/{id}
• PUT /admin/provider-configs/{id}
• POST /admin/provider-configs/{id}/activate
• POST /admin/provider-configs/{id}/deactivate
• GET /admin/providers
• GET /admin/providers/{providerCode}/health
• POST /admin/providers/{providerCode}/check-health

Settlements and Reconciliation

• GET /admin/settlements
• GET /admin/settlements/{id}
• POST /admin/settlements/generate
• POST /admin/settlements/{id}/mark-paid
• POST /admin/settlements/{id}/cancel
• GET /merchants/me/settlements
• GET /merchants/me/settlements/{id}
• POST /admin/reconciliation/run
• GET /admin/reconciliation/runs
• GET /admin/reconciliation/runs/{id}
• GET /admin/reconciliation/items
• POST /admin/reconciliation/items/{id}/resolve

Webhook writes store the raw payload and external event ID to prevent duplicate processing.

Developer API Keys

• POST /developer/api-keys
• GET /developer/api-keys
• DELETE /developer/api-keys/{id}

API keys are hashed in the database and only shown once at creation.

Mobile App APIs

• GET /app/config
• POST /mobile/auth/register/customer
• POST /mobile/auth/register/merchant
• POST /mobile/auth/login
• POST /mobile/auth/logout-all
• GET /mobile/customer/home
• GET /mobile/merchant/home
• POST /mobile/qr/verify
• POST /mobile/payments/preview
• POST /mobile/payments/initiate
• POST /mobile/payments/confirm
• POST /mobile/withdrawals/preview
• POST /mobile/withdrawals/initiate
• GET /mobile/merchant/withdrawal-requests
• POST /mobile/merchant/withdrawal-requests/{id}/approve
• POST /mobile/merchant/withdrawal-requests/{id}/complete
• GET /mobile/customer/transactions
• GET /mobile/merchant/transactions
• GET /mobile/transactions/{id}/receipt
• GET /mobile/notifications
• GET /mobile/customer/linked-wallets
• GET /mobile/limits/me

Merchant Dashboard APIs

• GET /dashboard/merchant/summary
• GET /dashboard/merchant/analytics/transactions
• GET /dashboard/merchant/analytics/payments
• GET /dashboard/merchant/analytics/withdrawals
• GET /dashboard/merchant/analytics/commissions
• GET /dashboard/merchant/transactions
• GET /dashboard/merchant/payments
• GET /dashboard/merchant/payments/{id}
• GET /dashboard/merchant/payments/{id}/receipt
• GET /dashboard/merchant/withdrawals
• GET /dashboard/merchant/withdrawals/{id}
• GET /dashboard/merchant/withdrawal-requests
• POST /dashboard/merchant/withdrawal-requests/{id}/approve
• POST /dashboard/merchant/withdrawal-requests/{id}/reject
• POST /dashboard/merchant/withdrawal-requests/{id}/complete
• GET /dashboard/merchant/commissions
• GET /dashboard/merchant/commissions/summary
• GET /dashboard/merchant/settlements
• GET /dashboard/merchant/settlements/summary
• GET /dashboard/merchant/qr
• POST /dashboard/merchant/qr/regenerate
• GET /dashboard/merchant/qr/download
• GET /dashboard/merchant/profile
• GET /dashboard/merchant/settings
• GET /dashboard/merchant/staff
• POST /dashboard/merchant/staff
• POST /dashboard/merchant/exports/{type}
• GET /dashboard/merchant/exports
• GET /dashboard/merchant/activity
• POST /dashboard/merchant/feedback

Disputes, Feedback, and Pilot Operations

• POST /disputes
• GET /disputes
• GET /disputes/{id}
• POST /disputes/{id}/messages
• POST /disputes/{id}/close
• GET /dashboard/merchant/disputes
• GET /admin/disputes
• POST /admin/disputes/{id}/resolve
• GET /admin/pilot/merchants
• POST /admin/pilot/merchants
• GET /admin/feedback

Admin

• GET /admin/dashboard
• GET /admin/merchants
• GET /admin/customers
• GET /admin/transactions
• GET /admin/payments
• GET /admin/withdrawals
• POST /admin/merchants/{id}/approve
• POST /admin/merchants/{id}/suspend
• POST /admin/merchants/{id}/activate
• GET /admin/audit-logs
• GET /admin/risk-alerts

Stage 5 control center additions:

• GET /admin/dashboard/summary
• GET /admin/dashboard/transactions-chart
• GET /admin/dashboard/risk-summary
• GET /admin/dashboard/provider-health
• GET /admin/dashboard/settlement-summary
• GET /admin/users
• GET /admin/users/{id}
• POST /admin/users/{id}/suspend
• POST /admin/users/{id}/activate
• POST /admin/users/{id}/lock
• POST /admin/users/{id}/unlock
• POST /admin/wallets/{id}/freeze
• POST /admin/wallets/{id}/unfreeze
• GET /admin/transactions/{id}
• POST /admin/transactions/{id}/flag
• POST /admin/transactions/{id}/review
• POST /admin/transactions/{id}/reversal-request
• GET /admin/reversal-requests
• POST /admin/reversal-requests/{id}/approve
• POST /admin/reversal-requests/{id}/process
• GET /admin/fraud-rules
• POST /admin/fraud-rules
• GET /admin/observability/requests
• GET /admin/observability/errors
• GET /admin/observability/latency
• GET /admin/observability/slow-queries
• GET /admin/system/logs
• GET /admin/system/jobs

Stage 8 admin operations portal additions:

• GET /admin/operations/summary
• GET /admin/operations/today
• GET /admin/operations/alerts
• GET /admin/operations/queue-summary
• GET /admin/customers
• GET /admin/customers/{id}
• POST /admin/customers/{id}/suspend
• POST /admin/customers/{id}/force-logout
• GET /admin/merchants
• GET /admin/merchants/{id}
• POST /admin/merchants/{id}/approve
• POST /admin/merchants/{id}/reset-qr
• GET /admin/kyc/workbench
• GET /admin/kyc/submissions/{id}/documents
• GET /admin/kyc/documents/{id}/secure-download
• GET /admin/monitoring/transactions
• GET /admin/monitoring/failed-transactions
• GET /admin/monitoring/transaction-timeline/{id}
• GET /admin/finance/summary
• GET /admin/finance/ledger
• POST /admin/finance/settlements/{id}/approve
• GET /admin/support/summary
• GET /admin/support/tickets
• POST /admin/support/tickets
• GET /admin/risk/summary
• GET /admin/risk/blacklist
• POST /admin/risk/blacklist
• GET /admin/providers/{providerCode}/transactions
• POST /admin/providers/{providerCode}/maintenance-on
• GET /admin/settings
• PUT /admin/settings/{key}
• GET /admin/maintenance
• POST /admin/maintenance/enable
• POST /admin/maintenance/disable
• GET /admin/notes/{entityType}/{entityId}
• POST /admin/exports/{type}
• GET /admin/compliance/summary
• GET /admin/admin-activity
• GET /admin/announcements

Stage 9 Operations

• GET /health/deep
• GET /admin/observability/slow-requests
• CLI: php cli/worker.php --queue=default
• CLI: php cli/queue-listen.php --queue=webhooks
• CLI: php cli/retry-failed-jobs.php
• CLI: php cli/clear-stale-jobs.php
• CLI: php cli/recalculate-summaries.php --date=YYYY-MM-DD

Stage 10 Sandbox and QA

• POST /admin/sandbox/wallets/{id}/credit
• POST /admin/sandbox/wallets/{id}/debit
• POST /admin/sandbox/wallets/{id}/reset
• GET /admin/sandbox/provider-scenarios
• POST /admin/sandbox/provider-scenarios
• PUT /admin/sandbox/provider-scenarios/{id}
• POST /admin/sandbox/provider-scenarios/{id}/activate
• POST /admin/sandbox/provider-scenarios/{id}/deactivate
• POST /sandbox/provider/payments/success
• POST /sandbox/provider/payments/fail
• POST /sandbox/provider/withdrawals/success
• POST /sandbox/provider/withdrawals/fail
• POST /sandbox/provider/webhooks/send
• POST /sandbox/provider/webhooks/duplicate
• POST /sandbox/provider/webhooks/invalid-signature
• GET /admin/pilot/metrics
• GET /admin/pilot/merchant-metrics/{merchantId}
• CLI: php cli/seed-sandbox.php
• CLI: php cli/reset-sandbox.php --force
• CLI: php cli/run-qa-suite.php

Stage 11 Developer Platform

• POST /developers/register
• GET /developers/me
• PUT /developers/me
• GET /developers/apps
• POST /developers/apps
• GET /developers/apps/{id}
• POST /developers/apps/{id}/api-keys
• GET /developers/apps/{id}/api-keys
• GET /developers/apps/{id}/webhooks
• POST /developers/apps/{id}/webhooks
• POST /developers/apps/{id}/webhooks/{webhookId}/test
• GET /developers/apps/{id}/usage
• GET /developers/apps/{id}/usage/summary
• GET /partners/merchants/verify/{merchantCode}
• POST /partners/payments/preview
• POST /partners/payments/initiate
• GET /partners/payments/{id}
• GET /partners/transactions
• GET /admin/developers
• POST /admin/developers/{id}/approve
• GET /admin/developer-apps
• POST /admin/developer-apps/{id}/approve-production
• GET /admin/developer-rate-plans

Stage 12 Audit and Readiness CLI

• CLI: php cli/audit-log-validator.php
• CLI: php cli/ledger-integrity-check.php
• CLI: php cli/reconciliation-dry-run.php --date=YYYY-MM-DD
• Test: php tests/security/security-smoke-test.php