Account Management

Query Account Details

POST /query/getAccountDetails

<This endpoint allows you to query a certain account's details>

Parameters

Parameters	Type	Description	Is Required
accountId	string	The number of the account that you want to query the details of.	TRUE

Response

00000

{
  "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
}

Get All Accounts of a Client

POST /account/queryAccountListByUserId

<This endpoint allows you to get all accounts of a certain client>

Parameters

Parameters	Type	Description	Is Required
userId	string	The unique string to identify the user in the BaaS partner system.	TRUE

Response

00000

{
  "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;
    }
  ]
}

Get Abnormal Account List

POST /query/getAbnormalAccountList

<This endpoint allows you to get all abnormal accounts in BaaS partner's channel>

Parameters

Parameters	Type	Description	Is Required
pageNo	int	Page number	TRUE
pageSize	int	Page size	TRUE

Response

00000

{
  "total": "",
  "resultArray": [
    {
      "userId": "",
      "accountId": "",
      "accountType": "",
      "status": [
        {1},
        {2},
        //Abnormal status; 1-Dormant; 2-Restricted; 3-Frozen
      ]
    }
  ]
}

Apply for Short Code

POST /account/applyForShortCode

<This endpoint allows end users to apply for a shortcode for its account>

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

{
  "accountId": "", 
  "shortCode": "", //generated shortcode
}

Query Shortcode By AccountId

POST /account/queryForShortCode

<This endpoint allows you to query shortcode using account number>

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

{
  "accountId": "", 
  "shortCode": "",
}

Query AccountId By Shortcode

POST /account/queryAccountByShortCode

<This endpoint allows you to query accountId by shortcode>

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

{
  "accountId": "", 
  "shortCode": "", 
}

Activate Dormant Account

POST /account/activateAccount

<This endpoint allows you to activate dormant account (account inactive above 6 months)>

Parameters

Parameters	Type	Description	Is Required
accountId	string	The number of the dormant account that the user wants to activate.	TRUE

Response

00000

{
  "accountId": "", 
  "shortCode": "", 
}

Add Email

POST /user/addOrUpdateEmail

<This endpoint allows end users to add Email information if they didn't fill in Email when they were onboarding, or update Email information if it's changed>

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

{
  "applicationId": "",
}

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

{
  "applicationId": "", //requestId returned by the baas api.
}

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.

Verify Email Address

POST /account/verifyEmailAddress

<To receive OTP through email, the BaaS accounts will require the existing email specified at the time of onboarding to be verified. Only verified emails will qualify to receive OTP.

When a verify request is completed, the verification code will be sent to the email address.

The user will be required to enter the received email verification code in the BaaS server using the verify OTP API to complete the email address verification process.>

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

{
  "applicationId": "",
}

Verify Email or Mobile

POST /account/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

{
  "applicationId": "",
}

Edit SME Sub-Account/VA Name

POST /account/editSubAccountName

<This endpoint allows SME customers to edit its sub-account/virtual account's name>

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

{
  "applicationId": "",
}

Cancel Account Operation

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	Request or application to be cancelled	TRUE

Response

00000

{
  "code": "00000",
  "msg": "Completed successfully"
}