User Story

As a PortaBilling System Administrator of a CSP, I need to automatically transmit tax invoice data of post-paid customers to the Malawi Revenue Authority's (MRA) Electronic Invoicing System (EIS) in real-time when invoices are generated, so that CSP complies with mandatory VAT e-invoicing regulations, avoids penalties for non-compliance, and ensures uninterrupted business operations.

As a CSP customer, I want to scan an MRA-approved QR code on my invoice that confirms the tax amounts and invoice validity, so that I can be confident the CSP has correctly declared and paid taxes.

Example of Use

On 2025-02-01 at 00:15:00, PortaBilling completes the billing cycle for January 2025 and generates invoice INV-2025-000456 for customer "Blantyre Medical Supplies Ltd" (Customer ID 102345) totaling MWK 1,250,000.00 (including MWK 175,206.61 VAT at 16.5%). The EIS integration service automatically transmits this invoice details to MRA EIS via the API. MRA validates the invoice and returns an invoice validation URL (e.g. "https://eservices.mra.mw/doc/v/?vc=90241313200014&c=fdd8d5ccc06a49d6a1efbf7e3896f0b4") which must be converted to a QR code by the EIS integration service to appear at the bottom of invoice.

Current Solution

For pre-paid customers invoicing is done via custom built (by CSP) SAP integration and agreed by CSP to remain unchanged.

For post-paid customers, a 3rd party application currently collects invoices from PortaBilling, parses them, and reports the invoice data to the MRA. The application then stamps the invoices and saves them in a remote directory (outside of PortaBilling) so invoices are ready to be delivered to end customers. 

This process of reporting to the MRA and stamping invoices should be decommissioned in favor of using the EIS system and an MRA-approved QR code instead of a stamp.

Additional information:

• Taxation is disabled in the system
• VAT and excise included into the prices
• There is a princeXML based invoice template (prepared by PortaOne in scope of PMD-2367), which back-calculates VAT and excise from the xDRs and shows charges summaries and aging details 

Business Model

The Malawi Revenue Authority has mandated that all VAT-registered taxpayers must use the Electronic Invoicing System (EIS) to transmit detailed sales transaction data in real-time. This replaces the legacy Electronic Fiscal Devices (EFDs) that transmitted summarized Z-reports once daily via FTP. Non-compliance results in penalties up to MWK 5,000,000 and potential business license suspension.

Financial Flow

• VAT Collection: CSP collects 16.5% VAT on all taxable services (voice calls, data bundles, messaging, subscriptions). For a typical monthly billing cycle with MWK 500,000,000 in taxable revenue, VAT collected equals MWK 82,500,000.
• Remittance Deadline: VAT must be remitted to MRA by the 25th of the next month. Integration ensures accurate tracking and reporting.
• Penalty Avoidance: Late or incorrect submissions incur MWK 300,000 penalty plus 2% interest per month on outstanding VAT.

Technology (systems involved)

• PortaBilling: Core billing system with customer records, xDRs, and invoice generation
• MRA EIS API: REST API at https://eis-api.mra.mw/ accepting JSON payloads over HTTPS
• MRA EIS Portal: https://eis-portal.mra.mw/ for terminal registration and configuration management

High-Level Scope of Integration Flows

• Terminal Onboarding: One-time activation using Terminal Activation Code (TAC) obtained from MRA portal. TAC is exchanged for terminal configuration including API tokens.
• Configuration Sync: Daily call to "Get Latest Configuration" endpoint to retrieve current tax rates and parameters.
• Invoice Transmission: Real-time POST to sale transaction endpoint with invoice details; receive invoice validation URL in response.

Key MRA Data Objects

Stakeholders and Their Benefits

Use Cases

Use Case #1: Terminal activation preparation

Roles: CSP, EIS, EIS integration service 

Preconditions:

1. CSP manually registers and activates terminal in the EIS platform
2. CSP enters terminal secret key, terminal activation code and a terminal jwt token to the EIS integration service
3. EIS integration service fetches current terminal configuration using EIS API

Use Case #1.1: Successful terminal activation

1. Continuation of Use Case #1
2. EIS API returns current terminal configuration including current tax rates (VAT, excise)
3. EIS integration service shows "service is activated" notification message to the CSP

Use Case #1.2: Failed terminal activation (alternative to #1.1)

1. Continuation of Use Case #1
2. EIS API does not respond, or responds with a failure
3. EIS integration service shows "Service activation failed. Terminal jwt token is invalid, re-check the terminal credentials." notification message to the CSP
4. CSP starts over the Use Case #1

Use Case #2: Invoice Transmission to MRA EIS

Roles: CSP, EIS, EIS integration service 

Preconditions:

• EIS integration service is activated with VAT tax 16.5%
• Customer "Blantyre Medical Supplies Ltd" (Customer ID 102345) has custom field TIN: 1000234567
• Customer has active account with billing period January 1-31, 2025
• xDRs totaling MWK 1074793.39 (incl. VAT) have been rated for the period
• PortaBilling invoice template includes placeholder for the QR code to be inserted (made via layout designer or custom html template)
• Invoice review functionality is enabled

Use Scenario #2.1: Successful Monthly Invoice Transmission

1. At the end of billing period PortaBilling regular invoice "11" is generated for Customer ID 102345
2. PortaBilling sends notification to the CSP with invoice review request
3. CSP opens invoice "11" and verifies total amount of MWK 1074793.39 (no QR code yet) and approves the invoice
4. PortaBilling aggregates the invoice xDRs related to the invoice "11" and sends them to the EIS integration service
5. EIS integration service constructs the JSON payload according to the MRA EIS API specification.
   • TODO: Mapping exercise with stakeholders
6. EIS integration service back-calculates the 16.5% VAT from xDR and total amount (1074793.39 * 16.5% = 177340.91) 
7. EIS integration service triggers invoice transmission event
8. EIS integration service sends POST to https://eis-api.mra.mw/api/sale with signed payload
9. MRA API returns HTTP 200 with validationURL "https://eservices.mra.mw/doc/v/?vc=90241313200014&c=fdd8d5ccc06a49d6a1efbf7e3896f0b4"
10. EIS integration service downloads the invoice "11" PDF and puts the encoded validation URL to the previously defined placeholder position
11. EIS integration service saves the invoice "11" PDF with the encoded QR code to the internal storage
12. EIS integration service returns successful response code to the PortaBilling
13. PortaBilling starts processing next invoice according to the scenario #2.1

Use Scenario #2.2: EIS integration service can't locate a QR code placeholder (alternative to #2.1)

1. Continuation of Use Scenario #2.1 after step 9
2. EIS integration service downloads the invoice "11" PDF, but can't locate the QR code placeholder
3. EIS integration service appends new blank PDF page with the QR code in the middle  
4. EIS integration service logs about failure to put QR code to the invoice "11" on pre-defined location, due to missing placeholder
5. EIS integration service returns a success code to the PortaBilling
6. PortaBilling starts processing next invoice according to the scenario #2.1

Use Scenario #2.3: MRA EIS is not responding (alternative to #2.1)

1. Continuation of Use Scenario #2.1 after step 8
2. MRA EIS does not respond (returns 408 request timeout code)
3. EIS integration service returns error code to the PortaBilling
4. PortaBilling creates notification to the CSP of unsuccessful MRA report delivery for the invoice "11"
5. PortaBilling schedules retry attempt for the invoice "11" after an hour
6. PortaBilling starts processing next invoice according to the scenario #2.1

Use Case #3: Defining product codes of the MRA EIS

Roles: CSP, PortaBilling, EIS integration service

TODO: can be created after mapping confirmation from the stakeholders.

preliminary it will be similar to https://wiki.portaone.com/x/wYgtBg 

Non-functional Requirements

• Performance:
  • System generates 550 invoices during billing period closure. 
• Availability:
  • EIS integration service must achieve 99.9% uptime monthly
• Security:
  • API credentials must not appear in logs; use token masking (show first 4 and last 4 characters only)
• Audit and Logging:
  • All EIS transactions must be logged with: timestamp, invoice_id, amount, MRA_response_code, duration_ms, user_id
  • Logs must be retained for 7 years per MRA regulations
  • Failed transmission attempts must be logged with full error details for troubleshooting
• Compliance:
  • Integration must pass MRA API Compliance Certification before production deployment
  • QR codes must be generated according to MRA specifications and be verifiable via MRA portal
  • All amounts must be transmitted in Malawi Kwacha (MWK)
  • PortaBilling Charging categories must map to MRA standardized service codes

Peculiarities

• Pre-paid billing model reporting to MRA EIS support is out of scope.
• Invoice voiding and modification after successful upload to the MRA EIS shall be avoided, as these actions are not supported by MRA EIS. All the adjustments can be done in new invoices only.
• PortaOne Assumptions
  • The only PortaBilling records for EIS integration service to report towards MRA (as Sale Transactions) are PortaBilling Customer Invoices
    • the other transactions are out of integration scope, e.g.
      • PortaBilling charges for customers with disabled invoicing
      • POS charges managed in external system (SAP)
  • CSP has already registered with MRA and has a valid Taxpayer Identification Number (TIN)
  • CSP will apply for Terminal Activation Code via MRA portal before integration begins
  • PortaOne will obtain MRA API Compliance Certification (Product ID and Version) before production deployment
  • Customers' TIN numbers are available in PortaBilling customer records for B2B invoices
  • B2C transactions may avoid supplying buyer information if individual TIN not available
  • As the invoice number reported to the MRA EIS and the invoice number in PortaBilling have different formats, PortaOne assumes it is acceptable to encode the invoice number mapping into the invoice file naming schema after the QR code is generated for debug purposes.
• Edge Cases
  • Zero-value invoices: Invoices with zero total for charges (e.g., fully discounted) are NOT transmitted to MRA (confirmed here).
  • Backdated invoices: Invoices generated for past periods use the original billing period date, not generation date
  • Multi-currency: MRA EIS does not support multi-currency; Any non-MWK transaction  shall be skipped from reporting (confirmed here). 
• Regulatory Specifics
  • VAT Rate: Standard VAT rate is 16.5% (as of December 2025); exempt and zero-rated items per Taxation Act schedules
  • Record Retention: All EIS records must be retained for 7 years per VAT Act requirements
  • Certification Requirement: Per MRA API Compliance Certification (Section 7), all third-party POS software must be certified before production use.
• Operational models: countries regulations vary between countries