# Table of Contents - [Overview | Choice Bank - API Documentation](#overview-choice-bank-api-documentation) - [Authentication | Choice Bank - API Documentation](#authentication-choice-bank-api-documentation) - [Sandbox Environment | Choice Bank - API Documentation](#sandbox-environment-choice-bank-api-documentation) - [Current Account | Choice Bank - API Documentation](#current-account-choice-bank-api-documentation) - [Wallet Account | Choice Bank - API Documentation](#wallet-account-choice-bank-api-documentation) - [Overview | Choice Bank - API Documentation](#overview-choice-bank-api-documentation) - [Deposit from M-PESA | Choice Bank - API Documentation](#deposit-from-m-pesa-choice-bank-api-documentation) - [Deposit from Banks | Choice Bank - API Documentation](#deposit-from-banks-choice-bank-api-documentation) - [SME Account | Choice Bank - API Documentation](#sme-account-choice-bank-api-documentation) - [Account Management | Choice Bank - API Documentation](#account-management-choice-bank-api-documentation) - [International Transfer (SWIFT) | Choice Bank - API Documentation](#international-transfer-swift-choice-bank-api-documentation) - [General Transfer | Choice Bank - API Documentation](#general-transfer-choice-bank-api-documentation) - [Bulk Transfer | Choice Bank - API Documentation](#bulk-transfer-choice-bank-api-documentation) - [Foreign Exchange | Choice Bank - API Documentation](#foreign-exchange-choice-bank-api-documentation) - [Bank Transfer (RTGS/EFT) | Choice Bank - API Documentation](#bank-transfer-rtgs-eft-choice-bank-api-documentation) - [Utility Payment | Choice Bank - API Documentation](#utility-payment-choice-bank-api-documentation) - [New Features | Choice Bank - API Documentation](#new-features-choice-bank-api-documentation) - [M-PESA PayBill / BuyGoods | Choice Bank - API Documentation](#m-pesa-paybill-buygoods-choice-bank-api-documentation) - [Confirm OTP | Choice Bank - API Documentation](#confirm-otp-choice-bank-api-documentation) - [Merchant | Choice Bank - API Documentation](#merchant-choice-bank-api-documentation) - [Get Enumerations | Choice Bank - API Documentation](#get-enumerations-choice-bank-api-documentation) - [Close Sandbox Account | Choice Bank - API Documentation](#close-sandbox-account-choice-bank-api-documentation) - [Callback and IP Whitelisting | Choice Bank - API Documentation](#callback-and-ip-whitelisting-choice-bank-api-documentation) - [Apply for multiple accounts | Choice Bank - API Documentation](#apply-for-multiple-accounts-choice-bank-api-documentation) - [Const | Choice Bank - API Documentation](#const-choice-bank-api-documentation) - [Closing individual account | Choice Bank - API Documentation](#closing-individual-account-choice-bank-api-documentation) - [Upgrade wallet to current account | Choice Bank - API Documentation](#upgrade-wallet-to-current-account-choice-bank-api-documentation) - [Onboarding | Choice Bank - API Documentation](#onboarding-choice-bank-api-documentation) - [Cancel Account Operation | Choice Bank - API Documentation](#cancel-account-operation-choice-bank-api-documentation) - [Query Business Onboarding Request ID | Choice Bank - API Documentation](#query-business-onboarding-request-id-choice-bank-api-documentation) - [Onboarding | Choice Bank - API Documentation](#onboarding-choice-bank-api-documentation) - [Pull transactions | Choice Bank - API Documentation](#pull-transactions-choice-bank-api-documentation) - [Account Statement API | Choice Bank - API Documentation](#account-statement-api-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [Apply for FX v2 | Choice Bank - API Documentation](#apply-for-fx-v2-choice-bank-api-documentation) - [Query Account Manager/Administrator List | Choice Bank - API Documentation](#query-account-manager-administrator-list-choice-bank-api-documentation) - [Apply for multiple accounts | Choice Bank - API Documentation](#apply-for-multiple-accounts-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [Apply for M-PESA B2B Transfer v2 | Choice Bank - API Documentation](#apply-for-m-pesa-b2b-transfer-v2-choice-bank-api-documentation) - [Account Administrator | Choice Bank - API Documentation](#account-administrator-choice-bank-api-documentation) - [Query joint account information | Choice Bank - API Documentation](#query-joint-account-information-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [API Reference | Choice Bank - API Documentation](#api-reference-choice-bank-api-documentation) - [Apply for outbound external payment channel (RTGS, EFT) | Choice Bank - API Documentation](#apply-for-outbound-external-payment-channel-rtgs-eft-choice-bank-api-documentation) - [Open a Joint Account | Choice Bank - API Documentation](#open-a-joint-account-choice-bank-api-documentation) - [Apply for inbound external payment channel (RTGS, EFT) | Choice Bank - API Documentation](#apply-for-inbound-external-payment-channel-rtgs-eft-choice-bank-api-documentation) - [IMT Transfers | Choice Bank - API Documentation](#imt-transfers-choice-bank-api-documentation) - [Onboarding | Choice Bank - API Documentation](#onboarding-choice-bank-api-documentation) - [Deposit from M-PESA | Choice Bank - API Documentation](#deposit-from-m-pesa-choice-bank-api-documentation) - [Confirm OTP | Choice Bank - API Documentation](#confirm-otp-choice-bank-api-documentation) - [Callback and IP Whitelisting | Choice Bank - API Documentation](#callback-and-ip-whitelisting-choice-bank-api-documentation) --- # Overview | Choice Bank - API Documentation ![Page cover](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252F3D1dFZp9bGj1k3WqpBvH%252Fbanner.PNG%3Falt%3Dmedia%26token%3D037ff4b0-dce9-46da-9af2-9ea205776148&width=1248&dpr=4&quality=100&sign=1cfb2a49&sv=2) [](https://choice-bank.gitbook.io/choice-bank#introduction) 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. [](https://choice-bank.gitbook.io/choice-bank#getting-started) Getting started ----------------------------------------------------------------------------------- ### [](https://choice-bank.gitbook.io/choice-bank#develop-your-frontend-and-backend) 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. ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FKNftYesVN2TWtfyox1G4%252Fimage.png%3Falt%3Dmedia%26token%3D7aa668a3-81f7-4a3f-9dfd-4792c5f75f20&width=768&dpr=4&quality=100&sign=25b4a4ad&sv=2) ### [](https://choice-bank.gitbook.io/choice-bank#get-your-private-key) 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. [](https://choice-bank.gitbook.io/choice-bank#message-template) 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. ### [](https://choice-bank.gitbook.io/choice-bank#request-message-template) Request Message Template Copy { "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](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication) string TRUE `params` Actual request parameters of the request. Different API requires different fields in params object. object TRUE ### [](https://choice-bank.gitbook.io/choice-bank#response-message-template) Response Message Template Copy { "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 `msg`field. 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](https://choice-bank.gitbook.io/choice-bank/getting-started/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 [](https://choice-bank.gitbook.io/choice-bank#terminologies) 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 1. M-PESA Paybill / Till-BuyGoods Shortcode Refers to the ​M-PESA-specific shortcodes allocated to businesses or merchants for facilitating mobile payments. 2. Choice-Allocated Collection Shortcode A ​proprietary 5-7 digits shortcode assigned by Choice to account numbers, enabling simplified and shortened identifiers for payment collections. [NextAuthentication](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication) Last updated 8 months ago --- # Authentication | Choice Bank - API Documentation To ensure the security and integrity of system communication, Choice BaaS API requires all request senders to sign the request message with their private key, and the Choice BaaS platform will verify the signature before processing.​ If the signature is invalid, the request will NOT be accepted. [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#sign-the-request) Sign the Request -------------------------------------------------------------------------------------------------------------------- After onboarding, a private key can be obtained from your account manager and every request you make should be signed with it. The signing algorithm is described below: 1. Fill the salt into the request JSON object with `salt` field name. 2. Fill the private key into the request JSON object with `senderKey` field name. 3. Convert the key-value pair of the request JSON object into string with alphabetical sorting. When converting, make the key-value pair as `string=string` and join them with `&`. 4. Hash the converted string which got in step 1 with SHA-256 and the private key then fill the hashed string back to the request JSON with field name - `signature`. 5. Remove the `senderKey` field from request JSON object. ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#example) Example The original request JSON object is: Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "params": { "name": "Tester" } } 1 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#generate-salt) Generate Salt Generate the salt randomly and fill it into the request JSON object Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "params": { "name": "Tester" } } 2 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#private-key) Private Key Fill the private key into the JSON object Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "senderKey": "yourkey", "params": { "name": "Tester" } } 3 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#convert-json-to-string) Convert JSON to String Flatten the JSON object to string. * ​**ASCII Order**: Sorted by raw byte values (e.g., `A` (65) before `a` (97)). * ​**Joined with** `**&**`: Uses `&` as the delimiter between sorted key-value pairs. JSON Object Flat String Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "senderKey": "yourkey", "params": { "name": "Tester" } } locale=en\_ke¶ms.name=Tester&requestId=APPREQ00990320fed02000&salt=QcEwsZ123da&sender=client1&senderKey=yourKey×tamp=1650533105687 4 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#hash-the-string) Hash the string Hash the converted string with SHA-256 and fill the hashed into the field `signature` Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "senderKey": "yourkey", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "params": { "name": "Tester" } } 5 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#remove-senderkey) Remove senderKey Remove the field senderKey from the request JSON object. Then you get the final request JSON object and send out. Copy { "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "params": { "name": "Tester" } } [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#verify-signature) Verify Signature -------------------------------------------------------------------------------------------------------------------- To verify the signature of the response from Choice BaaS 1. Fill the private key into the response JSON with field name `senderKey`. 2. Remove the field `signature` field from the response JSON. **NOTES:** Please do remember to keep the value of the signature field of the response for comparison later. 1. Convert the modified response JSON to string with alphabetical sorting. 2. Hash the string converted from response JSON in step 3. 3. Compare the hash result from step 4 to the signature of the original response. ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#example-1) Example The original response JSON object: Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "choice.baas", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "data": { "accountId": "46012123456789" } } 1 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#private-key-1) Private Key Fill your private key to the field `senderKey` Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "choice.baas", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "senderKey": "yourKey", "data": { "accountId": "46012123456789" } } 2 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#remove-signature) Remove Signature Remove the field `signature` field from the response JSON. Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "choice.baas", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "senderKey": "yourKey", "data": { "accountId": "46012123456789" } } 3 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#convert-json-to-string-1) Convert JSON to String JSON Object Converted String Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "choice.baas", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "senderKey": "yourKey", "data": { "accountId": "46012123456789" } } "code=00000&data.accountId=46012123456789&locale=en\_ke&msg=Completed successfully&requestId=APPREQ00990320fed02000&salt=QcEwsZ123da&sender=choice.baas&senderKey=yourKey×temp=1650533105687" 4 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#hash-the-converted-string) Hash the converted string Hash the converted string with SHA-256 5 ### [](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#compare-signatures) Compare Signatures Compare the signature that 1. from the original response 2. from the hashed converted string. If the two are the same, then the response is valid, otherwise, it's invalid. [PreviousOverview](https://choice-bank.gitbook.io/choice-bank) [NextSandbox Environment](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment) Last updated 25 days ago --- # Sandbox Environment | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment#url) URL ----------------------------------------------------------------------------------------------- [https://baas-pilot.choicebankapi.com/](https://baas-pilot.choicebankapi.com/) [](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment#private-key-sandbox) Private Key - Sandbox --------------------------------------------------------------------------------------------------------------------------------- Get the private key for sandbox environment from your account manager. [PreviousAuthentication](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication) [NextClose Sandbox Account](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment/close-sandbox-account) Last updated 8 months ago --- # Current Account | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/current-account#steps) Steps --------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/account/current-account#initiate-onboarding-request) Initiate Onboarding Request Call endpoint `/onboarding/submitOnboardingRequest` to initiate an onboarding request submit the text information. 2 ### [](https://choice-bank.gitbook.io/choice-bank/account/current-account#submit-onboarding-documents) Submit Onboarding Documents Call endpoint `/onboarding/uploadMedia` to submit the onboarding documents. For the documents required for onboarding, please refer to the Documents table below After initiating the onboarding request, the onboarding documents have to be submitted within 30 mins, otherwise, the onboarding request expires. 3 ### [](https://choice-bank.gitbook.io/choice-bank/account/current-account#waiting-for-reviewing) Waiting for Reviewing The request status becomes `2-PROCESSING` . 4 ### [](https://choice-bank.gitbook.io/choice-bank/account/current-account#get-onboarding-result) Get Onboarding Result * Get it from `0001 - Personal Onboarding Result Notification` * Query the result by calling the endpoint `/onboarding/getOnboardingStatus` [](https://choice-bank.gitbook.io/choice-bank/account/current-account#status) Status ----------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FMwwD30mo87q6prS09Qds%252Fwhiteboard_exported_image%2520%281%29.png%3Falt%3Dmedia%26token%3Dce95d766-188e-4768-9857-a8ffac81c392&width=768&dpr=4&quality=100&sign=d311a7fb&sv=2) [](https://choice-bank.gitbook.io/choice-bank/account/current-account#documents) Documents ----------------------------------------------------------------------------------------------- File ID Description Supported File Type Required? KYCF00001 Front side photo of Kenya national ID jpg, jpeg Required when `idType == 101` KYCF00002 Back side photo of Kenya national ID jpg, jpeg Required when `idType == 101` KYCF00003 Photo of the Kenya passport jpg, jpeg Required when `idType == 103` KYCF00004 Front side photo of Kenya Alien ID jpg, jpeg Required when `idType == 102` KYCF00005 Back side photo of Kenya Alien ID jpg, jpeg Required when `idType == 102` KYCF00007 Selfie video mp4 Required [PreviousClose Sandbox Account](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment/close-sandbox-account) [NextOnboarding](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding) Last updated 22 days ago --- # Wallet Account | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#steps) Steps -------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#initiate-onboarding-request) Initiate Onboarding Request Call endpoint `/onboarding/v3/submitEasyOnboardingRequest` to initiate an onboarding request submit the text information. 2 ### [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP. Call endpoint `/common/confirmOperation` to confirm the OTP code received. The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#waiting-for-reviewing) Waiting for Reviewing The request status becomes `2-PROCESSING` . 4 ### [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#get-onboarding-result) Get Onboarding Result * Get it from `0001 - Personal Onboarding Result Notification` * Query the result by calling the endpoint `/onboarding/getOnboardingStatus` [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account#status) Status ---------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FMwwD30mo87q6prS09Qds%252Fwhiteboard_exported_image%2520%281%29.png%3Falt%3Dmedia%26token%3Dce95d766-188e-4768-9857-a8ffac81c392&width=768&dpr=4&quality=100&sign=d311a7fb&sv=2) [PreviousClosing individual account](https://choice-bank.gitbook.io/choice-bank/account/current-account/closing-individual-account) [NextOnboarding](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding) Last updated 22 days ago --- # Overview | Choice Bank - API Documentation Overview | Choice Bank - API Documentation --- # Deposit from M-PESA | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-m-pesa#stk-push-deposit) STK Push Deposit ----------------------------------------------------------------------------------------------------------------- `POST` `/trans/depositFromMpesa` In KES only and should be a whole number; decimals are not supported. **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that the money should be deposit to. TRUE `mobile` string The number of the mobile that is to make the transfer from (which will receive STK push and needs to input the PIN code) TRUE `amount` decimal Deposit amount (in **KES** only and should be a **whole number** as decimals are not supported) TRUE **Response** 00000 Copy { "txId": "" } [](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-m-pesa#paybill-deposit) Paybill Deposit --------------------------------------------------------------------------------------------------------------- Sandbox: make a transfer to Paybill Shortcode 4101847, and specify the number of the bank account that is to deposit to in the Account Number field in Mpesa App. Prod: make a transfer to Paybill Shortcode 444174, and specify the number of the bank account that is to deposit to in the Account Number field in Mpesa App. [PreviousAccount Statement API](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api) [NextDeposit from Banks](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-banks) Last updated 29 days ago --- # Deposit from Banks | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-banks#transfer-instructions) ​**Transfer Instructions** ------------------------------------------------------------------------------------------------------------------------------- ### [](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-banks#local-transfers-within-kenya) **​Local Transfers (Within Kenya)** * ​**Via Pesalink**: 1. Log in to your bank’s mobile app or internet banking. 2. Select ​**Pesalink** as the transfer method. 3. Select **Choice Microfinance Bank** and enter your ​**Account Number & Account Name**. 4. Input the amount and confirm the transaction. ### [](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-banks#international-transfers) **International Transfers** 1. Instruct your bank to initiate a ​**SWIFT transfer** using: * ​**SWIFT BIC**: `CHFIKENX` 2. Include your ​**Choice Account Number** and ​**Full Name** in the payment reference field. [PreviousDeposit from M-PESA](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-m-pesa) [NextGeneral Transfer](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer) Last updated 8 months ago --- # SME Account | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#background) Background --------------------------------------------------------------------------------------------- SME can open the SME Account in Choice Bank through BaaS API Platform. The following 5 types of organizations are eligible to open the SME Account: 1. **Sole Proprietorship** A sole proprietorship is a type of enterprise that is owned and run by one individual, with no distinction between the owner and the business entity. The owner is entitled to all profits and is responsible for all the business's debts, losses, and liabilities. 2. **Limited Liability Company** A limited liability company is a business structure that combines the pass-through taxation of a partnership or sole proprietorship with the limited liability of a corporation. Owners of an LLC are called members and are protected from personal liability for business debts and claims. 3. **Partnership Company** A partnership company is a business organization in which two or more individuals manage and operate a business in accordance with the terms and objectives set out in a Partnership Deed. Partners share profits and losses and are jointly and severally liable for the obligations of the partnership. 4. **NGO (Non-Governmental Organization)** A non-governmental organization is a non-profit group that operates independently of any government, typically one whose purpose is to address a social or political issue. NGOs play a critical role in developing society, improving communities, and promoting citizen participation. 5. **CBO (Community-Based Organization)** A community-based organization is a non-profit group that works at a local level to improve life for residents. These organizations are typically grassroots entities that are focused on community-based issues and are involved in activities that address the needs of the community. [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#steps) Steps ----------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#initiate-onboarding-request) Initiate Onboarding Request Call endpoint `/onboarding/business/applyForSmeOnboarding` to initiate an onboarding request. On initiation, end users will need to select their SME type and how they would like to receive the OTP (SMS or email). Status: `1-SUBMITTED` 2 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP (using onboardingRequestId received in the response in the first step). Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` If the OTP is not verified within 30 minutes of submission, the onboarding request will expire. 3 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#submit-onboarding-basic-information) Submit Onboarding Basic Information Based on the SME's `businessType`, call different endpoints to submit the basic information for onboarding. Onboardings for Different organizations require different information. * Sole Proprietorship - `/onboarding/business/submitStoreOnboardingRequest` * Limited Liability Company - `/onboarding/business/submitCompanyOnboardingRequest` * Partnership Company - `/onboarding/business/submitPartnershipOnboardingRequest` * NGO/CBO - `/onboarding/business/submitOrganisationOnboardingRequest` Status: `2-PROCESSING` 4 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#submit-onboarding-documents) Submit Onboarding Documents Call endpoint `/onboarding/uploadMedia` to submit the onboarding documents. Call endpoint `/onboarding/business/removeMedia` to remove the uploaded onboarding documents. For the documents required for onboarding, please refer to the table Documents below 5 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#submit-company-shareholders-directors-partners-information) Submit Company Shareholders/Directors/Partners Information Sole Proprietorship type of company is not required to do this step. For Limited Liability Company, Partnership Company, NGO and CBO, the information of at least 2 shareholders/directors/partners need to be submitted. * Add Individual shareholder: `/onboarding/business/submitCompanyMember` * Add organization shareholder: `/onboarding/business/submitShareholderCompanyMember` * Remove shareholder: `/onboarding/business/removeMember` Status: `2-PROCESSING` 6 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#submit-the-request-for-reviewing) Submit the Request for Reviewing When all information & documents are submitted, call endpoint `/onboarding/submitOrPullBackRequest` to send this onboarding to Choice Bank's reviewing. Before it's sent for reviewing, end users' onboarding information can be edited by repeating step 3-5; After the request is sent for reviewing, the onboarding information can no longer be amended. In case end users find anything wrong about the onboarding information or materials and want to amend it, they can also pull back the request (by calling the same endpoint `/onboarding/business/submitOrPullBackRequest`) and re-edit. Status: `9-MANUAL_REVIEWING` Once the OTP has been confirmed, the onboarding request is in `2-PROCESSING` status. In this status, end users have 72 hours to complete steps 3-5 by submitting basic information, company documents and shareholder information. If the onboarding request is not sent to 9-MANUAL\_REVIEWING within 72 hours, it will expire. 7 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#waiting-for-reviewing) Waiting for Reviewing Status: `9 - MANUAL REVIEWING` End users can request pulling back the request and amend the onboarding information at this stage. 8 ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#get-onboarding-result) Get Onboarding Result * Get it from `0006 - SME Account Opening Result Notification` * Query the result by calling the endpoint * Sole Proprietorship: `/onboarding/business/getStoreOnboardingInfo` * Limited Liability Company: `/onboarding/business/getCompanyOnboardingInfo` * NGO/CBO: `/onboarding/business/getOrganisationOnboardingInfo` * Partnership Company: `/onboarding/business/getPartnershipOnboardingInfo` [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#status) Status ------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FMwwD30mo87q6prS09Qds%252Fwhiteboard_exported_image%2520%281%29.png%3Falt%3Dmedia%26token%3Dce95d766-188e-4768-9857-a8ffac81c392&width=768&dpr=4&quality=100&sign=d311a7fb&sv=2) [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#documents) Documents ------------------------------------------------------------------------------------------- ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#sole-proprietorship) Sole Proprietorship File ID Description Supported File Type Is Required KYCF00001 Front side photo of Kenya national ID jpg, jpeg TRUE KYCF00002 Back side photo of Kenya national ID jpg, jpeg TRUE KYCF00006 Selfie Photo jpg, jpeg TRUE KYCF00009 Photo of Kenya Personal KRA PIN Certificate pdf, jpg, jpeg TRUE KYCF00010 Photo or scan copy of Proprietor Business Certificate pdf, jpg, jpeg TRUE KYCF00029 Other document files pdf, jpg, jpeg FALSE ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#limited-liability-company) Limited Liability Company File ID Description File Type Required? KYCF00011 CR12 pdf, jpg, jpeg TRUE KYCF00012 CR2, CR1, CR8 - Memorandum of the Company pdf, jpg, jpeg FALSE KYCF00013 KRA Pin certificate of Company pdf, jpg, jpeg TRUE KYCF00014 Original Board Resolutions on company’s letter head pdf, jpg, jpeg TRUE KYCF00023 Ultimate beneficiary owners pdf, jpg, jpeg FALSE (unless unless one shareholder is a company) KYCF00024 Certificate of Incorparation pdf, jpg, jpeg TRUE KYCF00029 Other document files pdf, jpg, jpeg FALSE ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#partnership) Partnership File ID Description Supported File Type Is Required KYCF00013 KRA Pin certificate of Company pdf, jpg, jpeg FALSE KYCF00014 Original Board Resolutions on company’s letter head pdf, jpg, jpeg TRUE KYCF00016 Partnership Certificate of Registration pdf, jpg, jpeg TRUE KYCF00017 Certified Partnership Deed pdf, jpg, jpeg TRUE KYCF00029 Other document files pdf, jpg, jpeg FALSE ### [](https://choice-bank.gitbook.io/choice-bank/account/sme-account#ngo-cbo) NGO / CBO File ID Description Supported File Type Is Required KYCF00013 Photo or scan copy of KRA Pin certificate of the company pdf, jpg, jpeg TRUE KYCF00014 Photo or scan copy of Original Board Resolutions on company’s letter head pdf, jpg, jpeg TRUE KYCF00016 Certified Copy of Certificate of Registration/Exemption Certificate pdf, jpg, jpeg TRUE KYCF00018 Photo of scan copy of By-laws / constitutions pdf, jpg, jpeg TRUE KYCF00029 Other document files pdf, jpg, jpeg FALSE [PreviousUpgrade wallet to current account](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/upgrade-wallet-to-current-account) [NextOnboarding](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding) Last updated 3 days ago --- # Account Management | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/account-management#query-account-details) Query Account Details -------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getAccountDetails` **Parameters** Parameters Type Description Is Required `accountId` string The number of the account that you want to query the details of. TRUE **Response** 00000 Copy { "accountId": "", //string "accountName": "", //string "currency": "", //string "accountType": "", //refer to account type definition "shortCode": "", //account short code, "accountStatus": "", //int, 0 - Normal; 1 - Locked; 2 - Closed "createTime": "", //unix timestamp of account creation time "balance": "", //2 dp, eg 12.3 returns "12.30", 453 returns "453.00" "dormantStatus": "", //0-Normal; 1-Dormant "freezeStatus": "", //0-Normal; 1-Frozen } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#get-all-accounts-of-a-client) Get All Accounts of a Client ---------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/queryAccountListByUserId` **Parameters** Parameters Type Description Is Required `userId` string The unique string to identify the user in the BaaS partner system. TRUE **Response** 00000 Copy { "accounts": [\ {\ "accountId": "",\ "accountName": "",\ "currency": "",\ "accountType": "", \ //C001-Current Account\ //C002-Wallet Account\ //C004-Loan Account\ //C006-Fixed Deposit Account\ //B001-SME Account\ //B005-Business Loan Account\ //B006-Business Fixed Deposit Account\ "dormantStatus": "", //0-Normal; 1-Dormant;\ "freezeStatus": "", //0-Normal; 1-Frozen;\ }\ ] } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#get-abnormal-account-list) Get Abnormal Account List ---------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getAbnormalAccountList` **Parameters** Parameters Type Description Is Required `pageNo` int Page number TRUE `pageSize` int Page size TRUE **Response** 00000 Copy { "total": "", "resultArray": [\ {\ "userId": "",\ "accountId": "",\ "accountType": "",\ "status": [\ {1},\ {2},\ //Abnormal status; 1-Dormant; 2-Restricted; 3-Frozen\ ]\ }\ ] } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#apply-for-short-code) Apply for Short Code ------------------------------------------------------------------------------------------------------------------------ `POST` `/account/applyForShortCode` **Parameters** Parameters Type Description Is Required `accountId` string The number of the account that the end user wants to apply for shortcode for. TRUE **Response** 00000 Copy { "accountId": "", "shortCode": "", //generated shortcode } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#query-shortcode-by-accountid) Query Shortcode By AccountId ---------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/queryForShortCode` **Parameters** Parameters Type Description Is Required `accountId` string The number of the account that the end user wants to query its short code. TRUE **Response** 00000 Copy { "accountId": "", "shortCode": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#query-accountid-by-shortcode) Query AccountId By Shortcode ---------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/queryAccountByShortCode` **Parameters** Parameters Type Description Is Required `shortCode` string The shortcode of the account that the end user wants to query its account number. TRUE **Response** 00000 Copy { "accountId": "", "shortCode": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#activate-dormant-account) Activate Dormant Account -------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/activateAccount` **Parameters** Parameters Type Description Is Required `accountId` string The number of the dormant account that the user wants to activate. TRUE **Response** 00000 Copy { "accountId": "", "shortCode": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#add-email) Add Email -------------------------------------------------------------------------------------------------- `POST` `/user/addOrUpdateEmail` **Parameters** Parameters Type Description Is Required `onboardType` string personal business TRUE `personalIdType` string This parameter is only required when `onboardType` == personal 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport FALSE `documentNumber` string The ID number for personal customer, or the business certificate number TRUE `email` string Email address TRUE **Response** 00000 Copy { "applicationId": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#phone-number-change-v2) Phone Number Change v2 ---------------------------------------------------------------------------------------------------------------------------- This endpoint allows users to change their registered phone number with the bank. A customer (business or individual) can attempt to request a change of the mobile number only three times in a day (both failed and success attempts) Note: Only verified Mobile can be used to receive OTP for payments/operations. If the user needs to verify their Mobile number, `/account/verifyEmailOrMobile` has to be called `POST` `/account/v2/mobileChange` Fields Type Description Required `accountId` string Account number TRUE `newMobileCountryCode` string New mobile country code TRUE `newMobileNumber` string New mobile umber TRUE **Response** 00000 Copy { "applicationId": "", //requestId returned by the baas api. } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#confirm-phone-number-change) Confirm Phone Number Change -------------------------------------------------------------------------------------------------------------------------------------- This is to help users confirm/validate their request to change to a new mobile number `POST` `/account/confirmMobileChange` Request Parameters Fields Type Description Required? `requestId` String Request ID generated by the phone number change request TRUE `ProveIdCode` String The OTP sent to the previous phone number(the number you're changing from) TRUE `confirmChangeCode` String The code sent to the new designated mobile number(the number you're changing to) TRUE Response Data: There is no return field in the response data. Please check the return code of the response. A return code of "00000" indicates the request is processed successfully, otherwise, please refer to the [error code specification](https://n05mxbyps1.feishu.cn/sheets/shtcntKB4yIErO5rOLACgMxv1Fe) . [](https://choice-bank.gitbook.io/choice-bank/account/account-management#verify-email-address) Verify Email Address ------------------------------------------------------------------------------------------------------------------------ `POST` `/user/verifyEmailAddress` **Parameters** Parameters Type Description Is Required `onboardType` string personal business TRUE `personalIdType` string This parameter is only required when `onboardType` == personal 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport FALSE `documentNumber` string The ID number for personal customer, or the business certificate number TRUE **Response** 00000 Copy { "applicationId": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#verify-email-or-mobile) Verify Email or Mobile ---------------------------------------------------------------------------------------------------------------------------- `POST` `/user/verifyEmailOrMobile` This endpoint is used to verify mobile and email of customers. Verified mobile/email will be used to receive OTP to authorize transactions and account operations. **Parameters** Parameters Type Description Is Required `onboardType` string personal business TRUE `personalIdType` integer 101 for National ID 102 for Alien ID 103 for Passport TRUE `documentNumber` string The ID number for personal customer, or the business certificate number TRUE `verifyType` string mobile email TRUE **Response** 00000 Copy { "applicationId": "", } [](https://choice-bank.gitbook.io/choice-bank/account/account-management#edit-sme-sub-account-va-name) Edit SME Sub-Account/VA Name ---------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/editSubAccountName` **NOTE:** * The **Business Name** is always used as a fixed prefix in the final account name. * If `subAccountName` is not provided in the request, the final account name will default to just the business name. * This endpoint helps SMEs manage and distinguish between multiple virtual accounts more intuitively. * The final account name must not exceed **255 characters** in total length. **Parameters** Parameters Type Description Required? `accountId` string Account number. Must belong to the SME customer. TRUE `subAccountName` string The sub-account name to be appended to the SME’s business name. By default, SME's sub-account/virtual account's name is the same as its Business Name. To customize it, this field can be provided and will be appended to the Business Name using an underscore \_. Example: **Business Name:** Choice Microfinance Bank **subAccountName**: ABC Company **Final Account Name:** Choice Microfinance Bank\_ABC Company If no value is passed, the sub-account name will be reset to match the Business Name only. FALSE **Response** 00000 Copy { "applicationId": "", } [PreviousQuery Account Manager/Administrator List](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-account-manager-administrator-list) [NextAccount Statement API](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api) Last updated 17 days ago --- # International Transfer (SWIFT) | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#scope) Scope ----------------------------------------------------------------------------------------------------- This applies to scenarios where end users are making a transfer to: 1. Other Cross-border Bank Accounts [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#steps) Steps ----------------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#initiate-transfer-request) Initiate Transfer Request Call endpoint `/trans/telegraphicTransfer` to initiate a transfer request Status: `1-SUBMITTED` 2 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `applicationId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-VALIDATING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#bank-validating) Bank Validating Status: `3-APPROVED` or `4-REJECTED` 4 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#bank-processing) Bank Processing Status: `6-IN_TRANSIT` 5 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#get-onboarding-result) Get Onboarding Result * Get it from `0023 - Inter-Bank Fund Transfer Result Notification` * Query transaction status by calling the endpoint `/trans/getInterBankTransferDetails` [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift#status) Status ------------------------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FfKKbGDusvAGijirSKe6q%252FSWIFT.jpg%3Falt%3Dmedia%26token%3Deed8b01b-1ea0-4a54-a38d-c3f929a68576&width=768&dpr=4&quality=100&sign=582aa91e&sv=2) [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft/api-reference) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift/api-reference) Last updated 7 months ago --- # General Transfer | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#scope) Scope ----------------------------------------------------------------------------------------- This applies to scenarios where end users are making a transfer to: 1. M-PESA Mobile Money 2. AIRTEL Mobile Money 3. Choice Bank Account 4. Pesalink Pesalink Transfer has following limitations: 1. Dometic banks only 2. KES currency only 3. Maximum KES 999,999 per transaction 4. Some counter banks restrict Pesalink service to business hours **Recommendations for Alternative Use Cases** 1. Large/Urgent Transfers → Prioritize RTGS for immediate, high-value settlements. 2. ​Cross-Border Payments → Utilize SWIFT or mobile money corridors (e.g., M-PESA Global). 3. ​After-Hours Transactions → Leverage M-PESA for 24/7 liquidity. 4. ​Bulk Corporate Payments → Integrate with bank APIs or dedicated bulk payment platforms. [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#steps) Steps ----------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#initiate-transfer-request) Initiate Transfer Request Call endpoint `/trans/v2/applyForTransfer` to initiate a transfer request Status: `1-SUBMITTED` 2 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `txId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#transaction-processing) Transaction Processing Status: `2-PROCESSING` 4 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#get-onboarding-result) Get Onboarding Result * Get it from `0002 - Transaction Result Notification` * Query transaction status by calling the endpoint `/query/getTransResult` [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer#status) Status ------------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252F8NKpTjUxYOeDc9S6ZPF5%252FGENERAL_TRANSFER.jpg%3Falt%3Dmedia%26token%3Ddf2ae789-d117-42fd-9894-069d0b530e53&width=768&dpr=4&quality=100&sign=fa057141&sv=2) [PreviousDeposit from Banks](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-banks) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer/api-reference) Last updated 2 months ago --- # Bulk Transfer | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#scope) Scope -------------------------------------------------------------------------------------- This applies to scenarios where end users are making a bulk transfer to: 1. M-PESA Mobile Money 2. AIRTEL Mobile Money 3. Choice Bank Account 4. Pesalink 5. M-PESA Paybill 6. M-PESA Pay Till/BuyGoods A maximum of 500 transactions per request to be processed [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#steps) Steps -------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#initiate-bulk-transfer-request) Initiate Bulk Transfer Request Call endpoint `/trans/v2/generalBulkTransfer` to initiate a transfer request 2 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `bulkPaymentOrderId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#transaction-processing) Transaction Processing 4 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer#get-onboarding-result) Get Onboarding Result * Get it from `0008 - Bulk Transfer Result Notification` * Query transaction status by calling the endpoint `/trans/queryBatchTransactionResult` [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift/api-reference) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer/api-reference) Last updated 22 days ago --- # Foreign Exchange | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#scope) Scope ----------------------------------------------------------------------------------------- This applies to scenarios where end users are making an exchange: 1. From foreign currency (USD/GBP/EUR/CNY/TZS/UGX/RWF) to KES 2. From KES to foreign currency (USD/GBP/EUR/CNY/TZS/UGX/RWF) [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#steps) Steps ----------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#query-live-fx-rate) Query Live FX rate Call endpoint `/query/v2/getForeignExchangeRate` to initiate a transfer request 2 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#initiate-fx-request) Initiate FX Request Call endpoint `/trans/v2/applyForFcExchange` to initiate a transfer request Status: `1-SUBMITTED` 3 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `applicationId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 4 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#processing) Processing Status: `2-PROCESSING` 5 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#get-onboarding-result) Get Onboarding Result * Get it from `0013 - Foreign Exchange Result Notification` * Query transaction status by calling the endpoint `/query/v2/getFxRequestStatus` [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange#status) Status ------------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FgWho9eOM9Nxith8HmAdn%252FFX.jpg%3Falt%3Dmedia%26token%3D621e567b-164a-4b37-829a-841229a7d14d&width=768&dpr=4&quality=100&sign=a4468f27&sv=2) [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer/api-reference) [NextApply for FX v2](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange/apply-for-fx-v2) Last updated 4 days ago --- # Bank Transfer (RTGS/EFT) | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#scope) Scope ----------------------------------------------------------------------------------------------- This applies to scenarios where end users are making a transfer to: 1. Other Domestic (Kenya) Bank Accounts via RTGS 2. Other Domestic (Kenya) Bank Accounts via EFT **Under what circumstances should end users use RTGS/EFT instead of Pesalink for bank transfer?** Use Case Why RTGS / EFT Single transfer exceeding KES 999,999 RTGS: No upper limit (or limits up to ​KES 100 million), with ​real-time irrevocable settlement. EFT: Supports batch processing for large volumes, albeit with delayed settlement (e.g., T+1) B2B payments requiring invoice references, contract IDs, or audit trails * Pesalink lacks metadata support, complicating reconciliation. * RTGS/EFT provide ​detailed transaction records and comply with corporate governance standards. * Recipient banks not integrated with Pesalink. * Corporate accounts barred from using Pesalink (common in B2B contexts) RTGS/EFT are universally accepted across Kenyan banks, regardless of Pesalink participation ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#rtgs-vs.-eft) RTGS vs. EFT Scenario Recommended Channel Rationale Urgent, high-value (>KES 5M) RTGS Real-time, no cap, and irreversible settlement. Non-urgent bulk corporate EFT Lower fees, batch processing, but delayed settlement (T+1). [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#steps) Steps ----------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#initiate-transfer-request) Initiate Transfer Request Call endpoint `/trans/largeDomesticInterBankTransfer` to initiate a transfer request Status: `1-SUBMITTED` 2 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `applicationId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-VALIDATING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#bank-validating) Bank Validating Status: `3-APPROVED` or `4-REJECTED` 4 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#bank-processing) Bank Processing Status: `6-IN_TRANSIT` 5 ### [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#get-onboarding-result) Get Onboarding Result * Get it from `0023 - Inter-Bank Fund Transfer Result Notification` * Query transaction status by calling the endpoint `/trans/getInterBankTransferDetails` [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft#status) Status ------------------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FNfU5AT44LWt417pWYwuK%252FRTGS_EFT.jpg%3Falt%3Dmedia%26token%3D55ad6f65-fb70-4726-b930-860b2947d3d2&width=768&dpr=4&quality=100&sign=27fc5cf&sv=2) [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer/api-reference) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft/api-reference) Last updated 7 months ago --- # Utility Payment | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#scope) Scope --------------------------------------------------------------------------------------- This applies to scenarios where end users are making: 1. Utility bill payments 2. Airtime purchases [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#steps-airtime-purchase) Steps - Airtime Purchase --------------------------------------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#initiate-airtime-purchase-request) Initiate Airtime Purchase Request Call endpoint `/utilityPayment/v2/airtimePayment` to initiate an airtime purchase request Status: `1-Waiting` 2 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `paymentId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#payment-processing) Payment Processing Status: `2-PROCESSING` 4 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#get-payment-result) Get Payment Result * Get it from `0007 - Utility Payment Result Notification` * Query transaction status by calling the endpoint `/utilityPayment/paymentQuery` [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#steps-bulk-airtime-purchase) Steps - Bulk Airtime Purchase ------------------------------------------------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#initiate-bulk-airtime-purchase-request) Initiate Bulk Airtime Purchase Request Call endpoint `/utilityPayment/v2/airtimeBulkPayment` to initiate an airtime purchase request Status: `1-Waiting` 2 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#confirm-otp-1) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `bulkPaymentOrderId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#payment-processing-1) Payment Processing Status: `2-PROCESSING` 4 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#get-payment-result-1) Get Payment Result * Get it from `0014 - Bulk Airtime Purchase Notification` * Query transaction status by calling the endpoint `/utilityPayment/bulkPaymentQuery` [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#steps-utility-bill) Steps - Utility Bill ------------------------------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#query-utility-bill-due-information) Query Utility Bill Due Information Call endpoint `/utilityPayment/billQuery` to initiate an airtime purchase request 2 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#initiate-utility-bill-payment-request) Initiate Utility Bill Payment Request Call endpoint `/utilityPayment/v2/billPayment` to initiate an airtime purchase request Status: `1-Waiting` 3 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#confirm-otp-2) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `paymentId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 4 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#payment-processing-2) Payment Processing Status: `2-PROCESSING` 5 ### [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#get-payment-result-2) Get Payment Result * Get it from `0007 - Utility Payment Result Notification` * Query transaction status by calling the endpoint `/utilityPayment/paymentQuery` [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment#status) Status ----------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252F9eIVYZwTbhNpW7jZgDhL%252FUTILITY.jpg%3Falt%3Dmedia%26token%3De2528d54-714e-44bd-8ab2-b1ae885bf16d&width=768&dpr=4&quality=100&sign=cb2425a9&sv=2) [PreviousApply for M-PESA B2B Transfer v2](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/apply-for-m-pesa-b2b-transfer-v2) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference) Last updated 7 months ago --- # New Features | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/new-features#apply-for-transaction-reversal) Apply for Transaction Reversal --------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/txReversal` **Parameters** Parameters Type Description Is Required `transactionId` string The unique string generated by BaaS platform to identify a transaction. It has to be in the last 1 month. The transaction completed over 1 month ago cannot be reversed. TRUE `reversalReceiptNo` string If the transaction has been reversed already from third party institutions (i.e. M-PESA), end users should fill in the receipt number of the reversal transaction (The new transaction created to counter-effect the original one) FALSE `reversedTime` string If the transaction has been reversed already from third party institutions (i.e. M-PESA), end users should fill in the reversed time of the new reversal transaction FALSE `reversalReason` string Reversal reason FALSE `voucherBase64` string Voucher document FALSE `voucherType` string pdf image FALSE **Response** 00000 Copy { "applicationId": "", } [](https://choice-bank.gitbook.io/choice-bank/transfer/new-features#query-reversal-request) Query Reversal Request ----------------------------------------------------------------------------------------------------------------------- `POST` `/trans/queryTxReversal` **Parameters** Parameters Type Description Is Required `applicationId` string The unique string generated by BaaS platform to identify the application TRUE **Response** 00000 Copy { "applicationId": "", "transactionId": "", "reversalReceiptNo": "", "reversedTime": "", "reversalReason": "", "voucher": "", "status": "", "reversalTxId": "" } [](https://choice-bank.gitbook.io/choice-bank/transfer/new-features#validate-account-hakikisha) Validate Account (Hakikisha) --------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/validateAccount` Parameters Type Description Is Required `accountId` string The account/shortcode which the user wants to validate. This endpoint does return return "freezeStatus" and "restrictStatus" as well. TRUE `accountType` int The type of the counterparty account: 0 - **Choice Merchant** 1 - **M-PESA Paybill** 2 - **M-PESA Till** 3 - **Mpesa Mobile** 4 - **Pesalink Account Number** TRUE `bankCode` string (Mandatory if accountType is 4) The bankCode should be obtained from the choice bankcode through calling `/staticData/getBankCodes` Conditional **Response** 00000 Copy "data": { "accountType": "", //int, account type "accountId": "", //String, account Id "accountName": "", //String, return the account name if it's a valid accountId "freezeStatus":"", //freezeStatus: 0-normal; 1-frozen "restrictStatus":"",//restrict status 0-normal; 1-restrict in; 2-restrict out } [](https://choice-bank.gitbook.io/choice-bank/transfer/new-features#query-baas-channel-closing-balance) Query BaaS Channel Closing Balance ----------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/report/queryClosingBalance` **Parameters** Parameters Type Description Is Required `queryDate` string The UTC date that BaaS partner wants to query the closing balance on. TRUE **Response** 00000 Copy { "jobId": "", } **Result** Please refer to [0015-File Job Notification](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0015-account-statement-notification) [PreviousApply for FX v2](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange/apply-for-fx-v2) [NextCancel Account Operation](https://choice-bank.gitbook.io/choice-bank/transfer/new-features/cancel-account-operation) Last updated 15 days ago --- # M-PESA PayBill / BuyGoods | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#scope) Scope ----------------------------------------------------------------------------------------------- This applies to scenarios where end users are making a transfer to: 1. M-PESA Paybill 2. M-PESA Till/BuyGoods [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#steps) Steps ----------------------------------------------------------------------------------------------- 1 ### [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#initiate-transfer-request) Initiate Transfer Request Call endpoint `/trans/v2/applyForMpesaBusinessTransfer` to initiate a transfer request Status: `1-SUBMITTED` 2 ### [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#confirm-otp) Confirm OTP Call endpoint `/common/sendOtp` to request for OTP, filling the value of `txId` to `businessId` parameter. Call endpoint `/common/confirmOperation` to confirm the OTP code received. Status: `2-PROCESSING` The endpoint `/common/sendOtp` can also be used to resend OTP. 3 ### [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#transaction-processing) Transaction Processing Status: `2-PROCESSING` 4 ### [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#get-onboarding-result) Get Onboarding Result * Get it from `0002 - Transaction Result Notification` * Query transaction status by calling the endpoint `/query/getTransResult` [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods#status) Status ------------------------------------------------------------------------------------------------- ![](https://choice-bank.gitbook.io/choice-bank/~gitbook/image?url=https%3A%2F%2F1067423352-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZSBJA1E616k4RwaGxuZ2%252Fuploads%252FDSJM6b7HdAc9GohXrMzI%252FPAYBILL_BUYGOODS.jpg%3Falt%3Dmedia%26token%3D15f1b46f-d995-4eaf-a5ec-3a67d464292b&width=768&dpr=4&quality=100&sign=1c1cbdd9&sv=2) [PreviousPull transactions](https://choice-bank.gitbook.io/choice-bank/transfer/new-features/pull-transactions) [NextAPI Reference](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/api-reference) Last updated 7 months ago --- # Confirm OTP | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp#send-otp) Send OTP ------------------------------------------------------------------------------------- `POST` `/common/sendOtp` **Parameters** Parameters Type Description Is Required `businessId` string OnboardingID or Transaction Request ID TRUE `otpType` string sms email TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp#confirm-otp) Confirm OTP ------------------------------------------------------------------------------------------- `POST` `/common/confirmOperation` **Parameters** Parameters Type Description Is Required `businessId` string OnboardingID or Transaction Request ID TRUE `otpCode` string The received OTP code TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp#universal-resend-otp) Universal Resend OTP ------------------------------------------------------------------------------------------------------------- This api will support OTP resend capability operations for onboarding, accounts and transaction operations. You can use this endpoint to request the system to retry sending of OTP `POST` `/common/resendOtp` Fields Type Description Required? `businessId` String Onboarding or Transaction Request ID Mandatory `otpType` String sms or email Mandatory **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp#send-otp-sme-account-administrator) Send OTP - SME Account Administrator ------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/common/sendAccAdminOtp` **Parameters** Parameters Type Description Is Required `businessId` string The unique string generated by BaaS platform to identify the application TRUE `otpType` string sms email TRUE `accountId` string The number of the account that is to make the transfer TRUE `accManagerIdNumber` string The ID number of the account administrator TRUE `idType` string The ID type of the account administrator. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp#group-applications) Group Applications --------------------------------------------------------------------------------------------------------- `POST` `/common/groupApplications` **Parameters** Parameters Type Description Is Required `applicationIdList` array Array of string TRUE **Response** 00000 Copy { "applicationId": ""//The new application Id that can be used to confirm OTP } [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference) [NextMerchant](https://choice-bank.gitbook.io/choice-bank/others/merchant) Last updated 3 days ago --- # Merchant | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/others/merchant#request-for-merchant-bulk-transfer) Request for Merchant Bulk Transfer ----------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/batchTransitionalFundsDisbursement` This API is used by merchant accounts to disburse funds to Choice internal as well as external parties. All KES accounts of a whitelisted payment institution/service provider can be used for transitional fund settlement , and no OTP validation is required for transfers from that account to the beneficiaries, no matter which bank they are in. For this request to work, the partner requires to have requested for their merchant account \[payerAccountId\] to be whitelisted. If it is, then the subsequent verification is carried out, otherwise, the request will be rejected. **Parameters** Fields Type Description Required? `payerAccountId` string Allow merchant account onlyVerification: the merchant account must be associated with a Baas channel, otherwise the request will fail Mandatory `orgBatchId` string The unique batch ID generated by the merchant for this bulk payment request Optional beneficiaryArray array Array of the beneficiary details Mandatory Beneficiary Details/Array `orgTxId` string The unique transaction ID generated by the merchant for this specific transaction. Optional `payeeAccountName` string Payee account name Mandatory `payeeAccountId` string Payee account numberFor Mpesa paybill/paytill, its the shortcode number Mandatory `payeeBankCode` string Refer to [Choice BaaS Bank Code List](https://n05mxbyps1.feishu.cn/sheets/shtcnFyw3Kroc5tHUniyUaEptwf?sheet=5f853e) Kenya Bank Code and Wallet Entities tab. Mandatory `payeeType` string 0 for Individual 1 for business `payeeType` only be mandatory if `payeeBankCode` is M-PESA, otherwise it's optional. Conditional `payType` string 0 for paybill 1 for paytill Optional `payeeSubAccount` string For paybill cases Optional c`urrency` string Allow KES only for now Mandatory `amount` string Amount to be transferd Mandatory `remark` string Message to the beneficiary `payeeMobileForNotification` string The mobile number of the beneficiary of the sms notification to remind beneficiary of this inbound. Optional **Response** 00000 Copy { "orderId": "" } **Result** Please refer to [0004 - Merchant Bulk Fund Transfer Result Notification](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0004-merchant-bulk-fund-transfer-result-notification) [](https://choice-bank.gitbook.io/choice-bank/others/merchant#query-merchant-bulk-transfer-details) Query Merchant Bulk Transfer Details --------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/getInternalBatchTransactionResult` **Parameters** Parameters Type Description Is Required `orderId` string The orderId returned by Choice FALSE `orgBatchId` string The orgBatchId generated by BaaS Parnter. Either orderId or orgBatchId is mandatory. FALSE **Response** 00000 Copy { "orderId": "", "orgBatchId": "", "resultArray": [\ {\ "payeeAccountId": "",\ "payeeAccountName": "",\ "payerAccountId": "",\ "payerAccountName": "",\ "payeeBankCode": "",\ "orgTxId": "",\ "externalTxId": "",\ "payeeSubAccount": "",\ "paymentChannel": "",\ "payeeType": "",\ "currency": "",\ "amount": "",\ "txId": "",\ "txStatus": "",\ "failedReason": "",\ "completedTime": "",\ }, {}\ ] } [](https://choice-bank.gitbook.io/choice-bank/others/merchant#query-merchant-account-details) Query Merchant Account Details --------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getMerchantAccountDetails` **Parameters** Parameters Type Description Is Required `accountId` string Merchant account number TRUE **Response** 00000 Copy { "accountId": "", "accountName": "", "customerId": "", "currency": "", "accountType": "", "shortCode": "", "createTime": "", "balance": "", //available balance "frozenBalance": "", "dormantStatus": "", //0-Normal; 1-Dormant "abnormalStatus": "",//0-Normal; 1-Dormant; 2-Restricted; 3-Frozen "restrictStatus": "",//0-Normal; 1-Restrict In; 2-Restrict Out "freezeStatus": "", //0-Normal; 1-Frozen; } [PreviousConfirm OTP](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp) [NextIMT Transfers](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers) Last updated 28 days ago --- # Get Enumerations | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#current-account-onboarding-monthly-income-enumeration) Current Account Onboarding - Monthly Income Enumeration ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/staticData/getMonthlyIncomeEnumeration` **Parameters** Null **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "apigw.baas.choice", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "data": { "monthlyIncomeEnum": [\ {"id":"A", "text":"Less than 5000 ksh"},\ {"id":"B", "text":"5001 - 10000 ksh"},\ {"id":"C", "text":"10001 - 15000 ksh"},\ {"id":"D", "text":"15000 - 25000 ksh"},\ {"id":"E", "text":"Above 25000 ksh"} \ ] } } [](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#current-account-onboarding-employ-status-enumeration) Current Account Onboarding - Employ Status Enumeration ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/staticData/getEmploymentEnumeration` **Parameters** Null **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "apigw.baas.choice", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "data": { "employmentEnum": [\ {"id":"A", "text":"Employee"},\ {"id":"B", "text":"Self Employee"},\ {"id":"C", "text":"Unemployed"},\ {"id":"D", "text":"Employer"},\ {"id":"E", "text":"Student"},\ {"id":"F", "text":"Other"},\ ] } } [](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#bank-code-list) Bank Code List ----------------------------------------------------------------------------------------------------------- `POST` `/staticData/getBankCodes` **Parameters** Null **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "apigw.baas.choice", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11", "data": { "bankCodeList": [\ {"bankCode":"M-PESA", "bankName":"Mpesa"},\ {"bankCode":"CIC0001", "bankName":"TruuBank"},\ {"bankCode":"CIC0002", "bankName":"DigiTap"},\ {"bankCode":"CIC0003", "bankName":"TIFI"},\ {"bankCode":"01", "bankName":"Kenya Commercial Bank Limited "},\ {"bankCode":"46", "bankName":"Choice Microfinance Bank"},\ ] } } [](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#query-operational-bank-account-list) Query Operational Bank Account List ----------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/staticData/getOperationalAccounts` This is for customers to get a list of the Choice bank accounts held in other commercial bank for different deposit/transfer demands, like FX, RTGS, EFT transfers. **Parameters** Name Type Description Required? `type` wint 0 - Foreign Currency 1 - RTGS 2 - EFT TRUE **Response** 00000 Copy "data": { "operationalBankAccounts": [\ {\ "bank": "Kingdom Bank", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "51", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "5021805188004", //account no.\ "currency": "USD",\ "swiftCode": "CIFIKENA" //swiftCode \ },\ {\ "bank": "SBM Bank (Kenya) Limited", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "60", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "0322284570018", //account no.\ "currency": "USD",\ "swiftCode": "SBMKKENA" //swiftCode \ }, \ {\ "bank": "Diamond Trust Bank", //bank name\ "branch": "Karen", //branch\ "bankCode": "63", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "0217296003", //account no.\ "currency": "USD",\ "swiftCode": "DTKEKENA" //swiftCode\ }, \ {\ "bank": "Middle East Bank", //bank name\ "branch": "Karen", //branch\ "bankCode": "18", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "1003036000523", //account no.\ "currency": "USD",\ "swiftCode": "MIEKKENA" //swiftCode\ }, \ {\ "bank": "Equity Bank", //bank name\ "branch": "Kilimani", //branch\ "bankCode": "68", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "1450284300778", //account no.\ "currency": "USD",\ "swiftCode": "EQBLKENA" //swiftCode\ },\ {\ "bank": "Co-operative Bank of Kenya", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "11", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "02120214850701", //account no.\ "currency": "USD",\ "swiftCode": "KCOOKENA" //swiftCode\ }\ ] } [](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#get-foreign-currency-cooperation-bank-list) Get Foreign Currency Cooperation Bank List ------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/staticData/getFcyCooperativeBanks` This is for customers to get a list of the Choice bank accounts held in other commercial bank for different deposit/transfer demands, like FX, RTGS, EFT transfers. **No Request Parameters for this interface.** **Response** 00000 Copy "data": { "fcyCoopBanks": [\ {\ "bank": "Kingdom Bank", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "51", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "5021805188004", //account no.\ "currency": "USD",\ "swiftCode": "CIFIKENA" //swiftCode \ },\ {\ "bank": "SBM Bank (Kenya) Limited", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "60", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "0322284570018", //account no.\ "currency": "USD",\ "swiftCode": "SBMKKENA" //swiftCode \ }, \ {\ "bank": "Diamond Trust Bank", //bank name\ "branch": "Karen", //branch\ "bankCode": "63", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "0217296003", //account no.\ "currency": "USD",\ "swiftCode": "DTKEKENA" //swiftCode\ }, \ {\ "bank": "Middle East Bank", //bank name\ "branch": "Karen", //branch\ "bankCode": "18", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "1003036000523", //account no.\ "currency": "USD",\ "swiftCode": "MIEKKENA" //swiftCode\ }, \ {\ "bank": "Equity Bank", //bank name\ "branch": "Kilimani", //branch\ "bankCode": "68", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "1450284300778", //account no.\ "currency": "USD",\ "swiftCode": "EQBLKENA" //swiftCode\ },\ {\ "bank": "Co-operative Bank of Kenya", //bank name\ "branch": "Ongata Rongai", //branch\ "bankCode": "11", //bank code\ "accountName": "Choice Microfinance Bank", //account name\ "accountNo": "02120214850701", //account no.\ "currency": "USD",\ "swiftCode": "KCOOKENA" //swiftCode\ }\ ] } [PreviousCallback and IP Whitelisting](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting) [NextConst](https://choice-bank.gitbook.io/choice-bank/appendix/const) Last updated 29 days ago --- # Close Sandbox Account | Choice Bank - API Documentation `POST` `/account/closeSandBoxAccount` This endpoint is used in a sandbox environment to close test accounts. Occassioned by the need to frequently close and open accounts to test functionality, this endpoint is special in that: 1. OTP will NOT be required to validate the request. 2. Manual review is NOT required. The request will be executed automatically without user intervention The account closing result will be sent to you by call back notification. Please refer to - CallBack Definition. **Parameters** Parameters Type Description Is Required `accountId` string Account number TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [PreviousSandbox Environment](https://choice-bank.gitbook.io/choice-bank/getting-started/sandbox-environment) [NextCurrent Account](https://choice-bank.gitbook.io/choice-bank/account/current-account) Last updated 29 days ago --- # Callback and IP Whitelisting | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#convention) Convention -------------------------------------------------------------------------------------------------------------------- For notification of payments/onboarding results/other operation results, our API gateway communicates through callback to registered URL of the BaaS Channel. ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#template) **Template** Fields Description Data Type requestId Request ID String sender Sender ID of choice baas String notificationType Indicate the type of the notification. Please refer to the notication code definition. String 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 timestamp General parameter of the request body. The millisecond of UNIX time sending the request. Long salt String to obscure the signature for every single request. String signature Signature of the request. For method to sign the request message, please refer to [Authentication](https://choice-bank.gitbook.io/choice-bank/getting-started/authentication#sign-the-request) String params Actual request parameters of the notification. Please refer to the specific notification for details. Object ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#response-to-notification) Response to Notification Please return the string '**ok'** when you receive the callback. The notification callback will stop after it has been sent 5 times or after receiving the '**ok**' response. [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#notifications) Notifications -------------------------------------------------------------------------------------------------------------------------- ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0001-personal-onboarding-result-notification) 0001 - Personal Onboarding Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond "notificationType":"0001", //String, notification type "params": { "userId": "", //String, the unique string in your system to identify users "onboardingRequestId": "", //String, The onboarding request ID "status": , //Int, The onboarding status // 0 - Not Submit // 1 - Submitted // 2 - Processing // 3 - Passed // 4 - Rejected // 5 - Account Closed // 6 - Waiting for account opening // 7 - Account opened // 8 - Failed to open account. // 9 - Manual Reviewing "accountId":"", //String, it's returned when the onboarding is successful "accountType":"", //String, C001：current account，C002：wallet account "completeTime": , //Long, UTC Unix timestamp in millisecond when the onboarding completed "rejectionReasonIds": "", //String, code of the reject reason. "rejectionReasonMsgs": "" //String, message of the reject reason. }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0002-transaction-result-notification) 0002 - Transaction Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0002", //String, notification type "params": { "txId": "", "txType": "", "externalTxId": "", //External party(M-PESA/Pesalink) reference number "accountId": "", "accountName": "", "accountType": "", //C001-current account //C002-wallet account //B001-SME account //B002-Merchant account "oppoChannelId": "", "oppoSubAccount": "", //M-PESA Paybill's sub-account number "mpesaBusinessPayType": 1, //Int; 0-Paybill; 1-Till/BuyGoods>, "oppoAccountId": "", "oppoAccountName": "", "oppoBankName": "", "paymentChannel": "", "thirdPartyTxType": "", "currency": "", "amount": "", "feeAmount": "", //String, Transaction fee, 2 places decimal. "txStatus": 8, //Int, transaction status. "createTime": , //Long, Unix timestamp of the create time "updateTime": , //Long, Unix timestamp of the last update time "extInfo": { "counterpartyName": "", }, "errorCode": "", //String, error code "errorMsg": "", //String, error message }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0003-balance-change-notification) 0003 - Balance Change Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0003", //String, notification type "params": { "txId":"", "externalTxId":"", "userId":"", "accountId":"", "accountName":"", "txType":"", "oppoBankCode":"", "oppoAccountId":"", "oppoAccountName":"", "oppoSubAccount":"", "thirdPartyTxType":"", "mpesaBusinessPayType":0, //Int; 0-Paybill; 1-Till/BuyGoods> "currency":"", "amount":"", "feeAmount":"", //Transaction fee "balance":"", //Account balance after the transaction "completeTime":, //Long, UNIX timestamp of the transction complete time "extInfo": { "transactionNarrative":"", //String "oppoPhoneNumber":"", //String "counterpartyName": "", } }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0004-merchant-bulk-fund-transfer-result-notification) 0004 - Merchant Bulk Fund Transfer Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp":339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0004", //String, notification type "params": { "orderId":"", //String, order id generated by BaaS platform "orgBatchId": "", //String, order id generated by BaaS partner "resultArray": [ \ {\ "payerAccountId": "",\ "payerAccountName": "",\ "merchantTxId": "", //Transaction ID generated by BaaS partner\ "externalTxId": "", //External party (M-PESA/Pesalink) reference number\ "payeeBankCode": "",\ "payeeSubAccount": "",\ "paymentChannel": "",\ "payeeAccountId":"", //String, Payee account id\ "payeeAccountName":"", //String, Payee account name\ "payeeType":0, //Int; 0-Individual; 1-Business\ "currency":"", //String currency\ "amount":"", //String, transaction amount.\ "txId":"", //String, choice transaction ID\ "txStatus": , //Int, Transaction status. Please refer to the transaction status definition\ "failedReason":"", //String, failure reason.\ "completedTime": //Long, transactioncomplete time. In UTC Unix timestamp in millisecond.\ }, {}\ ] }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0005-wallet-account-upgrade-result-notification) 0005 - Wallet Account Upgrade Result Notification Copy { "requestId": "", //String, unique id of the notification generated by BaaS platform "sender": "", //String, sender id of BaaS platform "locale": "en_KE", //String, language config "timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType": "0005", //String, notification type "params": { "userId": "", //String, the unique ID of the user in BaaS partner's system "onboardingRequestId": "", //String, onboarding request ID "status": 7, //Integer, status of the onboarding. "accountId": "46123000000023", "accountType": "", //String, Account type //C001：current account //C002：wallet account "completeTime": 38276483274, //Long, request complete time. TC Unix timestamp in millisecond. "rejectionReasonIds": [], //Array of String, the rejected reason id. "rejectionReasonMsgs": [] //Array of String, reject reason description. }, "salt": "", //String, salt "signature": "" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0006-sme-account-opening-result-notification) 0006 - SME Account Opening Result Notification Copy { "requestId": "", //String, unique id of the notification generated by BaaS platform "sender": "", //String, sender id of BaaS platform "locale": "en_KE", //String, language config "timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType": "0006", //String, notification type "params": { "userId": "", //String, the unique ID of the user in your end. "onboardingRequestId": "", //String, onboarding request ID "status": 7, //Integer, onboarding status "accountId": "46123000000023", //String, account number will be returned when the onboarding is successful "accountType": "", //B001-SME account "completeTime": 38276483274, //Long, request complete time. TC Unix timestamp in millisecond. "rejectionReasonIds": [], //Array of String, the rejected reason id. "rejectionReasonMsgs": [], //Array of String, reject reason description. "otherReasons": "", //other reject reasons }, "salt": "", //String, salt "signature": "" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0007-utility-payment-result-notification) 0007 - Utility Payment Result Notification Copy { "requestId": "", //String, unique id of the notification generated by BaaS platform "sender": "", //String, sender id of BaaS platform "locale": "en_KE", //String, language config "timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType": "0007", //String, notification type "params": { "paymentId": "", //String, the payment ID "payServiceCategory": "", //String, payment type "subType": "", //String, utility payment vendor or airtime network "orderNo": "", //String, the bill ID, for airtime, it's the phone number "txId": "", //String, payment transaction ID "refundTxId": "", //String, refund transaction ID when the payment is failed. "amount": "", //String, amount "status": "", //String, payment status "errorCode": "",//String, error code "errorMsg": "" //String, error reason }, "salt": "", //String, salt "signature": "" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0008-bulk-transfer-result-notification) 0008 - Bulk Transfer Result Notification Copy { "requestId": "", //String, unique id of the notification generated by BaaS platform "sender": "", //String, sender id of BaaS platform "locale": "en_KE", //String, language config "timestamp": 339847598, //long, notification send time. UTC Unix timestamp in millisecond. "notificationType": "0008", //String, notification type "params": { "bulkPaymentOrderId": "", //String "payerAccountId": "", //String, payer account Id "txCount": "", //transfer count "resultArray":[\ {\ "txId": "", //Choice Transaction ID\ "txType": "", //String; B2C or B2B\ "benificiaryName": "", //Beneficiary Account Name\ "benificiaryAccount": "", //Beneficiary Account Id/Shortcode\ "benificiarySubAccount": "", //M-PESA paybill's account number\ "benificiaryBankCode": "", //Beneficiary bank code\ "paymentChannel": "", //String, \ "currency": "", //Currency\ "amount": "", //Transaction Amount\ "feeAmount": "", //Transaction Fee Amount\ "externalTxId" : "", //External transaction reference number\ "txStatus": 0, //Integer, Transaction Status\ "errorCode": "", //Error code\ "errorMsg": "", //Failure Reasion\ "completedTime": "" //Transaction completed time，UTC Time Stamp\ },\ {}, ....\ ] }, "salt": "", //String, salt "signature": "" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0012-multiple-account-opening-result-notification) 0012 - Multiple Account Opening Result Notification Copy { "requestId": "", //String, unique id of the notification generated by BaaS platform "sender": "", //String, sender id of BaaS platform "locale": "en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType": "0012", //String, notification type id "params": { "applicationId":"", //String, application Id "accountId":"", //String, account id of the newly open account "accountName":"", //String, account name "currency":"", //String, currency of the newly open account. "status": 3, //Int, status of the multiple account opening request. 3-successful; 4-failed "errorCode":"", //String, error code }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0013-foreign-exchange-result-notification) 0013 - Foreign Exchange Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0013", //String, notification type id "params": { "applicationId":"", //String, FX application id "kesAccountId":"", //String, local currency account id "fcAccountId":"", //String, foreign currency account id "outTxId":"", //String, debit transaction id "inTxId":"", //String, credit transaction id "currency":"", //String, currency code of the trading foreign currency "status":, //Int "amount":"", //String, exchange amount of the foreign currency "fxRate":"", //String, exchange rate "operation":"", //String, operation on the foreign currency, buy or sell "errorCode":"", //String, error code. "errorMsg":"" //String, error message. please refer to FCY error code }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0014-bulk-airtime-purchase-notification) 0014 - Bulk Airtime Purchase Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0014", //String, notification type id "params": { "bulkPaymentOrderId":"bulk payment id", "payerAccountId":"payer account id", "txCount":"number of the payment", "resultArray":[\ {\ "paymentId": "", //String, payment id\ "payServiceCategory": "", //String, pay service category\ "subType": "", //String, airtime network\ "orderNo": "", //String order id, for airtime, it's the phone number\ "txId": "", //String, Choice bank transaction id\ "refundTxId": "", //String, refund transaction id if payment fail\ "amount": "", //String, payment amount\ "status": "", //String, payment status\ "errorCode": "", //String, error code\ "errorMsg":"" //String, error message\ },{}\ ] }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0015-file-job-notification) 0015 - File Job Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0015", //String, notification type id "params": { "jobId":"jobId", //String, job id got when submit the job request. "fileUrl":"" //String, url to downloan the account statement }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0016-interest-disbursement-notification) 0016 - Interest Disbursement Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0016", //String, notification type id "params": { "date": "yyyy-mm-dd", //String, interest disbursing date "annualIr": "", //String, annual interest rate, 4 places decimal "interestDisbursementFequency": , //Integer, interest disbursement frequancy "endUserDisbursedInterest": "", //String, total interest disbursed to end user "endUserInterestTax": "", //String, tax of the interest of end user "partnerDisbursedInterest": "", //String, total interest disbursed to baas partner "partnerInterestTax": "", //String, tax of the interest of baas partner "partnerBeneficiaryAccount": "" //String, baas partner beneficiary account }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0019-account-closure-notification) 0019 - Account Closure Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0019", //String, notification type id "params": { "requestId": "", //String, the account closing request id. "accountId":"", //String, account number "completeTime":"", //String, complete time. "status":"", //String, 1-Account closed; 2-Request rejected "rejectionReason":"" //String, reject reason }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0021-account-status-change-notification) 0021 - Account Status Change Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0021", //String, notification type id "params": { "userId": "", //String "accountId":"", //String "type": 1, //Int; 1-freeze_status change; 2-dormant_status change "status": 1, //Int; 1-Unfrozen or Active; 2-Frozen or Dormant }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0022-merchant-balance-change-notification) 0022 - Merchant Balance Change Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0022", //String, notification type id "params": { "txId": "", "externalTxId": "", //External(Mpesa/Pesalink) reference number "accountId": "", "accountName": "", "txType": "", "oppoBankCode": "", "oppoAccountId": "", "oppoAccountName": "", "oppoSubAccount": "", //For M-PESA paybill scenario "thirdPartyTxType": "", "mpesaBusinessPayType": 0, //Int; 0-Paybill; 1-Till/BuyGoods "currency": "", "amount": "", "feeAmount": "", "balance": "", "completeTime": "", "extInfo": { "transactionNarrative": "", "oppoPhoneNumber": "", } }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0023-inter-bank-fund-transfer-result-notification) 0023 - Inter-bank Fund Transfer Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0023", //String, notification type id "params": { "applicationId": "", "type": "", //Domestic Fund Transfer or Cross-border Fund Transfer "debitAccountId": "", "debitAccountCcy": "", "beneficiaryBankName": "", "beneficiaryBankCode": "", "beneficiaryBranchCode": "", "beneficiaryAccountName": "", "beneficiaryAccountId": "", "beneficiaryAccountCurr": "", "requestAmtType": "", //Int; //0-In debit account currency; //1-In beneficiary account currency "requestAmount": "",//The transfer amount in "requestAmtType" currency "transferAmount": "", //The transfer amount in "debitAccountCcy" currency "bankCharge": "", // bank charge amount "debitAmount": "", //the total amount that the sender account was debited (including fee) "chargeType": "", //SHA, BEN or OUR "paymentChannel": "", //RTGS, EFT or SWIFT "txId": "", "refundTxId": "", //refund transaction ID when the payment fails "status": "", "createTime": "", "errorCode": "", "errorMsg": "", "exchangeRate": "", //If debitAccountCcy is different from beneficiaryAccountCurr //Choice automatically do exchange on behalf of end users }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0024-profile-check-result-notification) 0024 - Profile Check Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0024", //String, notification type id "params": { "profileCheckStatus": "", //Validated or Declined "onboardingRequestId":"", //String "resultCode": "", //Result code from Choice or Onboarding Vendor "resultDescription": "", //Description for the result code }, "salt":"", //String, salt "signature":"" //String, signature } ### [](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting#id-0025-fixed-deposit-result-notification) 0025 - Fixed Deposit Result Notification Copy { "requestId":"", //String, unique id of the notification generated by BaaS platform "sender":"", //String, sender id of BaaS platform "locale":"en_KE", //String, language config "timestamp": 339847598,//long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0025", //String, notification type id "params": { "applicationId": "", "depositAccountId":"", "completeTime": "", "status": "", //1-Submitted; 2-Processing; 3-Successful; 4-Failed "errorMessage": "", }, "salt":"", //String, salt "signature":"" //String, signature } [PreviousApply for outbound external payment channel (RTGS, EFT)](https://choice-bank.gitbook.io/choice-bank/others/merchant/apply-for-outbound-external-payment-channel-rtgs-eft) [NextGet Enumerations](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations) Last updated 7 months ago --- # Apply for multiple accounts | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/current-account/apply-for-multiple-accounts#apply-for-multiple-account) Apply for multiple account ------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/individualOpenAccount` **Parameters** Parameters Type Description Is Required `customerName` string End user name TRUE `idendityId` string The number of the ID that the end user used to onboard. TRUE `idType` string The type of the ID that the end user used to onboard. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `currency` string The currency of the new account that the end user wants to open. The following values are allowed: KES/USD/GBP/EUR/CNY/TZS/UGX/RWF TRUE **Response** 00000 Copy { "applicationId": "" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/apply-for-multiple-accounts#query-account-opening-request-status) Query account opening request status --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/getAccountOpeningStatus` **Parameters** Parameters Type Description Is Required `applicationId` string Account opening application ID TRUE **Response** 00000 Copy { "applicationId": "", "status": "", //1-Submitted; 2-OTP Confirmed; 3-Successful "accountId": "", //The number of the new account "accountName": "", "currency": "", } [PreviousOnboarding](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding) [NextClosing individual account](https://choice-bank.gitbook.io/choice-bank/account/current-account/closing-individual-account) Last updated 1 month ago --- # Const | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/appendix/const#account-type) Account Type -------------------------------------------------------------------------------------------- Value Description C001 Individual Current Account C002 Wallet Account C004 Individual Loan Account C006 Individual Fixed Deposit Account B001 SME Account B005 Business Loan Account B006 Business Fixed Deposit Account [](https://choice-bank.gitbook.io/choice-bank/appendix/const#transaction-type) Transaction Type ---------------------------------------------------------------------------------------------------- Transaction Type (txType) Description TTID0001 Withdraw to M-PESA TTID0002 Transfer Out TTID0003 Transfer In TTID0004 Interest Income TTID0005 M-PESA Paybill / Till TTID0006 Utility Payment TTID0007 Refund TTID0008 FCY Deposit TTID0009 FCY Transfer Out TTID0010 FCY Exchange TTID0011 Reversal TTID0023 Cash Deposit TTID0024 Cash Withdrawal [](https://choice-bank.gitbook.io/choice-bank/appendix/const#utility-payment-category) Utility Payment - Category ---------------------------------------------------------------------------------------------------------------------- Category Description 0 Airtime Purchase 3 Utility Bill [](https://choice-bank.gitbook.io/choice-bank/appendix/const#utility-payment-subtype) Utility Payment - SubType -------------------------------------------------------------------------------------------------------------------- Category SubType Description 0 0 SAFARICOM 0 1 AIRTEL 0 2 TELKOM 3 0 DSTV 3 1 GOTV 3 3 STARTIMES 3 6 WATER [](https://choice-bank.gitbook.io/choice-bank/appendix/const#media-file-id) Media - File ID ------------------------------------------------------------------------------------------------ File ID Description KYCF00001 Front side photo of Kenya national ID KYCF00002 Back side photo of Kenya national ID KYCF00004 Front side photo of Kenya Alien ID KYCF00005 Back side photo of Kenya Alien ID KYCF00003 Photo of the Kenya passport KYCF00006 Selfie photo KYCF00007 Selfie video KYCF00009 Photo of Kenya Personal KRA PIN Certificate KYCF00010 Photo or scan copy of Proprietor Business Certificate KYCF00011 Photo or scan copy of Company CR12 KYCF00012 Photo or scan copy of memorandum of the company KYCF00013 Photo or scan copy of KRA Pin certificate of the company KYCF00014 Photo or scan copy of Original Board Resolutions on company’s letter head KYCF00015 Photo or scan copy of Articles of Association of the company KYCF00016 Photo or scan copy of Certificate of Registration KYCF00017 Photo or scan copy of Certified partnership deed KYCF00018 Photo or scan copy of By-laws / constitutions KYCF00019 Photo or scan copy of Regulators License of the company KYCF00020 Photo or scan copy of Certified audit accounts / bank statement KYCF00021 Photo or scan copy of Business Permit KYCF00022 Photo or scan copy of Certified List of management commitee members KYCF00023 Photo or scan copy of Ultimate beneficiary owners KYCF00024 Photo or scan copy of Certificate of Incorporation KYCF00025 Photo or scan copy of Latest annual report KYCF00026 Photo or scan copy of AML policy / KYC procedure KYCF00027 Photo or scan copy of Election minutes of current signatories/directors KYCF00028 Photo or scan copy of Account opening form KYCF00029 Other document files KYCF00030 Photo or sacn copy of business CRB reports KYCF00031 Photo or scan copy of duly filled ground check/site visit form for business loan KYCF00032 Photo or scan copy of Business Mpesa statement KYCF00033 Photo or scan copy of Business Bank statements KYCF00034 Photo or scan copy of Joint account application form [](https://choice-bank.gitbook.io/choice-bank/appendix/const#payment-purpose) Payment Purpose -------------------------------------------------------------------------------------------------- Purpose ID Purpose Value Brief Description 512 National Industrial Training Authority National Industrial Training Authority 1001 Import Duty - Oil Import Duty - Oil 1002 Import Duty Import Duty 1101 Excise Duty - Oils Excise Duty - Oils 1102 Excise Duty Excise Duty 1201 VAT Oils VAT Oils 1202 VAT Imports VAT Imports 1206 VAT Oils - 8% VAT Oils - 8% 1501 Alteration Fee Alteration Fee 1518 Concession Fees Concession Fees 1519 Registration fees Registration fees 1527 Transhipment Fee Transhipment Fee 1801 IDF Fees (2.0%) IDF Fees (2.0%) 1802 IDF/PIF OIL IDF/PIF OIL 1908 Customs Warehouse Rent Customs Warehouse Rent 2101 Road Maintenance Levy (RML) Road Maintenance Levy (RML) 2301 Petroleum Regulatory Levy (PRL) Petroleum Regulatory Levy (PRL) 2501 Gross Payment-Petroleum Development Fund (PDF) Gross Payment-Petroleum Development Fund (PDF) 2901 Income Tax - PAYE Income Tax - PAYE 3001 Income Tax - Company Income Tax - Company 3100 Income Tax - Resident Individual Income Tax - Resident Individual 3101 Monthly Rental Income Tax Monthly Rental Income Tax 3103 Withholding Rental Income Withholding Rental Income 3200 Income Tax - Withholding Income Tax - Withholding 3304 Motor Vehicle Advance Tax Motor Vehicle Advance Tax 3509 VAT - Withholding VAT - Withholding 3514 Value Added Tax (VAT) Value Added Tax (VAT) 3801 Standards Levy Standards Levy 4103 Stamp Duty Stamp Duty 4301 State Department for Fisheries, Aquaculture and the Blue Economy State Department for Fisheries, Aquaculture and the Blue Economy 4601 Import Health Certificate Import Health Certificate 4702 Nuts and Oils Import Declaration Form Nuts and Oils Import Declaration Form 6001 Kenya Railway Development Levy (RDL) Kenya Railway Development Levy (RDL) 6002 Kenya Railway Development Levy (RDL)-Oils Kenya Railway Development Levy (RDL)-Oils 6101 Sale of single Number Plate Sale of single Number Plate 6102 Sale of pair of Number Plates Sale of pair of Number Plates 6301 Transfer Fees for Motor Vehicle Registration Transfer Fees for Motor Vehicle Registration 6401 Merchant Shipping Superintendent Levy Merchant Shipping Superintendent Levy 6402 Merchant Shipping Superintendent (MSS) Levy - Oils Merchant Shipping Superintendent (MSS) Levy - Oils 6501 Road Safety fund Road Safety fund 6601 SHMV purchase tax SHMV purchase tax ADTX Advance Tax This is a tax paid in advance before a public service vehicle or a commercial vehicle goes for the annual inspection. ARTX Agency Revenue This is a type of payment that KRA collects on behalf of various revenue collection agencies in Kenya. The two types of Agency Revenue include: Stamp Duty Betting and Pool Tax BTTX Betting Tax Betting Tax is chargeable on the gross gaming revenue (GGR) of a bookmaker at the rate of 15% as provided by Section 29A of the Betting, Lotteries and Gaming Act, 1966. CGTX Capital Gains Tax (CGT) This is a tax chargeable on the whole of a gain which accrues to a company or an individual upon transfer of property situated in Kenya, whether or not the property was acquired before 1st January, 2015. COTX Corporate Tax Identification This is a form of Income Tax that is levied on corporate bodies such as Limited companies, Trusts, and Co-operatives, on their annual income. EDTX Excise Duty This is a duty of excise imposed on goods manufactured in Kenya, or imported into Kenya and specified in the 1st schedule to Excise Duty Act, 2015. INTX Income Tax Income tax is a tax charged for each year of income, upon all the income of a person whether resident or non-resident, which is accrued in or was derived from Kenya. ISTX Installment Tax Installment tax is paid by persons who have tax payable for any year that amounts to Kshs. 40,000 and above. PAYE Pay As You Earn This is a method of collecting tax at source from individuals in gainful employment. Companies and Partnerships with employees are required to deduct tax according to the prevailing tax rates from their employees' salaries or wages on each payday for a month and remit the same to KRA on or before the 9th of the following month. RITX Rental Income Tax This is a tax charged on rental income received from renting out property. Taxation of rental income depends on how the rented property was used for residential or commercial purposes. SDTX Stamp Duty Stamp duty is a tax charged on transfer of properties, shares and stock. TAXR Tax Refund Transaction is the refund of a tax payment or obligation. TAXS Tax Payment Any other tax payments TOTX Turnover Tax Turnover Tax(TOT) is a tax charged on gross sales of a business as per Sec. 12(c) of the Income Tax Act. First introduced vide Finance Act 2006, replaced by Presumptive Income Tax vide Finance Act 2018 then reintroduced vide Finance Act 2019. TRAC Removed From Tracking Return following direct debit being removed from tracking process. VATX Value Added Tax Payment Value Added Tax is charged on supply of taxable goods or services made or provided in Kenya and on importation of taxable goods or services into Kenya. WHLD WithHolding This is a tax that is deductible from certain classes of income at the point of making a payment, to non-employees. SALA Salary Payment Transaction is the payment of salaries. SAVG Savings Transfer to savings/retirement account. OTHR Other Other payment purpose. LOAN Loan Account used for loans. INSU Insurance Premium Transaction is payment of an insurance premium. FOEX Foreign Exchange Foreign Exchange EDUC Education expenses Transaction is related to a payment of study/tuition fees. LICF License Fee Transaction is payment of a license fee. PENA Penalties Other related penalties AIRB Air transport Transaction is a payment for air transport related business. BUSB Bus Transaction is a payment for bus transport related business. CFR Cost and Freight Cost and Freight (sea and inland waterway transport) - Incoterms 2010 RLWY Railway Transaction is a payment for railway transport related business. SHIP Shipping Undertaking in support of a sea transportation obligation. TBIL Telecommunications Bill Transaction is related to a payment of telecommunications related bill and transfer payment of E-Value allocation/purchase/liquidation. HLTI Health Insurance Transaction is a payment of health insurance. INPC Insurance Premium Car Transaction is a payment of car insurance premium. LIFI Life Insurance Transaction is a payment of life insurance. PPTI Property Insurance Transaction is a payment of property insurance. VIPN Vehicle Identification Plate Number Account proxy for receiving insurance claims, pay insurance premium, road tax payments, traffic tickets etc.(applied for corporate or individual account proxy). INVS Investment And Securities Transaction is for the payment of mutual funds, investment products and shares GOVT Government Payment Transaction is a payment to or from a government department. ONCL Overnight Transaction is related to overnight clearing. INTE Interest Transaction is the payment of interest. REFU Refund Transaction is the payment of a refund. PL39 License Fees for Comms. Banks Licence Fees for Comm.Banks PL40 License Fees Deposit Micro. Institutions License Fees Deposit Micro. Institutions PL41 License Fees Forex Bureaus License Fees Forex Bureaus PL42 License Fees Credit Reference Bureaus License Fees Credit Reference Bureaus PL43 License Fees Mortgate Financial Institutions License Fees Mortgate Financial Institutions PL44 Application Fees For Commercial Banks Application Fees For Commercial Banks PL45 Application Fees For Mort.Fin.Institutions Application Fees For Mort.Fin.Institutions PL46 Application Fees Depo.Tak.Institutions Application Fees Depo.Tak.Institutions PL47 Application Fees Forex Bureaus Application Fees Forex Bureaus PL48 Application Fees Credit.Ref.Bureaus Application Fees Credit.Ref.Bureaus PL49 Penalties Commercial Banks Penalties Commercial Banks PL50 Penalties Mort.Fin.Institutions Penalties Mort.Fin.Institutions PL51 Penalties Deposit Taking Micro Institutions Penalties Deposit Taking Micro Institutions PL52 Penalties Forex Bureaus Penalties Forex Bureaus PL53 Penalties Credit Reference Bureaus Penalties Credit Reference Bureaus MDCS Medical Services Transaction is a payment for medical care services. MAFC Medical Aid Fund Contribution Transaction is contribution to medical aid fund. HLFD Purchase of food and household goods Transaction is for purchase of Food and Household goods BECH Child Benefit Transaction is related to a payment made to assist parent/guardian to maintain child. RENT Rent Transaction is the payment of rent. UBIL Utilities Transaction is for the payment to common utility provider that provide gas, water and/or electricity. CERE Ceremonies Ceremonies (Funeral expenses, graduation, wedding) RELG Religious activities Support religious activities/functions FARM Farming Farming expenses/Inputs CLOT Clothing Clothing expenses/Payments COMU Community Development Community Development activities CONS Construction Activities Construction of commercial and residential building expenses/activities MACH Machinery related Purchase of machinery and transport equipment FUEL Fuel expenses Purchase/Sale of fuel and related products. GOKX Government related Payments and Transfers Receipts and payments of transfers of Kenyan government CHC Charitable Contributions (Charity and Aid) Humanitarian aid, military assistance, contributions to international organization apart from loans, in cash or in kind, between the governments of different countries or between governments and international organizations VOST Vostro Payments Kenya Shilling Payments from cross border Banks to local Banks CSDK Central Security Depository Payments Central Security Depository Payments CUR/WIT CASH WITHDRAWALS CASH WITHDRAWALS CUR/DEP CASH DEPOSITS CASH DEPOSITS MSC Miscellenious Miscellenious BSD Banking Supervision Department Banking Supervision Department RPS COMESA PAYMENTS COMESA PAYMENTS [PreviousGet Enumerations](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations) Last updated 2 months ago --- # Closing individual account | Choice Bank - API Documentation `POST` `/account/closeIndividualAccount` Close individual (Baas Wallet/Baas Current) account; an OTP will be send to the customer to validate the request, then a Bank staff will manually review and Approve/Reject the request. The account closing result will be sent to you by call back notification. Please refer to - CallBack Definition. Highly recommended to go through the [AccountClosing Requirements](https://n05mxbyps1.feishu.cn/docx/H4vYdI2WhoejCtxwL9scNFk7n1b) before looking into the close account API. Fields Type Description Required? `accountId` String Account number TRUE `closureReason` String 1. I'm no longer using the account 2. Bank service - Dissatisfied with some aspects of choice's service 3. Platfom- Dissatisfied with some aspects of the software platforms, i.e User exxperince, system usability 4. Pricing- Dissatisfied with intrest or charges on my account 5. Policy - Dissatisfied with the rules around the product , i.e Onboarding, notice period, withdrawal policy 6. Moving away 7. Account holder circumstances have changed 8. Using funds 9. Similar account already held or opening a similar account with choice 10. Opened in error Note: You can submit multiple reasons TRUE `otpType` string sms email TRUE When the last account of the customer is closed, the onboarding request of that customer becomes ACCOUNT\_CLOSED. The customer has to submit fresh onboarding material when they request to open an account with Choice bank. If the account closed is not the last account of the customer, the customer does not need to submit fresh onboarding materials to open the account. **Response** 00000 Copy { "applicationId": "" } [PreviousApply for multiple accounts](https://choice-bank.gitbook.io/choice-bank/account/current-account/apply-for-multiple-accounts) [NextWallet Account](https://choice-bank.gitbook.io/choice-bank/account/wallet-account) Last updated 24 days ago --- # Upgrade wallet to current account | Choice Bank - API Documentation `POST` `/onboarding/walletAccountUpgrade` Supply the personal information and request to upgrade the wallet account to bank account. Fields Type Description Required? `userId` String User ID in your system. It should be the unique identity of the user in your system. Mandatory `kraPin` String KRA pin of the customer Mandatory `frontSidePhoto` String BASE64 text of the ID front side photo binary. Optional `backSidePhoto` String BASE64 text of the ID backside photo binary. Optional `passportPhoto` String Base64 text of photo of the passport. If wallet is on-boarded using a passport - this is the identification document to be submitted. Optional `selfiePhoto` String BASE64 text of the selfie photo binary. Mandatory **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [PreviousOnboarding](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding) [NextSME Account](https://choice-bank.gitbook.io/choice-bank/account/sme-account) Last updated 21 days ago --- # Onboarding | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#create-a-new-client) Create a new client ------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/submitOnboardingRequest` **Parameters** Parameters Type Description Is Required `userId` string A unique string to identify the user in the partner system. TRUE `firstName` string First name of the onboarding customer TRUE `middleName` string middle name of the onboarding customer FALSE `lastName` string last name of the onboarding customer TRUE `birthday` string Date of Birth; yyyy-MM-dd TRUE `address` string Physical address of the onboarding customer TRUE `gender` integer 0 - Female 1 - Male TRUE `countryCode` string The country code of the mobile, that the customer is using to onboard TRUE `mobile` string The mobile number that the customer is using to onboard TRUE `email` string Email address of the customer FALSE `idType` string Type of the document that the customer is using to onboard. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `idNumber` string ID Number of National ID/Passport/Alien ID TRUE `kraPin` string KRA PIN / Tax Number TRUE `employmentStatus` string Customer's work status. A - Employee B - Self employed C - Unemployed D - Employer E - Student F - Others TRUE `monthlyIncome` string Customer monthly income information. A - Less than Ksh. 14,999 B - Ksh. 15,000-24,999 C - Ksh. 25,000-39,999 D - Ksh. 40,000-59,999 E - Ksh. 60,000-84,999 F - Above Ksh. 85,000 TRUE `businessIndustry` string This field captures the industry the business is operating in. Please submit the number representing the business sector. 1 - Agriculture and Agribusiness 2 - Manufacturing and Processing 3 - Construction and Engineering 4 - Retail and Wholesale Trade 5 - Information and Communication Technology 6 - Tourism and Hospitality 7 - Health and Wellness Services 8 - Education and Training 9 - Financial Services 10 - Professional Services 11 - Creative Industries 12 - Renewable Energy and Environmental Conservation 13 - Transport and Logistics 14 - Food and Beverage 15 - Textiles and Apparel 16 - Automotive and Engineering Services 17 - Beauty and Personal Care 18 - Real Estate and Property Development 19 - Consulting and Business Services 20 - Social Enterprises and NGOs 21 - Others, please specify FALSE `specifyIndustry` string When businessIndustry == Others, please specify, this field is Mandatory. FALSE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD7695534567876" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#upload-client-kyc-document) Upload client KYC document -------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/uploadMedia` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. TRUE `mediaType` string This is to specify the document type. Please refer to [Documents](https://choice-bank.gitbook.io/choice-bank/account/current-account#documents) TRUE `mediaBase64` integer BASE64 text of the document file TRUE `contentType` string pdf/image FALSE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#query-onboarding-status) Query onboarding status -------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/getOnboardingStatus` **Parameters** Parameters Type Description Is Required `userId` string The unique string to identify the user in the partner system. FALSE `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. FALSE `mobile` string The mobile number that the customer is using to onboard. Use either one from userId / onboardingRequestId / mobile to query the onboarding status. FALSE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD2309LKSD90432", "onboardingStatus": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#query-client-kyc-information) Query client KYC information ------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/getUserKyc` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. TRUE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD2309LKSD90432", "baasChannelId": "", //This is your channel ID "userId": "", //The unique user identifier in your system "firstName": "Lily", "middleName": "IMISA", "lastName": "WAMBUI", "gender": "0", //0-Female; 1-Male; "nationality": "Kenya", "idType": "", //101-(Kenya) National ID; 102-(Kenya) Alien ID; 103-Passport "idNumber": "", "birthday": "", "address": "", "countryCode": "", //country code for mobile number "mobile": "", "employmentStatus": "", //Please refer to Employment Status Enumeration "monthlyIncome": "", //Please refer to Monthly Income Enumeration "kraPin": "", //Kenya KRA PIN code or tax number from other countries "businessIndustry": "", "specifyIndustry": "", "profileCheck": "", //0-Not Checked; 1-Submitted; 2-Validated; 3-Declined; 4-Processing; "profileCheckResultCode": "", "profileCheckResultText": "", "createTime": "", "updateTime": "", "status": "", //1-Submitted; 2-Processing; 3-Passed; 4-Rejected; //5-Account Closed; 9-Manual Reviewing } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#query-client-kyc-media-information) Query client KYC media information ------------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/personal/getKycMediaList` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. TRUE **Response** 00000 Others Copy { "mediaList": [\ { \ "mediaType": "",\ "fileTypeId": "",\ "mediaUrl": "",\ }, {} \ ] } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/current-account/onboarding#query-client-onboarding-request-id) Query client onboarding request ID ------------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/getOnboardingRequestId` **Parameters** Parameters Type Description Is Required `userId` string The unique string to identify the user in the partner system. FALSE `mobile` string User's mobile number / The mobile number that the user used to onboard FALSE **Response** 00000 Others Copy { "onboardingRequestId": "" } Copy { "code": "12005", "msg": "Invalid signature" } [PreviousCurrent Account](https://choice-bank.gitbook.io/choice-bank/account/current-account) [NextApply for multiple accounts](https://choice-bank.gitbook.io/choice-bank/account/current-account/apply-for-multiple-accounts) Last updated 26 days ago --- # Cancel Account Operation | Choice Bank - API Documentation `POST``/account/cancelAccountOperation` This endpoint is used to cancel account operation requests that have not been confirmed by OTP, which include: `/account/activateAccount /user/verifyEmailAddress /user/addEmail` Fields Type Description Required `requestId` string The request id to be cancelled TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully" } [PreviousNew Features](https://choice-bank.gitbook.io/choice-bank/transfer/new-features) [NextPull transactions](https://choice-bank.gitbook.io/choice-bank/transfer/new-features/pull-transactions) Last updated 29 days ago --- # Query Business Onboarding Request ID | Choice Bank - API Documentation `POST` `/onboarding/business/getOnboardingRequestId` After submit the onboarding request, system will generate the request id and return. This interface can get the the latest onboarding request ID that the onboarding request submit. Both sole proprietor business and company can get the onboarding request ID by this API. Fields Type Description Required? `businessCerNo` String Number of the certificate. Mandatory **Response** 00000 Copy { "onboardingRequestId": "" } [PreviousOpen a Joint Account](https://choice-bank.gitbook.io/choice-bank/account/sme-account/open-a-joint-account) [NextQuery joint account information](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-joint-account-information) Last updated 28 days ago --- # Onboarding | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding#create-a-new-client) Create a new client ----------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/v3/submitEasyOnboardingRequest` **Parameters** Parameters Type Description Is Required `userId` string A unique string to identify the user in the partner system. TRUE `firstName` string First name of the onboarding customer TRUE `middleName` string middle name of the onboarding customer FALSE `lastName` string last name of the onboarding customer TRUE `birthday` string Date of Birth; yyyy-MM-dd TRUE `gender` integer 0 - Female 1 - Male TRUE `countryCode` string The country code of the mobile, that the customer is using to onboard TRUE `mobile` string The mobile number that the customer is using to onboard TRUE `idType` string Type of the document that the customer is using to onboard. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `idNumber` string ID Number of National ID/Passport/Alien ID TRUE `address` string Physical address of the onboarding customer FALSE `kraPin` string KRA PIN / Tax Number FALSE `email` string Email address of the customer FALSE `frontSidePhoto` string Base 64 string TRUE `backSidePhoto` string Base 64 string When idType==101, this is required; When idType==102, this is required; When idType==103, this is NOT required; FALSE `selfiePhoto` string Base 64 string TRUE **Response** 00000 Others Copy { "onboardingRequestId": "" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding#query-onboarding-status) Query onboarding status ------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/getOnboardingStatus` **Parameters** Parameters Type Description Is Required `userId` string The unique string to identify the user in the partner system. FALSE `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. FALSE `mobile` string The mobile number that the customer is using to onboard. Use either one from userId / onboardingRequestId / mobile to query the onboarding status. FALSE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD2309LKSD90432", "onboardingStatus": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding#query-client-kyc-information) Query client KYC information ----------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/getUserKyc` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. TRUE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD2309LKSD90432", "baasChannelId": "", //This is your channel ID "userId": "", //The unique user identifier in your system "firstName": "Lily", "middleName": "IMISA", "lastName": "WAMBUI", "gender": "0", //0-Female; 1-Male; "nationality": "Kenya", "idType": "", //101-(Kenya) National ID; 102-(Kenya) Alien ID; 103-Passport "idNumber": "", "birthday": "", "address": "", "countryCode": "", //country code for mobile number "mobile": "", "employmentStatus": "", //Please refer to Employment Status Enumeration "monthlyIncome": "", //Please refer to Monthly Income Enumeration "kraPin": "", //Kenya KRA PIN code or tax number from other countries "businessIndustry": "", "specifyIndustry": "", "profileCheck": "", //0-Not Checked; 1-Submitted; 2-Validated; 3-Declined; 4-Processing; "profileCheckResultCode": "", "profileCheckResultText": "", "createTime": "", "updateTime": "", "status": "", //1-Submitted; 2-Processing; 3-Passed; 4-Rejected; //5-Account Closed; 9-Manual Reviewing } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding#query-client-kyc-media-information) Query client KYC media information ----------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/personal/getKycMediaList` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. TRUE **Response** 00000 Others Copy { "mediaList": [\ { \ "mediaType": "",\ "fileTypeId": "",\ "mediaUrl": "",\ }, {} \ ] } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/onboarding#query-client-onboarding-request-id) Query client onboarding request ID ----------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/getOnboardingRequestId` **Parameters** Parameters Type Description Is Required `userId` string The unique string to identify the user in the partner system. FALSE `mobile` string User's mobile number / The mobile number that the user used to onboard FALSE **Response** 00000 Copy { "onboardingRequestId": "" } [PreviousWallet Account](https://choice-bank.gitbook.io/choice-bank/account/wallet-account) [NextUpgrade wallet to current account](https://choice-bank.gitbook.io/choice-bank/account/wallet-account/upgrade-wallet-to-current-account) Last updated 28 days ago --- # Pull transactions | Choice Bank - API Documentation `POST` `/query/pullTransactionIds` This API is for BaaS partners to get all transaction IDs within a certain period of time so that they do not miss any inbound transactions when balance change notifications / callback is not received. Allowed query data timespan: past 30 days Allowed query interval: 1 hour Maximum endTime - startTime span: 4 hours Fields Type Description Required? `startTime` Long Unix timestamp of the start time Mandatory `endTime` Long Unix timestamp of the end time Mandatory **Response** 00000 Copy { "transactionID": "00000" //returns list of transaction IDs } [PreviousCancel Account Operation](https://choice-bank.gitbook.io/choice-bank/transfer/new-features/cancel-account-operation) [NextM-PESA PayBill / BuyGoods](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods) Last updated 29 days ago --- # Account Statement API | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api#periodic-account-statement) Periodic Account Statement ---------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/statement/applyAccountStatement` This endpoint allows end users to apply for account statement. Process: You submit the request to generate the account statement data. When the request is received, Choice BaaS will schedule a job to generate the account statement. It will take at most 15 minutes to complete the generation. When the job is done, a "0009" notification will be sent back by the **webhook** which contains the URL for downloading the CSV account statement data. Maximum duration of records you can query for is **180** days Parameters Type Description Is Required `accountId` string The ID of the SME account which you want to query the list of account managers. TRUE `startTime` long Unix timestamp of the start time of the account statement period. TRUE `endTime` long Unix timestamp of the end time of the account statement period. TRUE `fileType` string pdf or xlsx FALSE **Response** 00000 Copy { "jobId": "", //String, account statement generation job id. } [](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api#query-account-statement-job-status) Query Account Statement Job Status -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/statement/queryAccountStatement` This endpoint allows end users to query account statement job status **Parameters** Parameters Type Description Is Required `jobId` string account statement job Id TRUE **Response** 00000 Copy { "jobId": "", //String, account statement generation job id. "status": 1, //Int, status of the job, 0 - Waiting, 1 - Completed. "statementUrl": "" //String, URL to download the account statement when the job is completed. } [](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api#customer-bank-statement-request-to-email) Customer Bank Statement Request (to email) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/statement/applyBankAccountStatement` Customers request the bank account statement (for now, available in **Excel** form only) for a period, and the statement will be generated assynchronously and encryptedly sent to the owner's/account manager's email. An account can only request a max of 10 times in a day Password is last 6 digits of the owner of the account's mobile number The statement link contained in the email body expires in 7 days **Parameters** Parameters Type Description Required? `accountId` string The number of the account TRUE `startTime` long (UNIX timestamp) TRUE `endTime` long (UNIX timestamp). Not more than 180 days. TRUE email string The email address of the account owner or account manager, with or without verification. TRUE `fileType` string pdf or xlsx FALSE **Response** 00000 Copy { "jobId": "", //String, account statement generation job id } [](https://choice-bank.gitbook.io/choice-bank/account/account-management/account-statement-api#query-customer-statement-request-to-email-application-status) Query Customer Statement Request (to email) Application Status -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/statement/queryBankAccountStatement` Use this to check the status of the bank account statement application status. An account can only request a max of 10 times in a day Password is last 6 digits of the owner of the account's mobile number The statement link contained in the email body expires in 7 days **Parameters** Parameters Type Description Is Required `jobId` string account statement job Id TRUE **Response** 00000 Copy { "jobId": "", //String, account statement generation job id "accountId": "", //Requested account number "email": "" //Requested email address "status": 1 //Int, status of the job, 0 - Waiting, 1 - Completed } [PreviousAccount Management](https://choice-bank.gitbook.io/choice-bank/account/account-management) [NextDeposit from M-PESA](https://choice-bank.gitbook.io/choice-bank/deposit/deposit-from-m-pesa) Last updated 24 days ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer/api-reference#request-for-bulk-transfer) Request for Bulk Transfer -------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/v2/generalBulkTransfer` **Parameters** Parameters Type Description Is Required `payerAccountId` string The ID of the account that is to make the transfer TRUE `txDetails` array Bulk payment details: benificiaryName benificiaryType payType benificiaryAccount benificiarySubAccount benificiaryBankCode amount remark payeeMobileForNotification TRUE `benificiaryName` string Name of the beneficiary TRUE `benificiaryType` string 0 - Individual 1 - Business TRUE `payType` string 0 - Paybill 1 - Till/BuyGoods Optional unless Mpesa B2B FALSE `benificiaryAccount` string Beneficiary account number / shortcode TRUE `benificiarySubAccount` string SubAccount of the beneficiary if the counterparty is a paybill FALSE `benificiaryBankCode` string Beneficiary bank code Please refer to [Get Enumerations](https://choice-bank.gitbook.io/choice-bank/appendix/get-enumerations#bank-code-list) TRUE `amount` decimal Transfer amount TRUE `remark` string Message to beneficiary FALSE `payeeMobileForNotification` string Specify beneficiary's mobile number here and the bank will send SMS notification to inform him/her about the inbound. FALSE **Response** 00000 Copy { "bulkPaymentOrderId": "" //Bulk payment order id } [](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer/api-reference#query-bank-transfer-details) Query Bank Transfer Details ------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/trans/queryBatchTransactionResult` **Parameters** Parameters Type Description Is Required `orderId` string The bulk transfer order ID TRUE `pageNo` int Page number TRUE `pageSize` int Page size TRUE **Response** 00000 Copy { "orderId": "", "total": "", //total number of records of the query "resultArray": [\ {\ "txId": "",\ "payerAccount": "",\ "payerAccountName": "",\ "benificiaryAccount": "",\ "benificiaryName": "",\ "benificiarySubAccount": "",\ "benificiaryBankCode": "",\ "paymentChannel": "",\ "currency": "",\ "amount": "",\ "feeAmount": "",\ "externalTxId": "",\ "errorCode": "",\ "errorMsg": ""\ }\ ] } [PreviousBulk Transfer](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer) [NextForeign Exchange](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange) Last updated 22 days ago --- # Apply for FX v2 | Choice Bank - API Documentation `POST` `/trans/v2/applyForFcExchange` This allows customers to do Foreign Exchanges, enabling foreign currency to KES, KES to foreign currency and foreign currency to foreign currency. Field Type Description Is Required `sourceCurrency` string The currency that customers want to transfer from Mandatory `targetCurrency` string The currency that customers want to transfer to Mandatory `sourceAccount` string The account that customers want to transfer from Mandatory `targetAccount` string The account that customers want to transfer to Mandatory `sourceAmount` decimal The amount of money in sourceCurrency that customers want to transfer to another currency. Either `sourceAmount` or `targetAmount` is Mandatory. Conditional `targetAmount` decimal The amount of money in targetCurrency that customers want to receive after foreign exchange. Either `sourceAmount` or `targetAmount` is Mandatory. Conditional **Response** 00000 Copy "data": { "applicationId": "", //String, unique application id of the foreign exchange application. } [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange/apply-for-fx-v2#query-foreign-exchange-rate-v2) Query Foreign Exchange Rate v2 ----------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/v2/getForeignExchangeRate` **Request params** 00000 Copy "params": { "currencyPair": //String, Mandatory, Currency pairs //Support the following values: // "USD/KES" // "EUR/KES" // "GBP/KES" // "KES/TZS" // "KES/UGX" // "KES/RWF" // "GBP/USD" // "EUR/GBP" // "EUR/USD" // "USD/CNY" // The above stands for BaseCurrency/QuoteCurrency } **Response Data** 00000 Copy "data": { "UnitAmount": 1, //Int, unit amount of the foreign currency "CurrencyPair": "", //String, currency pair "TT": { //Telegraphic Transfer rate of currency exchange "SELL": "136.2300", //TT Bank sell (BaseCurrency) price, 4 decimal places. "BUY": "135.1110" //TT Bank buy (BaseCurrency) price, 4 decimal places. } } [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange/apply-for-fx-v2#new-api-query-fcy-exchange-request-status-v2) New API: Query FCY Exchange Request Status v2 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/v2/getFxRequestStatus` **Request params** Field Type Description Is Required `applicationId` string unique id of the FCY exchange request Mandatory **Response Data** 00000 Copy "data": { "applicationId": , //String, unique id of the FCY exchange request. "sourceAcctId":"", //String, the number of the debited account "targetAcctId":"", //String, the number of the credited account "sourceCurrency":"", //String, the currency of the debited account "targetCurrency": "", //String, the currency of the credited account "sourceAmt":"", //Decimal, the exchange amount of the debited account "targetAmt": "",//Decimal, the exchange amount of the credit account "outTxId": "", //String, debit transaction id "inTxId": "", //String, credit transaction id "status": 1, //Int, 1:init, 2:wait for review, 4:reject，5:approved,6:completed, 7:failed", "fxRate": "",, //String, actual exchange rate, 4 decimal places "errorCode": "", //String, code or the faliure reason, please refer to FCY Error Code "errorMsg": "" //String, reject reason } [](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange/apply-for-fx-v2#new-notification-0026-foreign-exchange-notification-v2) New Notification: 0026 - Foreign Exchange Notification v2 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- **Request params** 00000 Copy { "requestId":"", //String, unique id of the notification which is generated by baas "sender":"", //String, sender id of baas system "locale":"en_KE", //String, language config "timestamp": //long, notification send time. UTC Unix timestamp in millisecond. "notificationType":"0013", //String, notification type id "params": { "applicationId":"", //String, FX application id "sourceAcctId":"", //String, the number of the debited account "targetAcctId":"", //String, the number of the credited account "sourceCurrency":"", //String, the currency of the debited account "targetCurrency": "", //String, the currency of the credited account "sourceAmt":"", //Decimal, the exchange amount of the debited account "targetAmt": "",//Decimal, the exchange amount of the credit account "status":, //Int, 4-reject, 6-succeed, 7-failed "fxRate":"", //String, exchange rate "inTxId":"", //String, credit transaction id "outTxId":"", //String, debit transaction id "errorCode":"", //String, error code. "errorMsg":"" //String, error message. please refer to FCY error code }, "salt":"", //String, salt "signature":"" //String, signature } **Response Data** [PreviousForeign Exchange](https://choice-bank.gitbook.io/choice-bank/transfer/foreign-exchange) [NextNew Features](https://choice-bank.gitbook.io/choice-bank/transfer/new-features) Last updated 4 days ago --- # Query Account Manager/Administrator List | Choice Bank - API Documentation `POST` `/account/queryAccountAdministrator` Use this endpoint to query account managers of SME account. **Parameters** Parameters Type Description Required? `accountId` string The account number of the SME which you want to query the list of account managers. TRUE **Response** 00000 Copy "data": { "accountManagerInfos":[\ //Array of Object, array of the detailed information of the account managers.\ {\ "accountId": "", //String, SME account Id\ "fullName": "", //String, full name of the account manager which is submitted when added \ "email": "", //String, email of the account manager.\ "countryCode": "", //String, phone country code, "254" for Kenya\ "mobile": "", //String, mobile number of the account manager\ "idType":"", //String, Identity document ID type\ "idNumber":"", //String, Identity Number \ "emailVerified":"", //Integer, 0 is unverified, 1 is verified\ "mobileVerified":"", //Integer, 0 is unverified, 1 is verified \ "createTime": 1234567890, //Long, unix timestamp of the time the account manager was added.\ "updateTime": 1234567890 //Long, unix timestamp of the time when the account manager was updated. \ },{}\ ] } [PreviousQuery joint account information](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-joint-account-information) [NextAccount Management](https://choice-bank.gitbook.io/choice-bank/account/account-management) Last updated 29 days ago --- # Apply for multiple accounts | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/apply-for-multiple-accounts#apply-for-multiple-account) Apply for multiple account --------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/businessOpenAccount` **Parameters** Parameters Type Description Is Required `businessName` string SME's business name TRUE `businessCertId` string The number of the business certificate ID that the end user used to onboard. TRUE `currency` string The currency of the new account that the end user wants to open. The following values are allowed: KES/USD/GBP/EUR/CNY/TZS/UGX/RWF TRUE `operatingMode` string Operating mode of the new account. 1 - Singly 2 - Either to sign 3 - Any Two to Sign 4 - All of Us Jointly TRUE **Response** 00000 Copy { "applicationId": "" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/apply-for-multiple-accounts#query-account-opening-request-status) Query account opening request status ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/getAccountOpeningStatus` **Parameters** Parameters Type Description Is Required `applicationId` string Account opening application ID TRUE **Response** 00000 Copy { "applicationId": "", "status": "", //1-Submitted; 2-OTP Confirmed; 3-Successful "accountId": "", //The number of the new account "accountName": "", "currency": "", } [PreviousAccount Administrator](https://choice-bank.gitbook.io/choice-bank/account/sme-account/account-administrator) [NextOpen a Joint Account](https://choice-bank.gitbook.io/choice-bank/account/sme-account/open-a-joint-account) Last updated 1 month ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer/api-reference#request-for-transfer) Request for Transfer ------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/v2/applyForTransfer` **Parameters** Parameters Type Description Is Required `payerAccountId` string The ID of the account that is to make the transfer TRUE `payeeBankCode` string The bank code of the receiving bank Use `/staticData/getBankCodes` endpoint to get the list of bank codes TRUE `payeeAccountId` string The number of the receiving account TRUE `payeeAccountName` string The name of the receiving account This is mandatory when counterparty is a bank. When counterpaty is M-PESA/AIRTEL, it's optional. FALSE `currency` string Transfer currency (Supports KES, USD, GBP, EUR, TZS, UGX, RWF) TRUE `amount` decimal Transfer amount TRUE `remark` string The message to beneficiary. Not more than 100 characters. FALSE `payeeMobileForNotification` string Specify beneficiary's mobile number here and the bank will send SMS notification to inform him/her about the inbound. FALSE **Response** 00000 Copy { "txId": "" } [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer/api-reference#query-transaction-list) Query Transaction List ----------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getTransList` Query the transaction records of an account. This interface returns the transaction records page by page. Your program can assign the page number and the page size (how many records contains in a page) according to your need. If you want to get the transaction records in a call, just enlarge the page size. For example, pageNo=1 and pageSize = 50. Parameters Type Description Is Required `userId` string User ID in your system, a unique string to indentify a certain end user. TRUE `accountId` string Account ID TRUE `txType` array of string Transaction type filter. Please refer to the [transaction type definition](https://kgegjwnjseu.sg.larksuite.com/file/BaXfbjAQsoDM8dxU7pSljV84gqf?from=from_copylink) . If you want to get all type of the transaction record, just input blank array, i.e. \[\]. TRUE `txStatus` array of string Transaction status filter. Please refer to the transaction type definition. Example: \[2, 8\] - Get all processing and succeed transaction records. TRUE `startTime` long UTC timestamp in millisecond of the start time of the queried period. TRUE `endTime` long UTC timestamp in millisecond of the end time of the queried period. TRUE `pageNo` int Assign the page number. TRUE `pageSize` int Assign how many records return. TRUE `orderByDesc` int Parameter to indicate how to sort the returns records. 1 - Sorting the records by transaction date in reversing order. 0 - Sorting the records by transaction date in positive order. TRUE **Response** 00000 Copy { "totalRows": "",//integer, total # of the transaction records "result": [\ {\ "txId": "",\ "txType": "",\ "accountId": "",\ "accountName": "",\ "accountType": "",\ "oppoAccountId": "",\ "oppoAccountName": "",\ "oppoBankName": "",\ "oppoBankCode": "",\ "thirdPartyTxType": "",\ "currency": "",\ "amount": "",\ "feeAmount": "",\ "txStatus": "",\ "createTime": "",\ "updateTime": "",\ }, {} \ ] } [](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer/api-reference#query-transaction-details) Query Transaction Details ----------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getTransResult` **Parameters** Parameters Type Description Is Required `txId` string The ID of the transaction TRUE **Response** 00000 Copy { "txId": "", "txType": "", "accountId": "", "accountName": "", "accountType": "", "oppoAccountId": "", "oppoAccountName": "", "oppoSubAccount": "", "mpesBusinessPayType": "", "oppoBankName": "", "oppoBankCode": "", "thirdPartyTxType": "", "currency": "", "amount": "", "feeAmount": "", "extInfo": { "transactionNarrative": "", "oppoPhoneNumber": "", }, "externalTxId": "", "paymentChannel": "", "originalTxId": "", "refundTxId": "", "txStatus": "", "createTime": "", "updateTime": "", "errorCode": "", "errorMsg": "", } [PreviousGeneral Transfer](https://choice-bank.gitbook.io/choice-bank/transfer/general-transfer) [NextBank Transfer (RTGS/EFT)](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft) Last updated 5 days ago --- # Apply for M-PESA B2B Transfer v2 | Choice Bank - API Documentation `POST` `/trans/v2/applyForMpesaBusinessTransfer` This is the v2 of applyForMpesaBusinessTransfer endpoint. Currencies supported: USD, GBP, KES, CNY, TZS, UGX. RWF. The updates of this endpoint involve: 1. Parameters like otpType and otpMobile are removed from the endpoint to reduce the redundancy, meaning, no OTP will be automatically sent when this endpoint is called. BaaS server should call `/common/v2/sendOtp` endpoint to trigger the OTP sending. 2. With the combination of API `/common/v2/sendOtp,` users can specify the OTP service and the account manager (if the OTP should not go to account owner), meaning, with proper parameters, the OTP can be send to account owner's mobile/email or to account manager's mobile/email. 3. With the combination of API `/common/v2/sendOtp`, users can approve a batch of mpesa b2b transfers in one go. As endpoint `/common/v2/sendOtp` allows server to pass a list of txIds as a parameter and use ONE OTP to validate all transactions within the approved list, and our system will process the approved transactions one by one. 4. `/common/v2/sendOtp` can be used to re-send if the OTP sent does not reach customer. Fields Data Type Description Requirement `payerAccountId` String The number of the account that is to be debited Mandatory `payeeShortCode` String Counterparty shortcode of (paybill/paytill) Mandatory `payType` Integer 0 for Paybill1 for Paytill Mandatory `payeeReferenNumber` String Sub-account Number. Mandatory if paytype is 0 Conditional `amount` Decimal We assume it's KES amount Mandatory `description` String Message to the beneficiary Optional `payeeMobileForNotification` String Mobile number of the beneficiary if the payment initiator wants to send sms notification to the beneficiary Optional **Response Data** 00000 Copy { "txId": "", //String, Unique Transaction ID } ### [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/apply-for-m-pesa-b2b-transfer-v2#otp-mechanism) **OTP Mechanism** **Confirm OTP API** Use `/common/confirmOperation` **Send/Resend OTP API** Use `/common/sendOtp` or `/common/sendAccAdminOtp` **Confirm OTP API** Use `/common/confirmOperation` **OTP Notification Template** 1014 OR E318 [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/apply-for-m-pesa-b2b-transfer-v2#generate-qr-code-m-pesa-paybill) Generate QR Code (M-pesa Paybill) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/generateQRCode` Perfect for: business customers who have paybills and wish to be able to generate M-pesa QR codes to assist in the payment process for their customers This API generates a dynamic QR which enables Safaricom M-pesa customers who have My Safaricom App or M-PESA app, to scan a QR (Quick Response) code, to capture Choice's paybill number and amount automatically then authorize to pay bill and credit the Choice customer account. **Response Data** 00000 Copy { "code": "", "msg": "", "sender": "", "locale": "", "requestId": "",m//request-id string "data": { "requestId": "GQRC122514268054626304", //string, request-id "status": 1, // 0 - fail; 1 - succcessful "qrCode": "base64-string here" //string, base64 }, "timestamp": ""// unix timestamp in milliseconds } [PreviousAPI Reference](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/api-reference) [NextUtility Payment](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment) Last updated 3 hours ago --- # Account Administrator | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/account-administrator#add-account-administrator-for-sme) Add Account Administrator for SME ----------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/v2/addAccountAdministrator` **Parameters** Parameters Type Description Is Required `accountId` string The account that the account administrator will be have access to/allowed to make operations on. TRUE `idType` string Type of the document. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `idNumber` string ID number of the administrator TRUE `fullName` string full name of the administrator TRUE `countryCode` string Country code of the administrator's mobile. E.g. 254 TRUE `mobile` string mobile number of the administrator TRUE `email` string Email address of the administrator TRUE **Response** 00000 Copy { "accAdminRequestId": "" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/account-administrator#verify-account-administrator) Verify Account Administrator ------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/verifyAccountAdministrator` **Parameters** Parameters Type Description Is Required `accountId` string The account that the account administrator will have access to/be allowed to make operations on. TRUE `idType` string Type of the document. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `idNumber` string ID number of the administrator TRUE `verifyType` string EMAIL MOBILE TRUE **Response** 00000 Copy { "applicationId": "" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/account-administrator#remove-account-administrator) Remove Account Administrator ------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/account/removeAccountAdministrator` **Parameters** Parameters Type Description Is Required `accountId` string The account that the account administrator will be have access to/allowed to make operations on. TRUE `countryCode` string country code of that account administrator's mobile FALSE `mobile` string Mobile number the account administrator that is to be removed FALSE `idType` string Type of the document of the account administrator that is to be removed. 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport FALSE `idNumber` string ID number of the administrator that is to be removed. FALSE **Response** 00000 Copy { "applicationId": "" } [PreviousOnboarding](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding) [NextApply for multiple accounts](https://choice-bank.gitbook.io/choice-bank/account/sme-account/apply-for-multiple-accounts) Last updated 8 months ago --- # Query joint account information | Choice Bank - API Documentation `POST` `/onboarding/getJointAccountOnboardingInfo` Use this endpoint to get the onboarding information of the joint account that customer submitted. **Parameters** Parameters Type Description Required? `onboardingRequestId` string unique onboarding request id returned from Choice system. TRUE **Response** 00000 Copy { "onboardingRequestId": "",//ID of request which customer submitted most recently "channel": "", //This is your channel ID "channelUserId": "", //The unique user identifier in your system "operatingMode": "", //1 (Singly) or 6 (Anyone or survivor) "status": "", "createTime": "", "auditTime": "0", //0-Female; 1-Male "rejectReasonIds": "", //ISO 3166-2 country code "rejectReasonMsgs": "", //101-(Kenya) National ID; 102-(Kenya) Alien ID; 103-Passport "onboardingMediaInfos": [\ {\ "fileUrl": "",\ "mediaType": "",\ "contentType": "",\ "fileTypeId": "", //File type id，KYCFxxxxx\ "fileKey": "", //s3 file key\ "fileId": "",\ }\ ], "onboardingMediaInfos": [\ {\ "memberId": "", //ownerId\ "firstName": "", //First name of customer\ "middleName": "",//Middle name of customer\ "lastName": "", //Last Name of customer\ "fullName": "",\ "idType": "",\ "idNumber": "",\ "kraPin": "", //Kenya KRA PIN code or tax number from other countries\ "mobile": "",\ "email": "",\ "idFrontFileUrl": "",\ "idFrontFileType": "",\ "idFrontFile": "",\ "idBackFileUrl": "",\ "idBackFileType": "",\ "idBackFile": "",\ "kraPinFileUrl": "",\ "kraPinFileType": "", //File type, image/pdf\ "kraPinFile": "",\ "isPrimary": "", //Is primary owner，0：false，1：true\ "emailVerified": "", //0:unverify, 1:verified\ "mobileVerified": "", //0:unverify, 1:verified\ }\ ] [PreviousQuery Business Onboarding Request ID](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-business-onboarding-request-id) [NextQuery Account Manager/Administrator List](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-account-manager-administrator-list) Last updated 28 days ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/api-reference#request-for-mpesa-b2b-transfer) Request for MPESA B2B Transfer --------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/v2/applyForMpesaBusinessTransfer` **Parameters** Parameters Type Description Is Required `payerAccountId` string The ID of the account that is to make the transfer TRUE `payeeShortCode` string The shortcode of the receiving paybill/till. TRUE `payeeReferenceNumber` string The account number that is required when receiving party is a Paybill. FALSE `payType` string 0 - Paybill 1 - Till/BuyGoods TRUE `amount` decimal Transfer amount, it has to be whole number TRUE `description` string The message to beneficiary. Not more than 100 characters. FALSE `payeeMobileForNotification` string Specify beneficiary's mobile number here and the bank will send SMS notification to inform him/her about the inbound. FALSE **Response** 00000 Copy { "txId": "ONBOARD7695534567876" } [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/api-reference#query-transaction-list) Query Transaction List ----------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getTransList` **Parameters** Parameters Type Description Is Required `userId` string User ID in BaaS partner's system, a unique string to indentify a certain end user. TRUE `accountId` string End user's account number TRUE `txType` array of string Transaction type filter. FALSE `txStatus` array of string Transaction status filter. FALSE `startTime` long Start time TRUE `endTime` long End time TRUE `pageNo` int Page number TRUE `pageSize` int Page size TRUE `orderByDesc` int 0 - ASC 1 - DESC (default) FALSE **Response** 00000 Copy { "totalRows": "", "result": [\ {\ "txId": "",\ "txType": "",\ "accountId": "",\ "accountName": "",\ "accountType": "",\ "oppoAccountId": "",\ "oppoAccountName": "",\ "oppoBankName": "",\ "oppoBankCode": "",\ "thirdPartyTxType": "",\ "currency": "",\ "amount": "",\ "feeAmount": "",\ "txStatus": "",\ "createTime": "",\ "updateTime": "",\ }, {} \ ] } [](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/api-reference#query-transaction-details) Query Transaction Details ----------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/query/getTransResult` **Parameters** Parameters Type Description Is Required `txId` string The ID of the transaction TRUE **Response** 00000 Copy { "txId": "", "txType": "", "accountId": "", "accountName": "", "accountType": "", "oppoAccountId": "", "oppoAccountName": "", "oppoSubAccount": "", "mpesBusinessPayType": "", "oppoBankName": "", "oppoBankCode": "", "thirdPartyTxType": "", "currency": "", "amount": "", "feeAmount": "", "extInfo": { "transactionNarrative": "", "oppoPhoneNumber": "", }, "externalTxId": "", "paymentChannel": "", "originalTxId": "", "refundTxId": "", "txStatus": "", "createTime": "", "updateTime": "", "errorCode": "", "errorMsg": "", } [PreviousM-PESA PayBill / BuyGoods](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods) [NextApply for M-PESA B2B Transfer v2](https://choice-bank.gitbook.io/choice-bank/payment/m-pesa-paybill-buygoods/apply-for-m-pesa-b2b-transfer-v2) Last updated 1 month ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift/api-reference#request-for-cross-border-bank-transfer) Request for Cross-border Bank Transfer ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/telegraphicTransfer` **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that is to make the transfer TRUE `beneficiarySwiftBic` string The bank code of the receiving bank Use `/staticData/getBankCodes` endpoint to get the list of bank codes TRUE `beneficiaryBankName` string The name of the receiving bank TRUE `beneficiaryBankCountry` string The branch code of the receiving bank FALSE `beneficiaryBankCity` string The city of the receiving bank TRUE `beneficiaryBankAddress` string The address of the receiving bank FALSE `beneficiaryAccountId` string The number of the receiving account TRUE `beneficiaryAccountCcy` string The currency of the receiving account TRUE `beneficiaryName` string Beneficiary name TRUE `beneficiaryEmail` string The email address of the beneficiary FALSE `amount` decimal Transfer amount TRUE `amountType` Int 0 - In Debit Account Currency 1 - In Credit Account Currency TRUE `messageToBeneficiary` string The message to beneficiary. Not more than 100 characters. FALSE `paymentChannel` string SWIFT TRUE `paymentPurposeId` string Please refer to [Payment Purpose](https://choice-bank.gitbook.io/choice-bank/appendix/const#payment-purpose) TRUE `paymentPurpose` string When paymentPurposeId == OTHR, specify the payment payment in this parameter. Not more than 35 characters. FALSE `senderAddress` string Sender's address TRUE `supportDocument` string Base 64 string FALSE `supportDocumentType` string PDF Image FALSE `chargeType` string OUR BEN SHA Notes: OUR: Remitter to pay all charges BEN: Beneficiary to pay all charges SHA: Shared. Remitter to pay all fees charged by the sending bank (Here, Choice Bank) and Beneficiary to pay all fees charged by the receiving bank and intermediary/correspondent bank TRUE **Response** 00000 Copy { "applicationId": "" } [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift/api-reference#query-inter-bank-fund-transfer-list) Query Inter-Bank Fund Transfer List ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/getInterBankTransferList` **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that is to make the transfer TRUE `startTime` long Start time TRUE `endTime` long End time TRUE `pageNo` int Page number TRUE `pageSize` int Page size TRUE **Response** 00000 Copy { "result": [\ {\ "applicationId": "",\ "accountId": "",\ "type": "", //1-Domesitc Fund Transfer; 2-Cross-border Fund Transfer\ "currency": "",\ "amount": "",\ "createTime": "",\ "status": "",\ }\ ] } [](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift/api-reference#query-inter-bank-fund-transfer-details) Query Inter-Bank Fund Transfer Details ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/getInterBankTransferDetails` **Parameters** Parameters Type Description Is Required `applicationId` string The ID of the RTGS/EFT/SWIFT transfer application TRUE `accountId` string Account number TRUE **Response** 00000 Copy { "applicationId": "", "type": "", //1-Domesitc Fund Transfer; 2-Cross-border Fund Transfer "debitAccountId": "", "beneficiaryBankName": "", "beneficiaryBankCode": "", "beneficiaryBranchCode": "", "beneficiaryBankCountry": "", "beneficiaryBankCity": "", "beneficiaryBankAddress": "", "beneficiaryName": "", "beneficiaryEmail": "", "beneficiaryAccountId": "", "beneficiaryAccountCurr": "", "requestAmtType": "",//0-In debit account currency; 1-in beneficiary account currency "requestAmt": "",//requested transfer amount in the selected requestAmtType "transferAmt": "",//Actual transfer amount in debit account currency "bankCharge": "", "debitAmt": "", "chargeType": "", "paymentChannel": "", "paymentPurposeId": "", "paymentPurpose": "", "senderAddress": "", "messageToBeneficiary": "", "supportDocument": "", "supportDocumentType": "", "txId": "", "refundTxId": "", "referenceNumber": "", "createTime": "", "updateTime": "", "status": "", "errorCode": "", "errorMsg": "", "exchangeRate": "", } [PreviousInternational Transfer (SWIFT)](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift) [NextBulk Transfer](https://choice-bank.gitbook.io/choice-bank/transfer/bulk-transfer) Last updated 5 days ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft/api-reference#large-domestic-interbank-transfer) Large Domestic Interbank Transfer --------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/largeDomesticInterBankTransfer` **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that is to make the transfer. Rules: 1. The currency of the accountId and beneficiaryAccountCcy have to be the same. E.g both USD, both GBP etc. For now, the account can only be USD, KES, GBP, EUR accounts 2. Or no matter what currency the beneficiaryAccountCcy is, the currency of accountId is KES. E.g, accountId is KES, beneficiaryAccountCcy can be USD/GBP/EUR/TZS/UGX/RWF. TRUE `beneficiaryBankCode` string The bank code of the receiving bank Use `/staticData/getBankCodes` endpoint to get the list of bank codes TRUE `beneficiaryBankName` string The name of the receiving bank TRUE `beneficiaryBranchCode` string The branch code of the receiving bank FALSE `beneficiaryAccountId` string The number of the receiving account TRUE `beneficiaryAccountCcy` string The currency of the receiving account Allow it to be the following currencies: KES/USD/GBP/EUR/TZS/UGX/RWF TRUE `beneficiaryName` string Beneficiary name TRUE `beneficiaryEmail` string The email address of the beneficiary FALSE `amount` decimal Transfer amount TRUE `amountType` Int 0 - In Debit Account Currency 1 - In Credit Account Currency TRUE `messageToBeneficiary` string The message to beneficiary. Not more than 100 characters. FALSE `paymentChannel` string EFT RTGS TRUE `paymentPurposeId` string Please refer to [Payment Purpose](https://choice-bank.gitbook.io/choice-bank/appendix/const#payment-purpose) TRUE `paymentPurpose` string When paymentPurposeId == OTHR, specify the payment payment in this parameter. Not more than 35 characters. FALSE `senderAddress` string Sender's address TRUE `supportDocument` string Base 64 string FALSE `supportDocumentType` string PDF Image FALSE **Response** 00000 Copy { "applicationId": "" } [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft/api-reference#get-interbank-transfer-list) Get Interbank Transfer list --------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/getInterBankTransferList` **Parameters** Parameters Type Description Is Required `clientId` String Client ID TRUE `accountId` string Account number TRUE `startTime` long Start time TRUE `endTime` long End time TRUE `pageNo` int Page number TRUE `pageSize` int Page size TRUE **Response** 00000 Copy { "result": [\ {\ "applicationId": "",\ "accountId": "",\ "type": "", //1-Domestic Fund Transfer; 2-Cross-border Fund Transfer\ "currency": "",\ "amount": "",\ "createTime": "",\ "status": "",\ }\ ] } [](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft/api-reference#query-interbank-transfer-details) Query Interbank Transfer Details ------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/trans/getInterBankTransferDetails` **Parameters** Parameters Type Description Is Required `applicationId` string Application ID TRUE **Response** 00000 Copy { "applicationId": "", "type": "", //1-Domestic Fund Transfer; 2-Cross-border Fund Transfer "debitAccountId": "", "beneficiaryBankName": "", "beneficiaryBankCode": "", "beneficiaryBranchCode": "", "beneficiaryBankAddress": "", "country": "", "city": "", "address": "", "beneficiaryName": "", "beneficiaryEmail": "", "beneficiaryAccountId": "", "beneficiaryAccountCurr": "", "requestAmtType": "",//Query Interbank transfer details0-In debit account currency; 1-in beneficiary account currency "requestAmt": "",//requested transfer amount in the selected requestAmtType "transferAmt": "",//Actual transfer amount in debit account currency "bankCharge": "", "debitAmt": "", "chargeType": "", "paymentChannel": "", "paymentPurpose": "", "messageToBeneficiary": "", "supportDocument": "" "referenceNumber": "", "createTime": "", "updateTime": "", "status": "", } [PreviousBank Transfer (RTGS/EFT)](https://choice-bank.gitbook.io/choice-bank/transfer/bank-transfer-rtgs-eft) [NextInternational Transfer (SWIFT)](https://choice-bank.gitbook.io/choice-bank/transfer/international-transfer-swift) Last updated 5 days ago --- # API Reference | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#airtime-purchase) Airtime Purchase --------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/v2/airtimePayment` **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that is to make the payment TRUE `mobileNumber` string The number of the mobile that is to purchase airtime for TRUE `networkProvider` int 0 - SAFARICOM 1 - AIRTEL 2 - TELKOM TRUE `amount` decimal Top up amount TRUE **Response** 00000 Copy { "txId": "", "paymentId": "" } [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#airtime-purchase-bulk) Airtime Purchase - Bulk --------------------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/v2/airtimeBulkPayment` **Parameters** Parameters Type Description Is Required `accountId` string The ID of the account that is to make the payment TRUE `mobileDetails` array The mobile numbers that are to be purchased airtime for. TRUE \>>`mobileNumber` string Mobile number TRUE \>>`networkProvider` int 0 - SAFARICOM 1 - AIRTEL 2 - TELKOM TRUE \>>`amount` decimal Top up amount TRUE **Response** 00000 Copy { "bulkPaymentOrderId": "" } [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#query-utility-bill) Query Utility Bill ------------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/billQuery` **Parameters** Parameters Type Description Is Required `billType` int 0 - DSTV 1 - GOTV 3 - STARTIMES 6 - WATER TRUE `mobile` string The mobile number that is linked to the bill FALSE `billOrderNumber` string Bill order number TRUE **Response** 00000 Copy { "dueDate": "", "dueAmount": "", "currency": "", } [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#utility-bill-payment) Utility Bill Payment ----------------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/v2/billPayment` **Parameters** Parameters Type Description Is Required `accountId` string The number of the account that is to make the payment TRUE `billType` int 0 - DSTV 1 - GOTV 3 - STARTIMES 6 - WATER TRUE `billOrderNumber` string Bill order number TRUE `amount` decimal Payment amount; If it's not given, it will be populated with the due amount of that bill. FALSE **Response** 00000 Copy { "txId": "", "paymentId": "" } [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#query-utility-payment-details) Query Utility Payment Details ----------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/paymentQuery` **Parameters** Parameters Type Description Is Required `paymentId` string The unique string that generated by Choice to identify a utility payment/airtime purchase request TRUE **Response** 00000 Copy { "paymentId": "", "payServiceCategory": "", //0 - Airtime Purchase; 3 - Utility Bill "subType": "", //For airtime purchase, 0-SAFARICOM; 1-AIRTEL; 2-TELKOM //For utility bill, 0-DSTV; 1-GOTV; 3-STARTIMES; 6-WATER "orderNo": "", "txId": "", "refundTxId": "", "amount": "", "status": "", //-1 - Cancelled; 0 - Init; 1 - Submitted; 2 - Processing; //4 - Failed; 8 - Completed "errorCode": "", "errorMsg": "", } [](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment/api-reference#query-bulk-payment-details) Query Bulk Payment Details ----------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/utilityPayment/bulkPaymentQuery` **Parameters** Parameters Type Description Is Required `bulkPaymentOrderId` string The unique string that generated by Choice to identify a batch of utility payment/airtime purchase requests TRUE `pageNo` int page number TRUE `pageSize` int page size TRUE **Response** 00000 Copy { "bulkPaymentOrderId": "", "total": "", //total number of payment requests "resultArray": [\ {\ "paymentId": "",\ "payServiceCategory": "", //0 - Airtime Purchase; 3 - Utility Bill\ "subType": "", //For airtime purchase, 0-SAFARICOM; 1-AIRTEL; 2-TELKOM\ //For utility bill, 0-DSTV; 1-GOTV; 3-STARTIMES; 6-WATER\ "orderNo": "",\ "txId": "",\ "refundTxId": "",\ "amount": "",\ "status": "", //-1 - Cancelled; 0 - Init; 1 - Submitted; 2 - Processing; \ //4 - Failed; 8 - Completed\ "errorCode": "",\ "errorMsg": "",\ }, {}\ ] } [PreviousUtility Payment](https://choice-bank.gitbook.io/choice-bank/payment/utility-payment) [NextConfirm OTP](https://choice-bank.gitbook.io/choice-bank/otp/confirm-otp) Last updated 8 months ago --- # Apply for outbound external payment channel (RTGS, EFT) | Choice Bank - API Documentation `POST` `/trans/applyInternalPaymentChannelInbound` This API is for BaaS clients to submit a collection request for their externally transferred funds via RTGS, EFT or SWIFT to allow crediting their accounts in Choice Bank. Fields Type Description Required? `accountId` String The number of the account that is to be debited Mandatory `paymentChannel` String The payment channel that the customer chooses to transfer the money to Choice's bank account.RTGSEFT Optional `benificiaryBankCode` String bank code of transfer bank. Please refer to "**Bank Code**" column of the [Choice Bank Code List](https://n05mxbyps1.feishu.cn/sheets/shtcnFyw3Kroc5tHUniyUaEptwf) .NB: where this parameter is specified, the **benificiaryBankName** parameter ought not to be supplied Conditional `benificiaryBankName` String The name of the counterparty bankNB: where this parameter is specified, the **benificiaryBankCode** parameter ought not to be supplied Conditional `benificiaryBankAccount` String The account number of the counterparty (Receiver) that the customer requests to receive the funds Mandatory `benificiaryBankAccountName` String The name of the counterparty (receiver) that the customer requests to receive the funds Mandatory `amount` String The amount of the transfer (also the amount that the account has to be credited) Mandatory `supportDocument` File Contracts, source of funds or other supporting documents that Bank may require.The file is expected to be coded in Base64 representation Optional `documentType` String Specify the file type of the support documentPDFImageIf this is not specified, by default the type is PDF Optional **Response** 00000 Copy { "applicationId": "", } [PreviousApply for inbound external payment channel (RTGS, EFT)](https://choice-bank.gitbook.io/choice-bank/others/merchant/apply-for-inbound-external-payment-channel-rtgs-eft) [NextCallback and IP Whitelisting](https://choice-bank.gitbook.io/choice-bank/notifications/callback-and-ip-whitelisting) Last updated 28 days ago --- # Open a Joint Account | Choice Bank - API Documentation `POST` `/onboarding/applyForJointAccount` A joint account in a bank works like a regular bank account and is shared by two or more people (In Choice, 2 or 3 people). These accounts can be created permanently, for example, an account between two family members or spouses where both can deposit their salaries. It can also be created temporarily for a shorter period of time between two parties to collect funds. **Parameters** Parameters Type Description Required? `userId` String Channel user id Mandatory `mandate` Int 1. Singly 2. Anyone or survivor Mandatory `applicationForm` File Allow pdf or image Mandatory `applicationFormType` string pdf/image default image Optional `primaryOwnerInfo` object `firstName` String Full name Mandatory `middleName` String Middle name Optional `lastName` String Last name Mandatory `idType` Int Id type 101 - National ID 102 - Alien ID 103 - Passport Mandatory `idNumber` String Id number Mandatory `kraPin` String Kra pin number Mandatory `countryCode` String Country code Mandatory `mobile` String Mobile number Mandatory `email` String Email address Optional `idFrontSideFile` File Front side of the id Allow pdf and image Mandatory `idFrontSideFileType` string pdf/image, default image Optional `idBackSideFile` File Allow pdf and image Mandatory `idBackSideFileType` string pdf/image,default image Optional `kraPinFile` File Allow pdf and image Mandatory `kraPinFileType` string pdf/image,default image Optional **Response** 00000 Copy { "onboardingRequestId": "" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/open-a-joint-account#adding-a-joint-account-owner) Adding a joint account owner ------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/addJointAccountOwner` This endpoint will be used to request the addition of joint account holders. Account holders will be added one at a time This API can be called after the OTP has passed but before the onboarding request is approved. **Parameters** Parameters Type Description Required? `onboardingRequestId` String Onboarding request id Mandatory `firstName` String Full name Mandatory `middleName` String Middle name Optional `lastName` String Last name Mandatory `idType` Int 101 - National ID 102 - Alien ID 103 - Passport Mandatory `idNumber` String Id number Mandatory `kraPin` String Kra pin number Mandatory `countryCode` String Country code Mandatory `mobile` String Mobile number Mandatory `email` String Email address Optional `idFrontSideFile` File Front side of the id Allow pdf and image Mandatory `idFrontSideFileType` File pdf/image, default image Opyional `idBackSideFile` File Allow pdf and image Mandatory `idBackSideFileType` string pdf/image, default image Optional `kraPinFile` File Allow pdf and image Mandatory `kraPinFileType` string pdf/image default image Optional **Response** 00000 Copy { "memberId": "", returned for user to remove owner(s) in processing stage } [PreviousApply for multiple accounts](https://choice-bank.gitbook.io/choice-bank/account/sme-account/apply-for-multiple-accounts) [NextQuery Business Onboarding Request ID](https://choice-bank.gitbook.io/choice-bank/account/sme-account/query-business-onboarding-request-id) Last updated 28 days ago --- # Apply for inbound external payment channel (RTGS, EFT) | Choice Bank - API Documentation `POST` `/trans/applyExternalPaymentChannelInbound` This API is for BaaS clients to submit a collection request for their externally transferred funds via RTGS, EFT or SWIFT to allow crediting their accounts in Choice Bank Fields Type Description Required? `accountId` String The account number that is to be credited Mandatory `choiceReceivingBank` String The bank code of the external operational bank they used to send funds to. Please refer to API - [Query Operational Bank Account List](https://kgegjwnjseu.sg.larksuite.com/docx/QkOIdJINLoflB9xfR7FlMd3dgdd#doxlgiSjOt9axnuXM70CSGvONGh) Mandatory `choiceReceivingAccount` String Bank account number of the external operational bank that Choice utilises to receive funds Mandatory `paymentChannel` String The payment channel that the customer chooses to transfer the money to Choice's bank account.RTGSEFT Mandatory `payerBankCode` String bank code of transfer bank. Please refer to "**Bank Code**" column of the [Choice Bank Code List](https://n05mxbyps1.feishu.cn/sheets/shtcnFyw3Kroc5tHUniyUaEptwf) .NB: where this parameter is specified, the **payerBankName** parameter ought not to be supplied Conditional `payerBankName` String The name of the counterparty bankNB: where this parameter is specified, the **payerBankCode** parameter ought not to be supplied Conditional `payerAccount` String The account number of the counterparty (Sender) Mandatory `payerName` String The name of the counterparty (Sender) Optional `transactionDate` String Date of the transfer. Format: Unix timestamp Mandatory `transferReferenceNumber` String The reference number of the transfer that was generated by the sending bank Optional `transactionNarrative` String Transaction narrations if there's any Optional `supportDocument` File Contracts, source of funds or other supporting documents that the Bank may need to reference later.The file is expected to be coded in Base64 representation Mandatory `documentType` String Specify the file type of the support documentPDFImageIf this is not given, by default the type is PDF Optional `amount` String The amount of the transfer (also the amount that the account has to be credited with) Mandatory **Response** 00000 Copy { "applicationId": "", } [PreviousIMT Transfers](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers) [NextApply for outbound external payment channel (RTGS, EFT)](https://choice-bank.gitbook.io/choice-bank/others/merchant/apply-for-outbound-external-payment-channel-rtgs-eft) Last updated 28 days ago --- # IMT Transfers | Choice Bank - API Documentation Note: You require whitelisting to use this API. It's linked to your merchant account and does not require O**TP confirmation**. #### [](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers#new-api-initiate-imt-transfer-request) New API: Initiate IMT transfer request `POST` `/trans/applyForImtTransfer` < This is to be used specifically for sending remittances to M-PESA wallets> Fields Type Description Required `orgTxId` String Unique transaction ID generated by the partner’s system for tracking purposes. Mandatory `payerAccountId` String Identifier of the account to be debited for the transaction. Mandatory `ImtSenderName` String Full legal name of the ultimate sender (person initiating the remittance). I.e "Paul Kamau Kabuu". Ensure this format is followed - otherwise the transaction fails. Mandatory `imtSenderPhoneNumber` String Phone number of the ultimate sender, including country code. Mandatory `imtSenderServiceProvider` String Mobile network or service provider associated with the sender’s phone number. Mandatory `imtSenderNationality` String Nationality of the sender, represented in ISO 3166 Alpha-3 country code format (e.g., KEN for Kenya). Mandatory `imtSenderIdType` String Type of identification document used by the sender. Accepted values: 1 = Passport, 2 = National ID, 3 = Driver’s License, 4 = Diplomatic Passport. Defaults to `NULL` if not provided. Optional `imtSenderIdNumber` String Identification document number matching the `senderIdType`. Defaults to `NULL` if not provided. Optional `imtSenderBirthdate` String Date of birth of the sender in `yyyyMMdd` format. Defaults to `NULL` if not provided. Optional `imtFundsOriginCountryCode` String Country from which the funds are being remitted, in ISO 3166 Alpha-3 format. Mandatory `payeeAccountId` String The recipient’s M-PESA wallet number where the funds will be credited. Mandatory `payeeAccountName` String Full legal name of the recipient as registered on M-PESA. Mandatory `purpose` String Reason or purpose for the remittance (e.g., family support, business payment). Mandatory `imtForeignCurrency` String Details of the transaction: original currency, currency code(e.g., `"USD"`). Mandatory `imtConversionRate` String Details of the transaction: original conversion rate Mandatory `imtOriginalAmount` String Details of the transaction: original amount, Mandatory `ammount` String Transaction amount to be debited from the payer account and sent to the beneficiary. Mandatory `currency` String Currency code of the transaction. Only `KES` is supported. Mandatory `remark` String Additional transaction note or reference. Must be at least 2 characters long. Mandatory **Response** 00000 Copy { "txId": "", //unique, choice-generated transaction-id string } #### [](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers#new-api-imt-query) New API: IMT query `POST` `/trans/getImtTransferResult` orgTxId string Unique transaction ID generated by the partner’s system for tracking purposes. Optional txId string Unique transaction ID generated by the choice's system for tracking purposes. Optional **Response** 00000 Copy { "txId": "", //string, unique partner-generated transaction id "orgTxId": "", //string, unique partner-generated transaction id "payerAccountId": "", //string, identifier of account to be debited "payerAccountName": "", //string, registered name of account to be debited "beneficiaryAccountId": "", //string, recipient’s m-pesa wallet number where funds will be credited "benefeciaryAccountName": "", //string, full legal name of the recipient as registered on m-pesa "amount": "", //string, transaction amount to be debited "feeAmount": "", //string, transaction fee amount to be debited "externalTxId": "", //string, unique mpesa-generated transaction-id "txStatus": "", //int, transactions status, refer to txstatus definition "errorCode": "", //string, returned in case of unsuccessful transactions "errorMesaage": "", //string, offers more context on failure result "reversalTxId": "", //string, refund transaction id, in case of reversal request "completedTime": "", //string, time of transaction completion } #### [](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers#new-notification-imt-notification-0027) New Notification: IMT notification (0027) Copy { "requestId":"", //String, unique id of the notification which is generated by baas "sender":"", //String, sender id/ Channel ID of partner "locale":"en KE", //String, language config "timestamp":"", //long, notification send time. UTC Unix timestamp in millisecond. "salt":"", //String, salt "signature":"", //String, signature "params": { "txId":"", "orgTxId":"", "externalTxId":"", "payerAccountId":"", "payerAccountName":"", "payeeAccountId":"", "payeeAccountName":"", "currency":"", "amount":"", "feeAmount":"", "txStatus":"", "errorCode":"", "errorMsg":"", "completedTime":"" }, "notificationType":"0027", //String, notification type id } [](https://choice-bank.gitbook.io/choice-bank/others/merchant/imt-transfers#new-transaction-type) New transaction type --------------------------------------------------------------------------------------------------------------------------- TxType Definition TTID0025 IMT [PreviousMerchant](https://choice-bank.gitbook.io/choice-bank/others/merchant) [NextApply for inbound external payment channel (RTGS, EFT)](https://choice-bank.gitbook.io/choice-bank/others/merchant/apply-for-inbound-external-payment-channel-rtgs-eft) Last updated 11 days ago --- # Onboarding | Choice Bank - API Documentation [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#initiate-an-sme-onboarding-request) Initiate an SME Onboarding Request -------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/applyForSmeOnboarding` **Parameters** Parameters Type Description Is Required `userId` string A unique string to identify the user in the partner system. TRUE `countryCode` string The country code of the mobile, that the customer is using to onboard TRUE `mobile` string The mobile number that the customer is using to onboard TRUE `email` string Email address of the customer. When otpType == SMS, this is optional; When otpType == EMAIL, this is mandatory. FALSE `businessType` Integer Business type of the SME customer that is to onboard. 1 - Sole Proprietorship 2 - Limited Liability Company 3 - Partnership 4 - NGO / CBO TRUE `otpType` string Onboard an SME requires OTP confirmation. This determins the type of OTP that they want to receive to do OTP confirmation and onboard. Support values: SMS EMAIL TRUE **Response** 00000 Copy { "onboardingRequestId": "ONBOARD7695534567876" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#submit-basic-info-sole-proprietorship) Submit Basic Info - Sole Proprietorship ---------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/submitStoreOnboardingRequest` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `businessName` string Business's name TRUE `businessCerNum` string Business certificate number TRUE `firstName` string First name of the onboarding business owner TRUE `middleName` string middle name of the onboarding business owner FALSE `lastName` string last name of the onboarding business owner TRUE `birthday` string Date of Birth of the business owner; yyyy-MM-dd TRUE `gender` integer 0 - Female 1 - Male TRUE `idNumber` string ID Number of National ID/Passport/Alien ID TRUE `kraPin` string KRA PIN / Tax Number of the business (owner) TRUE `kinFullName` string The full name of the business owner's next kin TRUE `kinRelationship` string The relationship between the business owner and its next kin TRUE `kinCountryCode` string Country code of the business owner's next kin (mobile) TRUE `kinMobile` string Mobile number of the business owner's next kin TRUE `businessAddress` string Physical address of the onboarding business TRUE `businessIndustry` string This field captures the industry the business is operating in. Please submit the number representing the business sector. 1 - Agriculture and Agribusiness 2 - Manufacturing and Processing 3 - Construction and Engineering 4 - Retail and Wholesale Trade 5 - Information and Communication Technology 6 - Tourism and Hospitality 7 - Health and Wellness Services 8 - Education and Training 9 - Financial Services 10 - Professional Services 11 - Creative Industries 12 - Renewable Energy and Environmental Conservation 13 - Transport and Logistics 14 - Food and Beverage 15 - Textiles and Apparel 16 - Automotive and Engineering Services 17 - Beauty and Personal Care 18 - Real Estate and Property Development 19 - Consulting and Business Services 20 - Social Enterprises and NGOs 21 - Others, please specify TRUE `specifyIndustry` string When businessIndustry == Others, please specify, this field is Mandatory. FALSE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#submit-basic-info-llc) Submit Basic Info - LLC -------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/submitCompanyOnboardingRequest` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `businessName` string Business's name TRUE `businessCerNum` string Business certificate number TRUE `kraPin` string KRA PIN / Tax Number of the business TRUE `operatingMode` integer 1 - Singly 2 - Either to sign 3 - Any Two to Sign 4 - All of Us Jointly TRUE `businessAddress` string Physical address of the onboarding business TRUE `businessIndustry` string This field captures the industry the business is operating in. Please submit the number representing the business sector. 1 - Agriculture and Agribusiness 2 - Manufacturing and Processing 3 - Construction and Engineering 4 - Retail and Wholesale Trade 5 - Information and Communication Technology 6 - Tourism and Hospitality 7 - Health and Wellness Services 8 - Education and Training 9 - Financial Services 10 - Professional Services 11 - Creative Industries 12 - Renewable Energy and Environmental Conservation 13 - Transport and Logistics 14 - Food and Beverage 15 - Textiles and Apparel 16 - Automotive and Engineering Services 17 - Beauty and Personal Care 18 - Real Estate and Property Development 19 - Consulting and Business Services 20 - Social Enterprises and NGOs 21 - Others, please specify TRUE `specifyIndustry` string When businessIndustry == Others, please specify, this field is Mandatory. FALSE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#submit-basic-info-partnership) Submit Basic Info - Partnership ------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/submitPartnershipOnboardingRequest` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `businessName` string Business's name TRUE `businessCerNum` string Business certificate number TRUE `kraPin` string KRA PIN / Tax Number of the business TRUE `operatingMode` integer 1 - Singly 2 - Either to sign 3 - Any Two to Sign 4 - All of Us Jointly TRUE `businessAddress` string Physical address of the onboarding business TRUE `businessIndustry` string This field captures the industry the business is operating in. Please submit the number representing the business sector. 1 - Agriculture and Agribusiness 2 - Manufacturing and Processing 3 - Construction and Engineering 4 - Retail and Wholesale Trade 5 - Information and Communication Technology 6 - Tourism and Hospitality 7 - Health and Wellness Services 8 - Education and Training 9 - Financial Services 10 - Professional Services 11 - Creative Industries 12 - Renewable Energy and Environmental Conservation 13 - Transport and Logistics 14 - Food and Beverage 15 - Textiles and Apparel 16 - Automotive and Engineering Services 17 - Beauty and Personal Care 18 - Real Estate and Property Development 19 - Consulting and Business Services 20 - Social Enterprises and NGOs 21 - Others, please specify TRUE `specifyIndustry` string When businessIndustry == Others, please specify, this field is Mandatory. FALSE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#submit-basic-info-ngo-cbo) Submit Basic Info - NGO / CBO ------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/submitOrganisationOnboardingRequest` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `businessName` string Business's name TRUE `businessCerNum` string Business certificate number TRUE `kraPin` string KRA PIN / Tax Number of the business TRUE `operatingMode` integer 1 - Singly 2 - Either to sign 3 - Any Two to Sign 4 - All of Us Jointly TRUE `businessAddress` string Physical address of the onboarding business TRUE `businessIndustry` string This field captures the industry the business is operating in. Please submit the number representing the business sector. 1 - Agriculture and Agribusiness 2 - Manufacturing and Processing 3 - Construction and Engineering 4 - Retail and Wholesale Trade 5 - Information and Communication Technology 6 - Tourism and Hospitality 7 - Health and Wellness Services 8 - Education and Training 9 - Financial Services 10 - Professional Services 11 - Creative Industries 12 - Renewable Energy and Environmental Conservation 13 - Transport and Logistics 14 - Food and Beverage 15 - Textiles and Apparel 16 - Automotive and Engineering Services 17 - Beauty and Personal Care 18 - Real Estate and Property Development 19 - Consulting and Business Services 20 - Social Enterprises and NGOs 21 - Others, please specify TRUE `specifyIndustry` string When businessIndustry == Others, please specify, this field is Mandatory. FALSE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully" } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#add-shareholders-directors-individual) Add Shareholders / Directors (Individual) ------------------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/submitCompanyMember` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `idType` string 101 - (Kenya) National ID 102 - (Kenya) Alien ID 103 - Passport TRUE `idNumber` string ID number TRUE `gender` integer 0 - Female 1 - Male FALSE `email` string Email address FALSE `countryCode` string country code TRUE `mobile` string mobile number TRUE `firstName` string First name of the shareholder / director TRUE `middleName` string Middle name of the shareholder / director FALSE `lastName` string Last name of the shareholder / director TRUE `kraPin` string KRA PIN / Tax Number of the shareholder / director TRUE `idFrontSideFile` string Base 64 string TRUE `idFrontSideFileType` string image pdf TRUE `idBackSideFile` string Base 64 string TRUE `idBackSideFileType` string image pdf TRUE `selfieFile` string Base 64 string TRUE `selfieFileType` string image pdf TRUE `kraPinFile` string Base 64 string TRUE `kraPinFileType` string image pdf TRUE **Response** 00000 Others Copy { "memberId": "", } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#add-shareholders-directors-organization) Add Shareholders / Directors (Organization) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/submitShareholderCompanyMember` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string A unique string generated by Choice to identify a certain onboarding request TRUE `registrationFile` string Base 64 string TRUE `registrationFileType` string image pdf TRUE `companyName` string Company name TRUE **Response** 00000 Others Copy { "companyId": "", } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#remove-shareholders-directors) Remove Shareholders / Directors ------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/removeMember` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE `memberId` String For individual type of shareholders/directors, it's the memberId; For organization type, it's companyId. TRUE `memberType` Int 0 - Individual 1 - Organization TRUE **Response** 00000 Others Copy { "code": "00000", "msg": "Completed successfully", } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#upload-onboarding-media-materials) Upload Onboarding Media Materials ------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/uploadMedia` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String Onboarding request ID received when the general information was submitted. TRUE `mediaBase64` String BASE64 text of upload document TRUE `mediaType` String Please refer to [Business Customer Onboarding Document Definition](https://mib.feishu.cn/sheets/VHbKsKO9RhA0X6tNLVFcQqUMnGc?sheet=oRfchs) on the File type definition sheet for details. TRUE `contentType` String Type of the file uploaded. You can place * pdf * image If this parameter is not specified, the system will treat it as an image which is the default type. FALSE **Response** 00000 Others Copy { "fileId": "", //returned for all successful file uploads } Copy { "code": "12005", "msg": "Invalid signature" } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#remove-onboarding-media-materials) Remove Onboarding Media Materials ------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/removeMedia` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE `fileId` String The ID of the file that is to be removed TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#submit-pull-back-onboarding-request) Submit / Pull Back Onboarding Request ------------------------------------------------------------------------------------------------------------------------------------------------------------ `POST` `/onboarding/business/submitOrPullBackRequest` When a customer completes an onboarding by submitting all relevant details and documents, the onboarding status changes from Processing to Manual Review. At this point, the customer will not have the ability to make further changes to the onboarding request. This endpoint can be used to request the status to be changed from manual review to processing to allow for amendments to be made to the onboarding request (maybe edit data fields or re-upload document(s)) Once this endpoint returns a success response, you can now call the Business onboarding endpoints again to resubmit data/documents. After ammendments and resubmissions are complete, please call this endpoint again to indicate you have completed the ammendments. The system will change the status from Processing to Manual review. **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE `action` String 0 - to request amemdments 1 - to submit/complete onboarding TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#cancel-onboarding-request) Cancel Onboarding Request -------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/cancelOnboardingRequest` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE **Response** 00000 Copy { "code": "00000", "msg": "Completed successfully", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#query-onboarding-info-sole-proprietor) Query Onboarding Info - Sole Proprietor ---------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/getStoreOnboardingInfo` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE **Response** 00000 Copy { "onboardingRequestId": "00000", "smeName": "", "businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO "countryCode": "", "mobile": "", "email": "", "krapin": "", "businessCertificateNumber": "", "channel": "", "channelUserId": "", "ownerFullName": "", "ownerIdNumber": "", "ownerIdType": "", "ownerBirthDay": "", "kinFullName": "", "kinCountryCode": "", "kinMobile": "", "kinRelationship": "", "onboardingMediaInfos": [\ {\ "fileUrl": "",\ "mediaType": "",\ "contentType": "",\ "fileTypeId": "",\ "fileKey": "",\ "fileId": "",\ }\ ], "status": "", "rejectReasonIds": [\ ], "rejectReasonMsgs": [\ ], "createTime": "", "auditTime": "", "businessIndustry": "", "specifyIndustry": "", "businessAddress": "", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#query-onboarding-info-llc) Query Onboarding Info - LLC ---------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/getCompanyOnboardingInfo` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE **Response** 00000 Copy { "onboardingRequestId": "00000", "smeName": "", "businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO "countryCode": "", "mobile": "", "email": "", "krapin": "", "businessCertificateNumber": "", "channel": "", "channelUserId": "", "onboardingMediaInfos": [\ {\ "fileUrl": "",\ "mediaType": "",\ "contentType": "",\ "fileTypeId": "",\ "fileKey": "",\ "fileId": "",\ }\ ], "shareholdersMemberInfos": [\ {\ "memberId": "",\ "countryCode": "",\ "mobile": "",\ "idType": "",\ "idNumber": "",\ "firstName": "",\ "middleName": "",\ "lastName": "",\ "fullName": "",\ "kraPin": "",\ "idFrontFileUrl": "",\ "idFrontFileType": "",\ "selfieFileUrl": "",\ "selfieFileType": "",\ "idBackFileUrl": "",\ "idBackFileType": "",\ "kraPinFileUrl": "",\ "kraPinFileType": "",\ }\ ], "shareholdersCompanyInfos": [\ {\ "companyId": "",\ "companyName": "",\ "registrationFileKey": "",\ "registrationFileUrl": "",\ "registrationFileType": "",\ }\ ], "status": "", "rejectReasonIds": [\ ], "rejectReasonMsgs": [\ ], "createTime": "", "auditTime": "", "businessIndustry": "", "specifyIndustry": "", "businessAddress": "", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#query-onboarding-info-ngo-cbo) Query Onboarding Info - NGO / CBO -------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/getOrganisationOnboardingInfo` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE **Response** 00000 Copy { "onboardingRequestId": "00000", "smeName": "", "businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO "countryCode": "", "mobile": "", "email": "", "krapin": "", "businessCertificateNumber": "", "channel": "", "channelUserId": "", "onboardingMediaInfos": [\ {\ "fileUrl": "",\ "mediaType": "",\ "contentType": "",\ "fileTypeId": "",\ "fileKey": "",\ "fileId": "",\ }\ ], "shareholdersMemberInfos": [\ {\ "memberId": "",\ "countryCode": "",\ "mobile": "",\ "idType": "",\ "idNumber": "",\ "firstName": "",\ "middleName": "",\ "lastName": "",\ "fullName": "",\ "kraPin": "",\ "idFrontFileUrl": "",\ "idFrontFileType": "",\ "selfieFileUrl": "",\ "selfieFileType": "",\ "idBackFileUrl": "",\ "idBackFileType": "",\ "kraPinFileUrl": "",\ "kraPinFileType": "",\ }\ ], "shareholdersCompanyInfos": [\ {\ "companyId": "",\ "companyName": "",\ "registrationFileKey": "",\ "registrationFileUrl": "",\ "registrationFileType": "",\ }\ ], "status": "", "rejectReasonIds": [\ ], "rejectReasonMsgs": [\ ], "createTime": "", "auditTime": "", "businessIndustry": "", "specifyIndustry": "", "businessAddress": "", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#query-onboarding-info-partnership) Query Onboarding Info - Partnership -------------------------------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/getPartnershipOnboardingInfo` **Parameters** Parameters Type Description Is Required `onboardingRequestId` String A unique string generated by Choice to identify a certain onboarding request TRUE **Response** 00000 Copy { "onboardingRequestId": "00000", "smeName": "", "businessType": "", //1-Sole Proprietorship; 2-LLC; 3-Partnership; 5-NGO/CBO "countryCode": "", "mobile": "", "email": "", "krapin": "", "businessCertificateNumber": "", "channel": "", "channelUserId": "", "onboardingMediaInfos": [\ {\ "fileUrl": "",\ "mediaType": "",\ "contentType": "",\ "fileTypeId": "",\ "fileKey": "",\ "fileId": "",\ }\ ], "shareholdersMemberInfos": [\ {\ "memberId": "",\ "countryCode": "",\ "mobile": "",\ "idType": "",\ "idNumber": "",\ "firstName": "",\ "middleName": "",\ "lastName": "",\ "fullName": "",\ "kraPin": "",\ "idFrontFileUrl": "",\ "idFrontFileType": "",\ "selfieFileUrl": "",\ "selfieFileType": "",\ "idBackFileUrl": "",\ "idBackFileType": "",\ "kraPinFileUrl": "",\ "kraPinFileType": "",\ }\ ], "shareholdersCompanyInfos": [\ {\ "companyId": "",\ "companyName": "",\ "registrationFileKey": "",\ "registrationFileUrl": "",\ "registrationFileType": "",\ }\ ], "status": "", "rejectReasonIds": [\ ], "rejectReasonMsgs": [\ ], "createTime": "", "auditTime": "", "businessIndustry": "", "specifyIndustry": "", "businessAddress": "", } [](https://choice-bank.gitbook.io/choice-bank/account/sme-account/onboarding#query-onboarding-status) Query Onboarding Status ---------------------------------------------------------------------------------------------------------------------------------- `POST` `/onboarding/business/getBusinessOnboardingStatus` **Parameters** Parameters Type Description Is Required `onboardingRequestId` string The unique onboarding request id that was returned from Choice system. FALSE `businessCerNo` string Company/Organisation's incorporation certificate number. Either `onboardingRequestId` or `businessCerNo` is mandatory. FALSE **Response** 00000 Others Copy { "onboardingRequestId": "ONBOARD2309LKSD90432", "onboardingStatus": "Completed successfully", "rejectionReasonIds": [\ ], "rejectReasonMsgs": [\ ], "accountId": "46013xxxxxxxxx", "accountType": "", "auditTime": "", } Copy { "code": "12005", "msg": "Invalid signature" } [PreviousSME Account](https://choice-bank.gitbook.io/choice-bank/account/sme-account) [NextAccount Administrator](https://choice-bank.gitbook.io/choice-bank/account/sme-account/account-administrator) Last updated 19 days ago --- # Deposit from M-PESA | Choice Bank - API Documentation Deposit from M-PESA | Choice Bank - API Documentation --- # Confirm OTP | Choice Bank - API Documentation Confirm OTP | Choice Bank - API Documentation --- # Callback and IP Whitelisting | Choice Bank - API Documentation Callback and IP Whitelisting | Choice Bank - API Documentation ---