ZIMRA Integration
Understand how VasBox integrates with ZIMRA for fiscal compliance in Zimbabwe.
VasBox handles the complexity of ZIMRA (Zimbabwe Revenue Authority) fiscal compliance, allowing you to focus on your business while ensuring all invoices and receipts meet regulatory requirements.
Requirements
Before you can submit transactions to ZIMRA, ensure you have:
- Valid TIN - Tax Identification Number registered with ZIMRA
- VAT Registration - If your annual turnover exceeds the VAT threshold
- Fiscal Device - Registered fiscal device or VasBox virtual device
- VasBox Account - Active account with ZIMRA integration enabled
Registration Process
- Create a VasBox account
- Complete business verification
- Provide ZIMRA credentials
- Configure fiscal device
- Test in sandbox environment
- Go live with production
Submission Flow
The ZIMRA submission process follows these steps:
| Step | Action | Invoice Status |
|---|---|---|
| 1 | Create invoice with customer and items | draft |
| 2 | Review and make any necessary changes | draft |
| 3 | Submit invoice to ZIMRA | pending |
| 4 | VasBox sends data to ZIMRA servers | pending |
| 5 | ZIMRA validates and returns fiscal code | submitted |
| 6 | Invoice is now fiscalized and immutable | submitted |
Code Example
// 1. Create an invoice
$invoice = $vasbox->invoices->create([
'customer_id' => 'cust_123',
'items' => [...]
]);
// 2. Review and finalize
// Invoice is in 'draft' status
// 3. Submit to ZIMRA
$result = $vasbox->invoices->submit($invoice->id);
// 4. Invoice now has fiscal code
echo $result->fiscal_code; // ZW-2024-ABC123-XYZ
Important
Fiscal Codes
Each successfully submitted transaction receives a unique fiscal code from ZIMRA. This code must be printed on invoices and receipts.
Format
ZW-2024-ABC123-XYZ
│ │ │ │
│ │ │ └─ Checksum
│ │ └─ Unique identifier
│ └─ Year
└─ Country code
QR Codes
VasBox generates QR codes containing fiscal information for each transaction. Include this QR code on printed documents for verification.
qr_code_url field in the invoice response to get a ready-to-use QR code image. Compliance Rules
ZIMRA enforces specific rules for fiscal compliance:
Timing Requirements
| Rule | Requirement |
|---|---|
| Submission deadline | Within 24 hours of transaction |
| Receipt submission | Immediate (at point of sale) |
| Void deadline | Within 7 days of original transaction |
| Reporting period | Monthly VAT returns |
Data Requirements
- Customer TIN - Required for B2B transactions over $50
- Tax breakdown - Itemized VAT amounts per line item
- Currency - Transactions in supported currencies (USD, ZWL)
- Sequential numbering - Invoice numbers must be sequential
Non-Compliance Penalties
Failure to comply with ZIMRA regulations may result in:
- Fines and penalties
- Business license suspension
- Criminal prosecution for serious violations