March Release Notes

Hello Everyone, Please, find the release notes!

This document outlines upcoming changes to Mbanq’s APIs, which will take effect from 15th March 2025. These updates are in compliance with the Sponsor Bank’s new guidelines on client information sharing. As part of this mandate, specific parameters must be transmitted to the Sponsor Bank on a daily basis.

📅 Key Dates

15th March 2025 – Mandatory go-live date for all platforms
3rd March 2025 – Sandbox availability for testing

🚨 Affected APIs

The following APIs will be updated. For each, the corresponding API documentation link is provided:

API Group	API Document Link
AUTH API	https://apidocs.cloud.mbanq.com/reference/requestaccesstoken
Get Client Template API	https://apidocs.cloud.mbanq.com/reference/getclienttemplate
Create Client API	https://apidocs.cloud.mbanq.com/reference/createclient
Edit Client API	https://apidocs.cloud.mbanq.com/reference/updateclient
Get Client API	https://apidocs.cloud.mbanq.com/reference/getclientbyid
Create Client Document Record API	https://apidocs.cloud.mbanq.com/reference/createclientidentifier-1
Edit Client Document Record API	https://apidocs.cloud.mbanq.com/reference/editclientidentifier
List Client Document Record API	https://apidocs.cloud.mbanq.com/reference/listclientidentifiers

This document provides a comparison between the existing payload and the updated payload, clearly highlighting the changes made.
The goal is to ensure clarity on how the data structure has evolved and what modifications have been implemented.

👥 Impact of API Usage on Clientele Base

🆕 New Clients

The updated APIs will be used to onboard new customers to the platform, ensuring they are integrated using the most current data structure and functionality.

♻️ Existing Clients

For customers onboarded on and after 1st January 2025, the platform will:

Share an XLS or JSON file containing the relevant client data with the Mbanq team
The Mbanq team will manually update the records in the system
This ensures legacy customer data aligns with the new API structure

1. 🔐 AUTH API

Affected API Endpoint: /oauth/token
Method: POST
Type of Change: Modification
API Doc: Request Access Token
Note: Passing headers in the AUTH API is only necessary if the user credentials are stored and managed on Mbanq.

📝 Description of Change

The IP address and device identifier (such as device ID or browser fingerprint) of the devices (mobile or system) used by end customers must be captured and sent using this API each time the user logs in or authenticates.

Description	Example
New Headers	X-FORWARDED-FOR : 222.12.211.12 -- New X-DEVICE-FINGERPRINT : 09BD47A5-9380-40E3-AFF8-592D5E433 -- New

Definitions

Field	Type	Optional	Description
X-FORWARDED-FOR	string	required	The IP address refers to the numerical label assigned to the device used during the account opening process. It identifies the device's location on a network and is used for tracking and verifying the origin of the account activity.
X-DEVICE-FINGERPRINT	string	required	A device ID/browser fingerprint is a unique identifier generated by analyzing various attributes of a user's browser and device configuration. The resulting fingerprint is a single, distinctive string that represents the combination of these attributes, allowing for the identification of the browser or device.

2. Get Client Template

Affected API Endpoint(s): /v1/clients/template
Method: GET
Type of Change: Modification
API Doc: Create Client

Description of Change

When adding a new client, their occupation or designation must be captured. The selection should be made from a predefined list of occupations/designations. If the provided occupation does not match any value in the predefined list, it should be categorized as "Others".

Status Code	Sample Response
200	{ "clientOccupationOptions": [ ---New { "id": 10013, "name": "Sales Executive", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false }, { "id": 10014, "name": "Marketing Executive", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false }, { "id": 10015, "name": "Professor", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false }, { "id": 10015, "name": "Driver", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false }, { "id": 10015, "name": "Others", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false } ] }

Status Code

Sample Response

200

{
"clientOccupationOptions": [ ---New
{
"id": 10013,
"name": "Sales Executive",
"position": 0,
"description": "",
"active": true,
"mandatory": false,
"systemDefined": false,
"parentId": 0,
"codeName": "Occupation",
"isMasked": false
},
{
"id": 10014,
"name": "Marketing Executive",
"position": 0,
"description": "",
"active": true,
"mandatory": false,
"systemDefined": false,
"parentId": 0,
"codeName": "Occupation",
"isMasked": false
},
{
"id": 10015,
"name": "Professor",
"position": 0,
"description": "",
"active": true,
"mandatory": false,
"systemDefined": false,
"parentId": 0,
"codeName": "Occupation",
"isMasked": false
},
{
"id": 10015,
"name": "Driver",
"position": 0,
"description": "",
"active": true,
"mandatory": false,
"systemDefined": false,
"parentId": 0,
"codeName": "Occupation",
"isMasked": false
},
{
"id": 10015,
"name": "Others",
"position": 0,
"description": "",
"active": true,
"mandatory": false,
"systemDefined": false,
"parentId": 0,
"codeName": "Occupation",
"isMasked": false
}
]
}

3. Create Client API

Affected API Endpoint: /v1/clients
Method: POST
Type of Change: Modification
API Doc: Create Client

Description of Change

The client’s occupation needs to be captured upon onboarding a new client. The IP address and device identifier (device ID or browser fingerprint) of the devices (mobile or system) used by end customers must be captured and sent using this API each time the end client is onboarding either via mobile app or browser.

Description	Example
New Headers	X-FORWARDED-FOR : 222.12.211.12 -- New X-DEVICE-FINGERPRINT : 09BD47A5-9380-40E3-AFF8-592D5E433 -- New

Definitions

Field	Example
New Payload	{ "address": [], "familyMembers": [], "officeId": 3, "isStaff": true, "staffId": null, "legalFormId": 1, "firstname": "john", "lastname": "doe", "occupationId": 31, // NEW "active": false, "dateFormat": "dd MMMM yyyy", "activationDate": "18 February 2025", "submittedOnDate": "18 February 2025", "savingsProductId": null }

Field

Example

New Payload



{


"address": [],


"familyMembers": [],


"officeId": 3,


"isStaff": true,


"staffId": null,


"legalFormId": 1,


"firstname": "john",


"lastname": "doe",


"occupationId": 31,     // NEW


"active": false,


"dateFormat": "dd MMMM yyyy",


"activationDate": "18 February 2025",


"submittedOnDate": "18 February 2025",


"savingsProductId": null


}

4. Edit Client API

Affected API Endpoint: /v1/clients/{clientId}
Method: PUT
Type of Change: Modification
API Doc: Update Client

Description of Change

The client’s occupation needs to be captured upon editing/updating the personal information of a client if the occupation is changed.

Field	Example
New Payload	{ "legalFormId": 1, "firstname": "john", "lastname": "doe", "occupationId": 31, -- New "emailAddress": "[email protected]", "mobileCountryCode": "+1", "mobileNo": "9999888777", "dateOfBirth": "05 May 1993", "submittedOnDate": "29 January 2025", "activationDate": "29 January 2025", "isStaff": false, "isOptedForMLAStatus": false, "currentMLAStatus": "", "genderId": 634, "clientNonPersonDetails": { "incorpValidityTillDate": "" }, "active": true, "locale": "en", "dateFormat": "dd MMMM yyyy" }

Field

Example

New Payload



{


"legalFormId": 1,

"firstname": "john",

"lastname": "doe",

"occupationId": 31,               -- New

"emailAddress": "[email protected]",

"mobileCountryCode": "+1",

"mobileNo": "9999888777",

"dateOfBirth": "05 May 1993",

"submittedOnDate": "29 January 2025",

"activationDate": "29 January 2025",

"isStaff": false,

"isOptedForMLAStatus": false,

"currentMLAStatus": "",

"genderId": 634,

"clientNonPersonDetails": {

"incorpValidityTillDate": ""

},

"active": true,

"locale": "en",

"dateFormat": "dd MMMM yyyy"

}

Definitions for New Fields Above

Field	Type	Optional	Description
`occupationId`	integer	required	The occupation refers to the profession, job title, or primary field of work of the account holder. This information provides insight into the account holder's employment status and industry.

5. Get Client API

Affected API Endpoint: v1/clients
Method: GET
Type of Change: Modification
API Doc: Get Client Details

Description of Change

The client's occupation information will be included in the response along with other fields.

Status Code	Sample Response
200	-- New Section occupation "occupation": { "id": 10013, "name": "Sales Executive", "position": 0, "description": "", "active": true, "mandatory": false, "systemDefined": false, "parentId": 0, "codeName": "Occupation", "isMasked": false },

Status Code

Sample Response

200






-- New Section occupation

"occupation": {

"id": 10013,

"name": "Sales Executive",

"position": 0,

"description": "",

"active": true,

"mandatory": false,

"systemDefined": false,

"parentId": 0,

"codeName": "Occupation",

"isMasked": false

},

6. Create Client Document Record API

Affected API Endpoint: /v1/clients/{clientId}/identifiers
Method: POST
Type of Change: Modification
API Doc: Create Client Identifier

Description of Change

The issuedDate (client document issued date) must be recorded when adding a new client document record.

Field	Example
New Payload	{ "locale": "en", "dateFormat": "dd MMMM yyyy", "documentTypeId": 646, "status": "ACTIVE", "documentKey": "34543543", "description": " 43534543", "expiryDate": "18 February 2025", "issuedBy": "US Gov", "issuedDate": "8 February 2020" -- New }

Field

Example

New Payload



{


"locale": "en",

"dateFormat": "dd MMMM yyyy",

"documentTypeId": 646,

"status": "ACTIVE",

"documentKey": "34543543",

"description": "  43534543",

"expiryDate": "18 February 2025",

"issuedBy": "US Gov",

"issuedDate": "8 February 2020"      -- New

}

7. Edit Client Document Record API

Affected API Endpoint: /v1/clients/{clientId}/identifiers/{identifierId}
Method: PUT
Type of Change: Modification
API Doc: Edit Client Document Record

Description of Change

The issuedDate (client document issued date) must be recorded when updating a client document record.

Field	Example
New Payload	{ "locale": "en", "dateFormat": "dd MMMM yyyy", "documentTypeId": 646, "status": "ACTIVE", "documentKey": "34543543", "description": " 43534543", "expiryDate": "18 February 2025", "issuedBy": "US Gov", "issuedDate": "8 February 2020" -- New }

Field

Example

New Payload



{


"locale": "en",

"dateFormat": "dd MMMM yyyy",

"documentTypeId": 646,

"status": "ACTIVE",

"documentKey": "34543543",

"description": "  43534543",

"expiryDate": "18 February 2025",

"issuedBy": "US Gov",

"issuedDate": "8 February 2020"       -- New

}

Definitions for New Fields Above

Field	Type	Optional	Description
`issuedDate`	string	required	Represents the date when a document or identifier was issued. This date is critical for tracking the validity period of certain documents, such as passports and licenses, and can also be used to ensure that documents are up to date

8. List Client Document Records API

Affected API Endpoint: v1/clients/{clientId}/identifiers
Method: GET
Type of Change: Modification
API Doc: List Client Document Records

Description of Change

The issuedDate of the client identifier will be included in the response along with other fields.

Status Code	Sample Response
200	issuedDate": "2025-03-03 02:05:13" -- New

Migration Plan

The API changes will be available in the Stage environment starting March 4, 2025, and will become mandatory in production from March 15, 2025.
For existing clients onboarded on the Mbanq platform on or after January 1, 2025, fintech partners are requested to submit the XLS file following the example provided below

June 2024

June 2024 - We have updated our API Guides to make them more comprehensive both technically and from a business user's perspective. In many places we have added business process descriptions that provide explanations for financial service processes. These updated guides should aid you in getting your Mbanq integration up and running more quickly.