Overview

Introduction

Welcome to Choice BaaS APIs. Choice BaaS is a banking as a service platform that empowers any partner to launch their own financial products seamlessly. We believe in investing in the future and working hard towards the development of banking, payments and lending infrastructure.

Getting started

Develop your Frontend and Backend

Commonly, BaaS partners would have their own customer frontend and backend to provide their services to customers. By doing this, they can control the UI design, user interaction, business workflow, etc. When a transaction happens, it calls the Choice BaaS API in the backend, and Choice open banking platform will process the request and give feedback. The diagram below illustrates the high level architecture of the whole communication process.

Get Your Private Key

In order to connect to BaaS API, please consult your account manager to get the following information:

• Sender ID

To identify the request sent from your system.

• Private Key

To sign request and verify the signature of the response. After getting the two items above, you can start the integration in a sandbox environment. When everything's ready, the account manager will generate the formal sender ID and private key for production rollout. Please keep the private key safe in order to prevent someone faking the API call.

Message Template

Choice BaaS API only supports the JSON message. In order to standardize the format of the request and response message of Choice BaaS API, we define the request/response message template as below.

Request Message Template

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "params": {} //different API contains different params fields. Please refer to the API document for details.
}

Fields	Description	Type	Is Required
requestId	ID of the request. Please ensure the request id is unquie for every API call.	string	TRUE
sender	General field of the request body. Choice API will identify the sender by this field. Place your sender ID here.	string	TRUE
locale	General parameter of the request body. Choice API will decide the language of the response message according to this field. Place the en_KE by default.	string	TRUE
timestamp	General parameter of the request body. The millisecond of UNIX time sending the request.	long	TRUE
salt	String to obscure the signature for every single request.	string	TRUE
signature	Signature of the request. For method to sign the request message, please refer to Authentication	string	TRUE
params	Actual request parameters of the request. Different API requires different fields in params object.	object	TRUE

Response Message Template

{
    "code": "00000",
    "msg": "Completed successfully",
    "requestId": "APPREQ00990320fed02000",
    "sender": "apigw.baas.choice",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZHMUr",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "data": {} //return data of the API, please refer to the API document for the defferent return data of each API.
}

Fields	Description	Type
code	Return code. "00000" indicate the request completed successfully, otherwise, the request is failed. Plase refer to the Error code for details.	string
msg	The response message.	string
sender	The sender of the response message is always to be "choice.baas"	string
requestId	The request ID which the result responds to.	string
locale	Language of the msgfield.	string
timestamp	General parameter of the response body. The millisecond of UNIX time sending the request.	long
data	Return data. It is different along with different API. It will be null when the API doesn't return data or the request is failed, i.e. Return code is not "00000".	object
salt	String to obscure the signature for every single request. For method to verify the signature, please refer to Authentication	string
signature	Choice API signs all the response messages with the private key of the request sender. When requester receives the response, please always verify the message with the private key you got from your account manager.	string

Terminologies

Common terms that you will come across.

Term	Definition
BaaS API Platform	Choice's Banking-As-A-Service API platform, aiming to provide non-bank enterprises with core banking functions, payment & card solutions, compliance & rist infrastructure etc.
BaaS Partner	Third-party that integrates with Choice. i.e. You company
SME	Small and Medium-sized Enterprises.
LLC	Limited Liability Company.
OTP	One-time-password. A time-sensitve, single-use numeric code delivered via SMS or app to authenticate high-risk transactions.
SMS	Short Message Service. A channel for delivering payment notifications, balance updates and OTPs.
Paybill	A merchant payment collection service by Safaricom M-PESA, where businesses receive customer payments via a unique 5-7 digits shortcode.
Till/BuyGoods	M-PESA's merchant-facing service where businesses use a registered Till Number (e.g., 123456) to receive payments for retail transactions.
B2C	Business-to-Consumer. In Choice's ecosystem, it refers to transfer to M-PESA mobile money.
B2B	Business-to-Business. In Choice's ecosystem, it refers to transfer to M-PESA Paybill/Till.
Pesalink	Kenya’s real-time bank-to-bank payment system operated by the Kenya Bankers Association (KBA).
RTGS	Real-Time Gross Settlement. A high-value, immediate interbank settlement system managed by the Central Bank of Kenya (CBK). Used for large transactions (min. KES 1M) requiring irrevocable clearing, such as property purchases or treasury operations.
EFT	Electronic Funds Transfer. Batch-processed interbank transfers, typically used for payroll, recurring payments, or low-value bulk transactions. In Kenya, EFTs are often delayed (settled overnight) and cheaper than RTGS/Pesalink.
SWIFT	Society for Worldwide Interbank Financial Telecommunication. A global messaging network for cross-border payments. Kenyan banks use SWIFT for international trade settlements and diaspora remittances.
STK Push	SIM ToolKit Push. A USSD-based payment authorization method used by M-Pesa, where a secure menu is “pushed” to the user’s SIM card to confirm transactions (e.g., paying for goods via a merchant’s Till Number). Eliminates manual entry of payment details, enhancing security in Kenya’s cash-lite economy.
KRA	Kenya Revenue Authority.
KRA PIN	Kenya Revenue Authority Personal Identification Number. A mandatory tax identification number issued by the Kenya Revenue Authority to individuals and entities for tracking tax compliance.
Webhook Notifications	It is an event-driven communication mechanism using HTTP callbacks to push real-time structured data (typically JSON/XML) to a predefined URL endpoint when specific events occur. In payment ecosystem, it is widely adopted to automate transaction synchronization, reduce polling overhead, and enhance operational efficiency.
Short Code	M-PESA Paybill / Till-BuyGoods Shortcode Refers to the ​M-PESA-specific shortcodes allocated to businesses or merchants for facilitating mobile payments. Choice-Allocated Collection Shortcode A ​proprietary 5-7 digits shortcode assigned by Choice to account numbers, enabling simplified and shortened identifiers for payment collections.