FAQs
FAQs
BaaS (Banking-as-a-Service)
A digital product where banks expose their financial services, e.g., via APIs, H2H, etc., so third-party developers can build applications on top of them.
API Banking
The secure, authorized sharing of financial data, services, and functionalities (payments, transfers, account management, ID verification, etc.) through programmatic interfaces instead of traditional bank portals. It acts as a digital bridge, allowing external software to directly access banking functions without needing the bank's own app.
MSB – Money Services Business
A regulatory classification (common in Canada, U.S., and other jurisdictions) for non-bank financial institutions that provide services such as money transmission, currency exchange, check cashing, or stored value issuance. Equivalent licensing categories may exist under different names in other countries.
MRP – Money Remittance Provider
An entity licensed by CBK to facilitate domestic and/or cross-border fund transfers on behalf of customers. In many jurisdictions, this category is called MTO (Money Transfer Operator) or falls under a broader payments/remittance license.
PSP – Payment Service Provider
A licensed institution that enables businesses to accept and process payments (cards, bank transfers, wallets, etc.) without needing to become financial institutions themselves.
DCP – Digital Credit Provider
A regulated lender that offers credit through digital channels (e.g., mobile or online platforms).
LONO — Letter of No Objection
A formal document issued by a regulator (usually CBK) confirming that it has no objection to a proposed activity, partnership, product launch, or integration.
Whitelisting
The process of allowing only approved accounts or endpoints to access a service or API for security/compliance purposes.
POP (Purpose of Payment)
A document, receipt, or digital confirmation justifying the legitimacy of a transaction.
Callback URL
A URL provided by the BaaS partner to receive asynchronous notifications from our APIs when an event occurs (e.g., transaction result notification).
PesaLink
A Kenyan interbank transfer service that allows instant money transfers between accounts in different banks.
PesaLink Sponsorship
A model that allows us to provide unlicensed BaaS customers with access to PesaLink services at subsidized transaction costs.
Rail
A payment network or infrastructure that facilitates the movement of money between accounts, banks, or systems.
Embedded Finance
Integrating financial services (payments, lending, insurance, etc.) directly into other, possibly non-financial, platforms or apps.
API Signing
A security mechanism where API requests are digitally signed to verify authenticity and integrity.
Who is BaaS meant for?
Payment service providers, fintechs, finance startups, really anyone who wants to hold and move money.
What do I need to be a Choice Bank customer?
Please contact our branch operations team; they'll get you started. See their contacts here.
What do we need to use BaaS?
Any client-facing digital product meant to hold and/or move money or any such use-case — perfect for BaaS. See our contacts here.
What is the process of opting into BaaS?
Use-case alignment > Technical kick-off > Sandbox testing > Go-live
What do you offer as BaaS products/models?
We offer BaaS under three main models: Virtual Account, Sub-account, and IMT model. Your particular use-case and licensure status will determine which one best suits your business.
Do you offer 24/7 support?
No, as a bank we operate only during working hours (8am to 4:30pm EAT), but off-hours support is available in cases of serious downtimes.
Must I onboard my business using its official registered name?
Yes, for merchants coming on as business customers and SME onboardings via API, this is mandatory.
Is proof of license application acceptable?
Yes, certain features/exemptions are available if you can provide evidence of an active application process for the requisite license.
For BaaS, how long can I expect integration and testing to take?
This depends on your tech team’s availability and the sophistication of your use-case, but based on past integrations, it typically takes 1–3 months.
Can we get a free BaaS trial?
Yes, this can be granted for up to one month, subject to deliberation with your account manager.
What do we need to get into sandbox?
API sandbox keys: `sender` and `senderKey`, which should be kept private at all times. Please contact your account manager for access.
Which features should I test first?
This depends on your particular use-case, but the standard starting point is to onboard yourself as an SME client, which marks access to our APIs.
How do I authenticate into APIs?
We have a robust authentication algorithm using SHA-256 encryption and your private key (`senderKey`) to allow secure access to our API banking features.
What type of accounts do you offer?
Two main types: personal and business.
Personal: Wallets and current accounts
Business: Merchant and SME accounts
All business customers, including non-BaaS ones, have merchant accounts. Except for merchant accounts, all other account types can be onboarded via API.
What's the difference between wallets and current accounts?
- **Wallets:** Transaction max KES 20,000, holding capacity KES 300,000, require national ID and selfie. - **Current accounts:** No such limits; require KRA PIN certificate in addition to ID and selfie.
What's the difference between SME and merchant accounts?
SME accounts can only be created via API; merchant accounts can be created via standard onboarding procedures.
What sort of features do you offer via API?
APIs allow you to: - Onboard accounts - Make transfers, validating recipients via Hakikisha - Monitor statuses at all stages - Close accounts - Pull transactions by account number - Activate dormant accounts - Update signatory info (phone, email) - Amend KYC - Edit account names - Push STK prompts to Mpesa holders - Execute FX transfers - Pay for utilities (airtime, KPLC, water, etc.)
Are there any differences between sandbox and production?
Sandbox differs lightly in terms of which third-party PSP has granted UAT access. Example: - Safaricom UAT available - PesaLink and Airtel UAT are ongoing, so these won't terminate on sandbox but work in production.
Will your APIs accept dummy documentation just for testing purposes?
Yes, when testing, you don't need to pass real documentation.
Do you offer callback notifications?
Yes. See the procedure for setup and templates for all callback notifications [here](#).
Do you support dynamic accounts?
No, accounts are static — they cannot be closed at a predefined time or change account numbers.
Can we freeze/reverse transfers?
Yes. We offer a reversal API, and our operations team can act on problematic accounts/transfers.
How long do transfers take to process and complete?
Depends on the payment method used. See full TATs [here](#).
Which FX currencies and conversion pairs do you support?
- **Currencies:** KES, TZS, UGX, USD, EUR, GBP, CNY - **Pairs:** USD/KES, EUR/KES, GBP/KES, KES/TZS, KES/UGX, KES/RWF, GBP/USD, EUR/GBP, EUR/USD
How do I do an FX transfer?
- Merchants: via Internet Banking portal or OTC FX team - BaaS customers: via FX API
How do I deposit money into my sandbox account for transfer tests?
Use our sandbox Mpesa Paybill **4101847**, with the account number being the test account’s.
How long do I have to validate OTP?
20–30 minutes depending on the API. If the validation window passes before confirmation, the onboarding/transfer will fail.
Why are onboardings going to manual review?
Sandbox onboardings go to manual review by design. In production, if docs/details are correct, most onboardings pass automatically; worst-case KYC-flagged cases: 24 hours.
How long will it take to return an account number once onboarding is complete?
Typical: a few minutes for SME onboardings; worst-case: 24 hours for KYC-flagged or personal account onboardings.
What apps/knowhow will I need to test APIs?
- API client (Postman, curl) - Understanding HTTP requests (methods, headers, parameters, JSON responses) - Authentication (API keys, tokens, signatures) - Parsing status codes and error messages
How many business accounts can I have?
- Merchant and parent-SME: max 10 KES accounts + 1 of each foreign currency - Virtual/sub-accounts: max 50 (can be increased with justification)
Can you increase the number of accounts I can have?
- Merchant accounts: No - Parent-SMEs and VAs/sub-accounts: Yes, with justification
How many times can I use one phone#/ID# for onboardings?
- Personal accounts: only once per phone/ID - SME accounts: unlimited uses of the same phone number
What do I do if I haven't received an OTP?
Resend using `/common/sendOtp` API or the dedicated resend API.
What do I do if subsequent attempts to send an OTP fail?
Try the alternative delivery option (SMS or email). If this fails, contact BaaS support immediately.
What is the sequence of endpoints for onboardings?
See flows for current accounts, wallets, and SME accounts.
I'm getting a transaction/API error — what does it mean?
- Transaction errors: see the full list [here](#) - API response codes: see descriptions [here](#)
What do I need to get whitelisted?
Contact the BaaS team via work lines or support email with request + use-case justification.
What can I and can't I test on sandbox?
Most APIs are available. Exceptions: Airtel Money wallet transfers, PesaLink, RTGS, SWIFT.
Which KYC will I need to submit for the various account types?
- Wallets: national ID + selfie - Current accounts: ID + selfie + KRA PIN certificate See [KYC requirements](#) for merchant and SME accounts.
Do you offer notifications to end-users?
- API-driven payouts: no default SMS notifications to payee - You can pass the recipient’s number via `payeemobilefornotification` param - See list of SMS notifications + templates [here](#)
What's the minimum/maximum amount I can send?
Depends on product: - Internal transfers via API: min KES 0.01 - IB/M-Pesa payouts: min KES 10 - STK pushes: min KES 1 - Max amounts: see wallet/payment method limits [here](#)
We are getting a "500" error response when sending a request payload — why?
Indicates a typographical error in the base-URL/endpoint string. Confirm it and retry.
Do you have algorithms to help automate signing?
Yes, see our Java implementation [here](#) for generating a signature with the authentication procedure.
Can you give us test accounts for all payment channels?
We provide **payee test accounts** for mobile money and internal transfer tests. Payer accounts must be your onboarded accounts.
I sent in wrong onboarding details — can I amend them?
Yes, via Submit/Pullback API. You can also change or add a phone number/email via API after onboarding.
Why is the BaaS dashboard not reflecting all my transaction data?
The dashboard is designed to display a quick summary of transactional activity for all accounts under your BaaS channel in the last 24 hours, not all-time.
Why do you require PoP for pay-in?
Purpose-of-Payment documentation is mandatory for transfers of KES 1,000,000 (or USD 10,000 equivalent) and above. This is a standard compliance/AML measure for large volumes.
What are Levels I, II, and III in Internet Banking?
Tiers of access privileges for an Internet Banking (merchant account) user/admin: - **Level I:** Most privileged - **Level III:** Least privileged
Can you whitelist our IP?
No, we no longer whitelist IP addresses. Whitelisting applies to actual account numbers or BaaS channels.
Which licenses do we need for the virtual account BaaS model?
A DCP license will do, or any other license that allows your organization to hold customer funds.
We're getting "system error/busy" on IB/BaaS portal — why?
Temporary bandwidth lag caused by many users making simultaneous calls to a resource. If it persists for more than 2 minutes, contact BaaS support.
Can we switch our BaaS model after going live?
Yes, after proper contractual discussions with your account manager.
Can we use one callback URL for both sandbox and production?
Technically yes, but strongly discouraged. Both environments use the same format for notifications, which can lead to confusion and erroneous transactions.
Are there any special API formatting conventions we should know?
Yes: - Mobile numbers accept only nine digits (no `254` or `0` prefix) - Flattened arrays use square brackets (e.g., `array[0].field`) - Empty parameters must be included as `param={}` - All other conventions are documented in our GitBook.
Who do we contact to begin the account opening process?
Contact our team for personal, business, or API onboarding requests.
Will an external recipient be notified of an incoming, API-initiated payout?
Only if you pass the recipient’s number as `payeemobilefornotification` param. See detailed SMS notifications + templates [here](#).
Which APIs require prior whitelisting?
- Merchant Bulk Transfer - Internal Transfers without OTP - Internal Transactions by Batch - Callback 0020
Can our accounts receive deposits via Paybill?
Yes. Each live Choice Bank account can receive deposits using Mpesa Paybill **444174**.
How can we track transactional activity of our onboarded/child accounts?
Check the Transactions pane in your BaaS dashboard.
Which callbacks should we track for pay-ins and payouts?
- **Merchant accounts:** callbacks 0022 and 0004 - **Other API-onboarded accounts:** callbacks 0002 and 0003 See full list [here](#).
We received duplicate callbacks — how can we fix this?
Confirm via `notificationType` parameter that they are duplicates. If so, contact the BaaS/product team for remediation.
We initiated a payout to an M-Pesa wallet and received a reference ID, but the client hasn’t received the funds?
If a reference ID was returned, the funds were debited successfully. Contact Safaricom M-Pesa Business support for reconciliation.
Can we change our callback URL/private key ourselves?
Yes, via BaaS dashboard: Settings > Channel Information.
Do SME accounts onboarded via API need to use registered name?
Yes. For compliance, SME accounts must use the official registered name as in incorporation/business certificate.
Will we need special containers or SDK in our integration?
Yes, only if onboarding current accounts or upgrading wallets. From January 19, 2026, Smile ID document verification SDK is required for these flows.
Last updated