# 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

{% hint style="info" %}
Navigation: Use the sub-section drop-downs (>) in the left-side pane, together with the right-side headings, to quickly locate the API functionality you're looking for.
{% endhint %}

### Develop your Front-end and Back-end

Commonly, BaaS partners would have their own customer front-end and back-end 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 Choice Bank's BaaS APIs in the back-end, and Choice Bank's open-banking platform will process the request and give feedback. The diagram below illustrates the high level architecture of the whole communication process.

<figure><img src="/files/DAU21elCXtVnxkzq6Ovl" alt=""><figcaption></figcaption></figure>

### 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

```json
{
    "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.
}
```

<table><thead><tr><th>Fields</th><th width="409">Description</th><th width="90">Type</th><th width="110">Is Required</th></tr></thead><tbody><tr><td><code>requestId</code></td><td>ID of the request. Please ensure the request id is unquie for every API call.</td><td>string</td><td>TRUE</td></tr><tr><td><code>sender</code></td><td>General field of the request body. Choice API will identify the sender by this field. Place your sender ID here.</td><td>string</td><td>TRUE</td></tr><tr><td><code>locale</code></td><td>General parameter of the request body. Choice API will decide the language of the response message according to this field. Place the <code>en_KE</code> by default.</td><td>string</td><td>TRUE</td></tr><tr><td><code>timestamp</code></td><td>General parameter of the request body. The millisecond of UNIX time sending the request.</td><td>long</td><td>TRUE</td></tr><tr><td><code>salt</code></td><td>String to obscure the signature for every single request.</td><td>string</td><td>TRUE</td></tr><tr><td><code>signature</code></td><td>Signature of the request. For method to sign the request message, please refer to <a href="/pages/aLHU98394KL1B4jgJDnE">Authentication</a></td><td>string</td><td>TRUE</td></tr><tr><td><code>params</code></td><td>Actual request parameters of the request. Different API requires different fields in params object.</td><td>object</td><td>TRUE</td></tr></tbody></table>

### Response Message Template

```json
{
    "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.
}
```

<table><thead><tr><th width="141">Fields</th><th width="517">Description</th><th width="90">Type</th></tr></thead><tbody><tr><td><code>code</code></td><td>Return code. "00000" indicate the request completed successfully, otherwise, the request is failed. Plase refer to the Error code for details.</td><td>string</td></tr><tr><td><code>msg</code></td><td>The response message.</td><td>string</td></tr><tr><td><code>sender</code></td><td>The sender of the response message is always to be "choice.baas"</td><td>string</td></tr><tr><td><code>requestId</code></td><td>The request ID which the result responds to.</td><td>string</td></tr><tr><td><code>locale</code></td><td>Language of the <code>msg</code>field.</td><td>string</td></tr><tr><td><code>timestamp</code></td><td>General parameter of the response body. The millisecond of UNIX time sending the request.</td><td>long</td></tr><tr><td><code>data</code></td><td>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".</td><td>object</td></tr><tr><td><code>salt</code></td><td>String to obscure the signature for every single request. For method to verify the signature, please refer to <a href="/pages/aLHU98394KL1B4jgJDnE">Authentication</a></td><td>string</td></tr><tr><td><code>signature</code></td><td>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.</td><td>string</td></tr></tbody></table>

## Terminologies

Common terms that you will come across.

<table><thead><tr><th width="193">Term</th><th>Definition</th></tr></thead><tbody><tr><td>BaaS API Platform</td><td>Choice's Banking-As-A-Service API platform, aiming to provide non-bank enterprises with core banking functions, payment &#x26; card solutions, compliance &#x26; rist infrastructure etc.</td></tr><tr><td>BaaS Partner</td><td><p>Third-party that integrates with Choice. </p><p>i.e. You company</p></td></tr><tr><td>SME</td><td>Small and Medium-sized Enterprises.</td></tr><tr><td>LLC</td><td>Limited Liability Company.</td></tr><tr><td>OTP</td><td><p>One-time-password. </p><p>A time-sensitve, single-use numeric code delivered via SMS or app to authenticate high-risk transactions.</p></td></tr><tr><td>SMS</td><td>Short Message Service. A channel for delivering payment notifications, balance updates and OTPs.</td></tr><tr><td>Paybill</td><td>A merchant payment collection service by Safaricom M-PESA, where businesses receive customer payments via a unique 5-7 digits shortcode.</td></tr><tr><td>Till/BuyGoods</td><td>M-PESA's merchant-facing service where businesses use a registered Till Number (e.g., 123456) to receive payments for retail transactions. </td></tr><tr><td>B2C</td><td><p>Business-to-Consumer. </p><p>In Choice's ecosystem, it refers to transfer to M-PESA mobile money.</p></td></tr><tr><td>B2B</td><td><p>Business-to-Business. </p><p>In Choice's ecosystem, it refers to transfer to M-PESA Paybill/Till.</p></td></tr><tr><td>Pesalink</td><td>Kenya’s real-time bank-to-bank payment system operated by the Kenya Bankers Association (KBA).</td></tr><tr><td>RTGS</td><td><p>Real-Time Gross Settlement. </p><p>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.</p></td></tr><tr><td>EFT</td><td><p>Electronic Funds Transfer.</p><p>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.</p></td></tr><tr><td>SWIFT</td><td><p>Society for Worldwide Interbank Financial Telecommunication.</p><p>A global messaging network for cross-border payments. Kenyan banks use SWIFT for international trade settlements and diaspora remittances.</p></td></tr><tr><td>STK Push</td><td><p>SIM ToolKit Push. </p><p>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.</p></td></tr><tr><td>KRA</td><td>Kenya Revenue Authority. </td></tr><tr><td>KRA PIN</td><td><p>Kenya Revenue Authority Personal Identification Number. </p><p>A mandatory tax identification number issued by the Kenya Revenue Authority to individuals and entities for tracking tax compliance.</p></td></tr><tr><td>Webhook Notifications</td><td>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.</td></tr><tr><td>Short Code</td><td><ol><li><p>M-PESA Paybill / Till-BuyGoods Shortcode</p><p>Refers to the ​M-PESA-specific shortcodes allocated to businesses or merchants for facilitating mobile payments. </p></li><li><p>Choice-Allocated Collection Shortcode</p><p>A ​proprietary 5-7 digits shortcode assigned by Choice to account numbers, enabling simplified and shortened identifiers for payment collections.</p></li></ol></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://choice-bank.gitbook.io/choice-bank/getting-started/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.