Utilities

Common utility endpoints like warehouse product retrieval and security configuration.

Lookups and health checks to run around a sale: whether a buyer TIN needs an authorisation code, whether a VAT5 certificate is valid, and whether a terminal is blocked and why.

Endpoints in this section

Get terminal site products

🚀 Try it

POST/api/v1/{tin}/get-site-terminal-products🔒 token required

Retrieve products and services for a specific terminal site from Malawi Revenue Authority (MRA) EIS system.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	Site ID from terminal configuration Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`terminalId`	string	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Products retrieved successfully
400Bad request - invalid parameters
404Terminal not found or not activated

Get warehouse products

🚀 Try it

POST/api/v1/{tin}/get-warehouse-products🔒 token required

Retrieve warehouse inventory products with pagination from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal with valid JWT credentials.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' for testing or 'Production' for live One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`page`	integer	No	Page number for pagination Example: `1`
`pageSize`	integer	No	Number of items per page Example: `50`

Responses

200Warehouse products retrieved successfully
400Bad request - invalid parameters or missing terminal credentials
404Terminal not found - Please activate the terminal first

Check TIN Authorization Requirement

🚀 Try it

POST/api/v1/{tin}/check-tin-authorization-requirement🔒 token required

Check if a specific TIN requires a purchase authorization code from the Malawi Revenue Authority (MRA).

Parameters

Name	In	Required	Description
`tin`	path	Yes	Sellers's TIN (the authenticated company)
`deploymentEnvironment`	query	No	MRA environment (Sandbox or Production) One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	Site ID of the terminal to use for authorization Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`target_tin`	string	Yes	The TIN to check for authorization requirement Example: `12345678`

Responses

200Status retrieved successfully
401Unauthorized or Session Expired
404Terminal not found

Check Terminal Unblock Status

🚀 Try it

POST/api/v1/{tin}/check-terminal-unblock-status🔒 token required

Check if a specific terminal is currently unblocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (Authenticated company)
`deploymentEnvironment`	query	No	MRA environment (Sandbox or Production) One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	Site ID of the terminal to check Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`terminalId`	string	No	Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication. Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Unblock status retrieved successfully
401Unauthorized or Session Expired
404Terminal not found

Get Terminal Blocking Message

🚀 Try it

POST/api/v1/{tin}/get-terminal-blocking-message🔒 token required

Retrieve detailed information about why a terminal might be blocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (Authenticated company)
`deploymentEnvironment`	query	No	MRA environment (Sandbox or Production) One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	Site ID of the terminal to check Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`terminalId`	string	No	Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication. Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Blocking details retrieved successfully
401Unauthorized or Session Expired
404Terminal not found

Validate VAT5 Certificate

🚀 Try it

POST/api/v1/{tin}/validate-vat5-certificate🔒 token required

Validate a VAT5 certificate with the Malawi Revenue Authority (MRA) EIS system. This check ensures the certificate is valid, matches the project and terminal, and hasn't exceeded its quantity.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	Yes	MRA deployment environment - 'Sandbox' or 'Production' One of: Sandbox, Production
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	Site ID of the terminal to use Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`terminalId`	string	No	Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication. Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`projectNumber`	string	Yes	VAT5 Project Number Example: `PRJ-2024-001`
`certificateNumber`	string	Yes	VAT5 Certificate Number Example: `VAT5-987654`
`quantity`	number	Yes	Quantity being validated against the certificate Example: `100`

Responses

200Certificate validation response from MRA
401Unauthorized or Session Expired
403Terminal Blocked
404Terminal not found