Sales Management

Sales transaction and tax receipt generation for Malawi EIS.

Tax rates

taxRateId	Name	Rate
`A`	Standard Rated	16.5%
`B`	Zero Rated	0%
`E`	Exempt	0%

💡 How prices are treated

unitPrice is the VAT-inclusive shelf price. VAT is back-calculated as total × rate ÷ (100 + rate).
discount takes an amount (100.50) or a percentage ("10%").
You don't send totalVAT, taxableAmount or an invoiceSummary. They are computed from the line items.
The DEBUG endpoints return the exact MRA payload without submitting it. Use them to check calculations.

Endpoints in this section

Generate Tax Receipt

🚀 Try it

POST/api/v1/{tin}/generate-tax-receipt🔒 token required

Submit a sales transaction to the Malawi Revenue Authority (MRA) EIS system. This endpoint simplifies the integration process by handling complex tax calculations, invoice numbering, and MRA data formatting automatically.

🚀 Overview

The WEAF MRA API takes away the burden of calculating VAT, taxable amounts, and constructing the complex invoiceSummary object. You only need to provide basic transaction details, and our backend handles the rest, ensuring compliance with MRA EIS standards.

📋 Prerequisites

Valid API Access Token: Use the Authentication endpoints to obtain one.
TIN Configuration: Your company TIN must be added and activated in your account.
Terminal Setup: A terminal must be activated (terminalId) to provide the necessary MRA credentials.
Site ID: The site ID where the transaction originated.

📊 Global Configuration - Tax Rates

The following tax rates are supported by the MRA EIS system and should be used in the taxRateId field:

ID	Tax Rate Name	Rate %	Charge Mode
A	Standard Rated	16.5%	Item
B	Zero Rated	0%	Item
E	Exempt	0%	Item

⚡ Simplification & Automation

Auto-Calculations: You don't need to specify totalVAT, taxableAmount, or construct the invoiceSummary object. Our system calculates these based on your line items.
Flexible Discounts: The discount field accepts both absolute amounts (e.g., 100.50) and percentage strings (e.g., '10%').
VAT-Inclusive Pricing: Provide the regular shelf price in unitPrice. The system automatically back-calculates VAT using the formula: totalVAT = (total * rate) / (100 + rate).

🛠️ Business Logic & Validations

Duplicate Prevention: Requests with the same referenceNo and terminalId are blocked to prevent duplicate invoice generation.
Terminal Scoping: Each request is strictly scoped to the provided terminal and site, ensuring data integrity.
Invoice Numbering: Unique MRA-compliant invoice numbers are generated server-side.

⚠️ Important Notes

Testing: Use the deploymentEnvironment query parameter (Sandbox or Production) to switch between MRA instances.
Payload: Keep your request payload clean; only the simplified fields listed in the request schema are required.
Logging: All requests and responses are logged for audit and troubleshooting.

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 (used to fetch JWT token) Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`referenceNo`	string	Yes	Your internal reference number Example: `REF-1001`
`invoiceHeader`	object	Yes
`invoiceHeader.invoiceDateTime`	string (date-time)	No	Example: `2026-03-25T19:56:03.000Z`
`invoiceHeader.sellerTIN`	string	No	Example: `20154457`
`invoiceHeader.siteId`	string	No	Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`invoiceHeader.globalConfigVersion`	integer	No	Example: `1`
`invoiceHeader.taxpayerConfigVersion`	integer	No	Example: `1051`
`invoiceHeader.terminalConfigVersion`	integer	No	Example: `1`
`invoiceHeader.paymentMethod`	string	No	Example: `Cash`
`invoiceHeader.buyerTIN`	string	No	Buyer's Taxpayer Identification Number Example: `12345678`
`invoiceHeader.buyerName`	string	No	Buyer's Legal Name Example: `John Doe`
`invoiceHeader.buyerAuthorizationCode`	string	No	MRA-issued Authorization Code for the buyer Example: `AUTH-999`
`invoiceHeader.isExport`	boolean	No	Example: `false`
`invoiceHeader.isReliefSupply`	boolean	No	Example: `false`
`invoiceHeader.vat5CertificateDetails`	object	No
`invoiceHeader.vat5CertificateDetails.id`	integer	No	Example: `0`
`invoiceHeader.vat5CertificateDetails.projectNumber`	string	No	Example: `PRJ-123`
`invoiceHeader.vat5CertificateDetails.certificateNumber`	string	No	Example: `CERT-456`
`invoiceHeader.vat5CertificateDetails.quantity`	number	No	Example: `10`
`invoiceLineItems`	array<object>	Yes
`invoiceLineItems[].productCode`	string	No	Example: `260306145930`
`invoiceLineItems[].description`	string	No	Example: `MDF LAMINATED`
`invoiceLineItems[].unitPrice`	number (float)	No	Price including VAT Example: `1000`
`invoiceLineItems[].quantity`	integer	No	Example: `1`
`invoiceLineItems[].discount`	string	No	Discount amount or percentage (e.g. '100' or '10%') Example: `10%`
`invoiceLineItems[].taxRateId`	string	No	One of: `A`, `B`, `E` Example: `A`
`invoiceLineItems[].taxRate`	string	No	Tax rate [Required for rate A]. Supports decimal (0.165), percentage (16.5), or string ('16.5%') Example: `16.5`
`invoiceLineItems[].isProduct`	boolean	No	Example: `true`
`invoiceSummary`	object	No
`invoiceSummary.offlineSignature`	string	No	MRA Offline Signature (Required for offline synchronization)

Responses

200Tax receipt generated successfully

Generate Tax Receipt DEBUG TESTING AID

🚀 Try it

POST/api/v1/{tin}/generate-tax-receipt-debug🔒 token required

Debug endpoint for generating a tax receipt. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it. Use this to verify your payload structure and calculations before live submission.

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
`terminalId`	string (uuid)	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`referenceNo`	string	Yes	Example: `REF-2026-DEBUG-001`
`invoiceHeader`	object	Yes
`invoiceHeader.sellerTIN`	string	No	Example: `20154457`
`invoiceHeader.buyerTIN`	string	No	nullable Example: `12345678`
`invoiceHeader.buyerName`	string	No	nullable Example: `John Doe`
`invoiceHeader.isReliefSupply`	boolean	No	Example: `false`
`invoiceHeader.vat5CertificateDetails`	object	No	nullable
`invoiceHeader.vat5CertificateDetails.id`	integer	No	Example: `1`
`invoiceHeader.vat5CertificateDetails.projectNumber`	string	No	Example: `PRJ-123`
`invoiceHeader.vat5CertificateDetails.certificateNumber`	string	No	Example: `CERT-456`
`invoiceHeader.vat5CertificateDetails.quantity`	number	No	Example: `10.5`
`invoiceLineItems`	array<object>	Yes
`invoiceLineItems[].productCode`	string	No	Example: `260306145930`
`invoiceLineItems[].description`	string	No	Example: `MDF LAMINATED`
`invoiceLineItems[].unitPrice`	number (float)	No	Example: `1000`
`invoiceLineItems[].quantity`	number	No	Example: `2`
`invoiceLineItems[].taxRateId`	string	No	Example: `A`
`invoiceSummary`	object	No
`invoiceSummary.offlineSignature`	string	No	nullable

Responses

200Debug payload generated successfully

Generate Tax Receipt OFFLINE SIMULATION TESTING AID

🚀 Try it

POST/api/v1/{tin}/generate-tax-receipt-offline🔒 token required

Simulates an offline transaction generation. This endpoint computes the required offlineSignature and constructs the local validationURL exactly as a frontend POS should. Use this to verify your local signature implementation.

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`
`referenceNo`	string	Yes	Your internal reference number Example: `REF-1001`
`invoiceHeader`	object	Yes
`invoiceHeader.invoiceDateTime`	string (date-time)	No	Example: `2026-03-25T19:56:03.000Z`
`invoiceHeader.sellerTIN`	string	No	Example: `20154457`
`invoiceHeader.siteId`	string	No	Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`invoiceHeader.paymentMethod`	string	No	Example: `Cash`
`invoiceHeader.isExport`	boolean	No	Example: `false`
`invoiceHeader.isReliefSupply`	boolean	No	Example: `false`
`invoiceHeader.vat5CertificateDetails`	object	No
`invoiceHeader.vat5CertificateDetails.id`	integer	No	Example: `0`
`invoiceHeader.vat5CertificateDetails.projectNumber`	string	No	Example: `PRJ-123`
`invoiceHeader.vat5CertificateDetails.certificateNumber`	string	No	Example: `CERT-456`
`invoiceHeader.vat5CertificateDetails.quantity`	number	No	Example: `10`
`invoiceLineItems`	array<object>	Yes
`invoiceLineItems[].productCode`	string	No	Example: `260306145930`
`invoiceLineItems[].description`	string	No	Example: `MDF LAMINATED`
`invoiceLineItems[].unitPrice`	number (float)	No	Example: `1000`
`invoiceLineItems[].quantity`	integer	No	Example: `1`
`invoiceLineItems[].taxRateId`	string	No	Example: `A`
`invoiceLineItems[].taxRate`	string	No	Example: `16.5`

Responses

200Offline payload simulated successfully

Query Local Receipts

🚀 Try it

POST/api/v1/{tin}/query-local-receipts🔒 token required

Retrieve a list of tax receipts generated for a specific company (TIN) and site, stored in the local database.

Parameters

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

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	MRA Site ID Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`startDate`	string	No	Filter by start date (YYYY-MM-DD)
`endDate`	string	No	Filter by end date (YYYY-MM-DD)
`status`	string	No	One of: `success`, `failed`, ``
`referenceNo`	string	No	Filter by reference number
`invoiceNumber`	string	No	Filter by invoice number
`pageSize`	integer	No	Example: `20`
`pageNo`	integer	No	Example: `1`

Responses

200List of receipts
401Unauthorized - Authorization header missing or invalid

Get Last Online Transaction

🚀 Try it

POST/api/v1/{tin}/last-online-transaction🔒 token required

Retrieve the last successfully submitted online transaction from the MRA system for a specific terminal. This simplifies reconciliation by confirming what the MRA side has recorded.

Parameters

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

Request Body

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

Responses

200Last online transaction retrieved successfully

Get Last Offline Transaction

🚀 Try it

POST/api/v1/{tin}/last-offline-transaction🔒 token required

Retrieve the last successfully submitted offline transaction from the MRA system for a specific terminal.

Parameters

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

Request Body

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

Responses

200Last offline transaction retrieved successfully

Query Void/Refunded Receipts

🚀 Try it

POST/api/v1/{tin}/query-void-receipts🔒 token required

Retrieve a list of voided or refunded tax receipts directly from the Malawi Revenue Authority (MRA) system. This endpoint allows for tracking the status of cancellation requests across different time periods.

Parameters

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

Request Body

Field	Type	Required	Description
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`invoiceNumber`	string	No	Filter by a specific MRA invoice number Example: `Cs3-B-JY3E-BA`
`startDate`	string (date-time)	No	Start date for query range (YYYY-MM-DD or ISO 8601) Example: `2026-03-25T00:00:00.000Z`
`endDate`	string (date-time)	No	End date for query range (YYYY-MM-DD or ISO 8601) Example: `2026-03-27T00:00:00.000Z`
`page`	integer	No	Page number for pagination Example: `1`
`pageSize`	integer	No	Number of records per page Example: `10`

Responses

200Void receipts retrieved successfully

Cancel Sales Receipt (Void)

🚀 Try it

POST/api/v1/{tin}/cancel-sales-receipt🔒 token required

Submit a request to void/cancel an already submitted sales receipt in the MRA EIS system. Requires approval on the MRA side.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number
`token`	query	Yes	API access token for authentication
`deploymentEnvironment`	query	Yes	MRA deployment environment One of: Sandbox, Production

Request Body

Field	Type	Required	Description
`terminalId`	string	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`invoiceNumber`	string	Yes	The MRA invoice number to void Example: `Cs3-B-JY3E-BA`
`reason`	string	Yes	Reason for cancellation/void Example: `refund`
`referenceNo`	string	No	Optional internal reference number Example: `REF-1008`

Responses

200Void request submitted successfully

Query Local Void Requests

🚀 Try it

POST/api/v1/{tin}/query-local-void-requests🔒 token required

Retrieve a list of void requests stored in our local database for tracking and reconciliation.

Parameters

Name	In	Required	Description
`tin`	path	Yes	Taxpayer Identification Number
`token`	query	Yes	API access token for authentication

Request Body

Field	Type	Required	Description
`status`	string	No	One of: `Pending`, `Approved`, `Failed`
`invoiceNumber`	string	No
`referenceNo`	string	No
`pageSize`	integer	No	Example: `20`
`pageNo`	integer	No	Example: `1`

Responses

200List of void requests

Validate Buyer Authorization Code

🚀 Try it

POST/api/v1/{tin}/validate-buyer-auth-code🔒 token required

Validate an authorization code issued by MRA for a specific buyer/reason. This is used when a buyer claims to be purchasing on behalf of an organization or for specific tax-exempt purposes.

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
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`authorizationCode`	string	Yes	The MRA authorization code to validate Example: `070847437E52`

Responses

200Validation result
400Validation error or MRA error
404Company or Terminal not found

Get Invoice Details By Number

🚀 Try it

POST/api/v1/{tin}/get-invoice-by-number🔒 token required

Retrieve full details of a specific tax receipt from the MRA system using its invoice number. This endpoint returns the complete invoice header, line items, and summary details as recorded by MRA.

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
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`invoiceNumber`	string	Yes	The MRA invoice number to retrieve Example: `Cs3-B-JY3X-B`

Responses

200Invoice retrieved successfully
401Unauthorized - Authorization header missing or invalid
404Company or Terminal not found

Process Credit or Debit Note

🚀 Try it

POST/api/v1/{tin}/process-credit-debit-note🔒 token required

Generate a credit note (if the total is lower) or a debit note (if the total is higher) against an existing invoice. Our system automatically recalculates tax components and simplifies the submission process.

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
`terminalId`	string (uuid)	Yes	Terminal ID from activation Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`referenceNo`	string	Yes	Unique reference for this adjustment Example: `REF-CD-1002`
`reasonForAdjustment`	string	Yes	Description of why the credit/debit note is being issued Example: `Return of damaged goods`
`invoiceHeader`	object	Yes
`invoiceHeader.invoiceNumber`	string	Yes	The original invoice number being adjusted Example: `Cs3-B-JY3X-B`
`invoiceHeader.invoiceDateTime`	string (date-time)	No	Example: `2026-04-16T10:22:14.527Z`
`invoiceHeader.sellerTIN`	string	Yes	Example: `20154457`
`invoiceHeader.siteId`	string	No	Example: `CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce`
`invoiceHeader.paymentMethod`	string	No	Example: `Cash`
`invoiceHeader.isExport`	boolean	No	Example: `false`
`invoiceHeader.isReliefSupply`	boolean	No	Example: `false`
`invoiceHeader.vat5CertificateDetails`	object	No
`invoiceHeader.vat5CertificateDetails.id`	integer	No	Example: `0`
`invoiceHeader.vat5CertificateDetails.projectNumber`	string	No	Example: `PRJ-123`
`invoiceHeader.vat5CertificateDetails.certificateNumber`	string	No	Example: `CERT-456`
`invoiceHeader.vat5CertificateDetails.quantity`	number	No	Example: `10`
`invoiceLineItems`	array<object>	Yes
`invoiceLineItems[].productCode`	string	No	Example: `260306145930`
`invoiceLineItems[].description`	string	No	Example: `MDF LAMINATED`
`invoiceLineItems[].unitPrice`	number (float)	No	Example: `1000`
`invoiceLineItems[].quantity`	integer	No	Example: `1`
`invoiceLineItems[].discount`	string	No	Example: `0`
`invoiceLineItems[].taxRateId`	string	No	One of: `A`, `B`, `E` Example: `A`
`invoiceLineItems[].isProduct`	boolean	No	Example: `true`
`invoiceSummary`	object	No
`invoiceSummary.offlineSignature`	string	No	MRA Offline Signature (Required for offline synchronization)

Responses

200Note processed successfully
400MRA Processing Error (e.g., Original invoice not found)
401Unauthorized - Terminal session expired

Process Credit/Debit Note DEBUG TESTING AID

🚀 Try it

POST/api/v1/{tin}/process-credit-debit-note-debug🔒 token required

Debug endpoint for processing a credit or debit note. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it.

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
`terminalId`	string (uuid)	Yes	Example: `193760fb-cddc-40ed-b0fb-f08f8720f86c`
`referenceNo`	string	Yes	Example: `REF-ADJ-001`
`reasonForAdjustment`	string	Yes	Example: `Return of goods`
`invoiceHeader`	object	Yes
`invoiceHeader.invoiceNumber`	string	No	Example: `Cs3-B-JY3E-BA`
`invoiceHeader.sellerTIN`	string	No	Example: `20154457`
`invoiceHeader.isReliefSupply`	boolean	No	Example: `false`
`invoiceLineItems`	array<object>	Yes
`invoiceLineItems[].productCode`	string	No	Example: `260306145930`
`invoiceLineItems[].description`	string	No	Example: `MDF LAMINATED`
`invoiceLineItems[].unitPrice`	number (float)	No	Example: `1000`
`invoiceLineItems[].quantity`	number	No	Example: `1`
`invoiceLineItems[].taxRateId`	string	No	Example: `A`

Responses

200Debug payload generated successfully