Developer Documentation

Providers

Provider Integration

SikaaHub keeps provider logic outside the financial core. Payments, withdrawals, settlements, and webhooks call provider interfaces through PaymentProviderManager.

Modes

• internal_wallet_mode: development and closed-loop wallet movement. Confirmation debits and credits SikaaHub wallets immediately.
• external_provider_mode: confirmation sends collection or payout instructions to a provider. The payment remains awaiting_provider or processing until webhook or verification finalizes it.

Set the mode with:

PAYMENT_MODE=internal_wallet_mode
DEFAULT_PAYMENT_PROVIDER=mock

Interfaces

• PaymentProviderInterface
• MobileMoneyProviderInterface
• BankTransferProviderInterface
• GhIPSSProviderInterface
• SmsProviderInterface
• NotificationProviderInterface

Current development adapters:

• MockPaymentProvider
• MockMobileMoneyProvider
• MockBankTransferProvider
• MockGhIPSSProvider

Future placeholders:

• HubtelProvider
• PaySwitchProvider
• ExpressPayProvider
• BankPartnerProvider
• GhIPSSPartnerProvider

Admin Endpoints

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

Only super_admin can create or edit provider credentials. API responses never return raw credentials.

Provider Logs

Every provider call creates a provider_transactions record with masked request/response payloads, provider reference, normalized status, operation, and direction.

Provider statuses are normalized to:

• pending
• successful
• failed
• timeout
• unknown

Sensitive values such as secrets, tokens, passwords, PINs, and phone numbers are masked before logging.