Terminal Onboarding

Terminal activation and integration with Malawi Revenue Authority (MRA) EIS system. Manage terminal setup, JWT token acquisition, and security configuration for Malawi-based businesses.

📌 Activation flow

Activate with the activation code MRA issued for the terminal (e.g. 816Q-3VZP-6ZZY-K9Y5) and the device and POS platform details.
Confirm the activation using the returned terminalId.
List terminals whenever you need a terminal's ID, site or status.

WEAF stores the MRA JWT and secret key for each terminal, so you only ever send the terminalId. When MRA reports an expired session (401 or statusCode -2), request a new terminal token.

Endpoints in this section

Activate terminal

🚀 Try it

POST/api/v1/{tin}/activate-terminal🔒 token required

Activate a new terminal with Malawi Revenue Authority (MRA) EIS system. Returns JWT tokens and security configurations on success.

Parameters

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

Request Body

Field	Type	Required	Description
`terminalActivationCode`	string	Yes	Activation code provided by MRA Example: `816Q-3VZP-6ZZY-K9Y5`
`platformInfo`	object	Yes
`platformInfo.platform`	object	Yes
`platformInfo.platform.osName`	string	No	Example: `Microsoft Windows 10 Pro`
`platformInfo.platform.osVersion`	string	No	Example: `10.0.19045`
`platformInfo.platform.osBuild`	string	No	Example: `19045`
`platformInfo.platform.macAddress`	string	No	Example: `2E-CF-D9-E8-84-EE`
`platformInfo.pos`	object	Yes
`platformInfo.pos.productID`	string	No	Example: `sera`
`platformInfo.pos.productVersion`	string	No	Example: `v3.0`

Responses

200Terminal activated successfully
400Activation failed
401Unauthorized - Invalid or missing Bearer token
403Forbidden - Company mismatch or account inactive

Confirm terminal activation

🚀 Try it

POST/api/v1/{tin}/confirm-terminal-activation🔒 token required

Confirm a terminal activation with Malawi Revenue Authority (MRA) EIS system. This finalizes the terminal setup after initial activation.

Parameters

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

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Terminal ID to confirm Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`

Responses

200Terminal confirmation successful
400Confirmation failed
401Unauthorized - Invalid or missing Bearer token
403Forbidden - Company mismatch or account inactive

Get configured terminals

🚀 Try it

GET/api/v1/{tin}/terminals🔒 token required

Retrieve all configured and activated terminals for a given TIN from the WEAF backend database.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`token`	query	Yes	API access token for authentication

Responses

200Terminals retrieved successfully
401Unauthorized - Invalid or missing Bearer token
403Forbidden - Company mismatch or account inactive

Request New Terminal Token

🚀 Try it

POST/api/v1/{tin}/request-new-terminal-token🔒 token required

Retrieve the latest terminal security credentials (JWT token and Secret Key) from the MRA system. This is required when your current session has expired (indicated by a 401 Unauthorized response or MRA statusCode -2). The local database is automatically updated with the new credentials.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number (e.g., 20154457)
`deploymentEnvironment`	query	No	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	The site ID of the terminal to refresh tokens for Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`

Responses

200Terminal tokens retrieved and updated successfully
400Failed to retrieve tokens or missing required fields
401MRA Session Expired: You are not authorised.
404Company or Terminal not found