Contents

1. Document summary ............................................................................... 4

1.1. Definitions .......................................................................... 4
2. Fiscal Device Gateway usage scenarios ....................................................... 5
2.1. Device registration ................................................................ 5
2.2. Fiscal device communication modes ........................................... 5
2.3. Fiscal day (in online mode) ...................................................... 6
2.4. Fiscal day (in offline mode) ...................................................... 7
3. Object statuses .................................................................................... 8
3.1. Fiscal day statuses ................................................................. 8
4. Fiscal Device Gateway API interfaces ......................................................... 9
4.1. verifyTaxpayerInformation ...................................................... 9
4.2. registerDevice ...................................................................... 9
4.3. issueCertificate .................................................................. 10
4.4. getConfig .......................................................................... 11
4.5. getStatus .......................................................................... 12
4.6. openDay ........................................................................... 13
4.7. submitReceipt .................................................................... 13
4.8. submitFile ......................................................................... 19
4.8.1. File example.................................................................... 20
4.9. getFileStatus ...................................................................... 23
4.10. closeDay ........................................................................... 24
4.11. getServerCertificate ............................................................ 25
4.12. ping ................................................................................. 25
4.13. Users management .............................................................. 26
4.13.1. User registration process if user registration is finished right away: . 26
4.13.2. User registration process if user registration is finished after user login:
27
4.13.3. getUsersList ................................................................... 27
4.13.4. login ............................................................................ 28
4.13.5. createUserBegin .............................................................. 28
4.13.6. createUserConfirm ........................................................... 29
4.13.7. sendSecurityCode ............................................................ 29
4.13.8. sendSecurityCodeContactChange .......................................... 30
4.13.9. confirmUserContactChange ................................................. 30
4.13.10. updateUser .................................................................. 30
4.13.11. changeUserPassword ....................................................... 31
4.13.12. resetUserPasswordBegin ................................................... 31
4.13.13. resetUserPasswordConfirm ................................................ 32
4.14. getStockList ....................................................................... 32
5. Data Types ........................................................................................ 34
5.1. Address ............................................................................ 34
5.2. Contacts ........................................................................... 34
5.3. SignatureData .................................................................... 34
5.4. Enums .............................................................................. 34
5.4.1. DeviceOperatingMode ......................................................... 34
5.4.2. FiscalDayStatus ................................................................ 34
5.4.3. FiscalDayReconciliationMode ................................................ 35
5.4.4. FiscalCounterType ............................................................. 35
5.4.5. MoneyType...................................................................... 35
5.4.6. ReceiptType .................................................................... 35
5.4.7. ReceiptLineType ............................................................... 35
5.4.8. ReceiptPrintForm .............................................................. 36
5.4.9. FiscalDayProcessingError ..................................................... 36
5.4.10. FileProcessingStatus ......................................................... 36
5.4.11. FileProcessingError........................................................... 36
Copyright © ZIMRA 2 of 77
 5.4.12. UserStatus ..................................................................... 37
5.4.13. SendSecurityCodeTo ......................................................... 37
6. Fiscal counters ................................................................................... 38
7. Integration Setup Requirements.............................................................. 39
7.1. Communication and security protocols ...................................... 39
7.2. Environment addresses ......................................................... 39
7.3. Authentication and authorization ............................................ 39
7.4. Timeout Settings ................................................................. 39
8. Errors .............................................................................................. 40
8.1. Http statuses...................................................................... 40
8.2. Error codes........................................................................ 40
8.2.1. Validation errors ............................................................... 41
9. Requirements for fiscal devices .............................................................. 44
10. Standard fiscal receipt, invoice and report views ........................................ 46
10.1. Receipt48 view ................................................................... 46
10.2. InvoiceA4 view ................................................................... 48
10.3. Receipt and invoice view fields descriptions ............................... 52
10.4. Z Report / X Report .............................................................. 56
10.5. Z report and X report fields description .................................... 57
11. Receipt QR code rules .......................................................................... 60
12. Certificate signing request (CSR) and Certificate examples ............................. 61
12.1. Example keys used .............................................................. 61
12.1.1. ECC ECDSA on SECG secp256r1 ............................................. 61
12.1.2. RSA 2048 ....................................................................... 61
12.2. CSRs and Certificates ........................................................... 63
12.2.1. ECC ECDSA on SECG secp256r1 ............................................. 63
12.2.1.1. CSR ........................................................................ 63
12.2.1.2. Certificate ............................................................... 64
12.2.2. RSA 2048 ....................................................................... 65
12.2.2.1. CSR ........................................................................ 65
12.2.2.2. Certificate ............................................................... 66
13. Signatures generation and verification rules .............................................. 69
13.1. Signature an hash generation algorithm .................................... 69
13.2. Receipt signature generation and verification ............................. 69
13.2.1. Receipt device signature .................................................... 69
13.2.2. Receipt FDMS signature ..................................................... 72
13.3. Fiscal day signature generation and verification .......................... 73
13.3.1. Fiscal day device signature ................................................. 73
13.3.2. Fiscal day FDMS signature ................................................... 74

Copyright © ZIMRA 3 of 77
1. DOCUMENT SUMMARY

1.1. Definitions
Term Description
Device or Fiscal device Hardware based or software-based solution which is accounting sales (issues fiscal invoices, debit or
credit notes) and submits them to FDMS.
Device signature Receipt signature signed by fiscal device before submission of a receipt to Fiscal Device Gateway API.
Fiscal Device Gateway FDMS system module responsible for fiscal invoices, debit, or credit notes acceptance from fiscal
API devices.
Fiscalisation Data Fiscalisation Data Management System means Fiscalisation Backend system used by the Commissioner
Management System or the Zimbabwe Revenue Authority to receive, control and monitor User business transactions
(FDMS) recorded by Electronic Fiscal Devices interfaced to it and to generate various required reports for the
purposes of tax revenue administration.
FDMS signature Receipt signature signed by FDMS after submission of a fiscal invoices, debit, or credit notes to Fiscal
Device Gateway API.
QR code A machine-readable code consisting of an array of black and white squares storing fiscal invoices,
debit, or credit notes identification information, required to validate a receipt.
QR code data QR code data is one of few receipt identification fields stored in QR code, which represents fiscal
invoices, debit, or credit notes device signature.
Receipt Receipt encompasses fiscal invoice, debit, or credit note.
ZIMRA Zimbabwe Revenue Authority.

Copyright © ZIMRA 4 of 77
2. FISCAL DEVICE GATEWAY USAGE SCENARIOS
2.1. Device registration
The process starts when a taxpayer initially registers or updates their information using
the Zimra registration portal. After completing this process, the taxpayer is provided with
device ID and Activation Key. Device registration must be done once before starting to use a
new device. After device registration, it needs to get its configurations (config) from FDMS.

2.2. Fiscal device communication modes

Fiscal device communicates with Fiscal Device Gateway API in one of two possible
communication modes:

 Online
 Offline

Online communication mode represents fiscal device communication in a way when

fiscal device must have online access to FDMS (must have internet connection available) when
it wants to close fiscal day. Fiscal day opening and submission of a receipt to FDMS should be
done immediately after opening a day or printing receipt or invoice for buyer respectively,
however in case of missing internet connection, day opening message and submission of a
receipt may be delayed but must be done before closing a fiscal day. In case fiscal day was
opened and receipt was issued without internet connection, it is mandatory, that fiscal day
opening message would be sent before sending receipts. Otherwise, receipts will not be
accepted.

Copyright © ZIMRA 5 of 77
 Offline communication mode represents fiscal device communication in a way, when
fiscal device may not have internet, and its receipts and fiscal report data will be provided to
FDMS by using files (by uploading file using Self-service, or by sending file to Fiscal Device
Gateway API, whenever connection will be available).

2.3. Fiscal day (in online mode)

After successful device registration, it can be used for submitting sales to FDMS. Sales
submission is possible only when fiscal day is opened. When work is finished with device, it
must close fiscal day.

In case of error in fiscal day report processing report must be corrected on device and
resubmitted to FDMS. Report resubmission can be done unlimited number of times. In case it
does not give successful result, and supplier cannot fix it to submit successful report, fiscal day
may be closed manually by supplier in Public Portal, or by ZIMRA officer.

Copyright © ZIMRA 6 of 77
 2.4. Fiscal day (in offline mode)

If device has internet connection, it should call getConfig method, to get device
configuration information.
Device opens fiscal day, if device has internet connection it can send information using
submitFile method (file with only header) about opened day.
Invoices are issued which are saved in device if device has internet connection it can
send information using submitFile method (file with header and content) about already issued
invoices.
After fiscal day is closed information is saved in device, if device has internet connection
it should send information using submitFile method (file with header and footer) about closed
day. However, if there are still left unsent invoices it should send information using submitFile
method (file with header, content and footer) about receipts and closed day.
After sending file device should call getFileStatus method to get sent file status.

Copyright © ZIMRA 7 of 77
3. OBJECT STATUSES
3.1. Fiscal day statuses

Status Description
1. FiscalDayClosed Status used when fiscal device has successfully closed fiscal day. New fiscal day opening is
possible only from this status.
2. FiscalDayOpened Fiscal day is opened. Invoices can be created only when fiscal day is in this status.
3. FiscalDayCloseInitiated Closure of fiscal day is initiated, however FDMS not yet validated fiscal counters.
While Fiscal day is in status “FiscalDayCloseInitiated”, no new request to initiate fiscal day
closure will be accepted from device or user. New invoices will not be accepted as well.
4. Is processing successful? If processing of report is successful, fiscal day status is changed to FiscalDayClosed, if
processing of report is not successful status is changed to FiscalDayCloseFailed.
5. FiscalDayCloseFailed FDMS validated fiscal day report received from device, however there are validation errors.
Device must correct issues and repeatedly submit fiscal day closure message.

Copyright © ZIMRA 8 of 77
4. FISCAL DEVICE GATEWAY API INTERFACES
Fiscal Device Gateway API exposes its methods using REST JSON interface. All methods
except closeDay and submitFile are synchronous. closeDay and submitFile methods return
response about accepted request synchronously, however processing of information is done
asynchronously.

Each request must contain these HTTP headers:

Header name Mandatory Description
DeviceModelName Yes Device model name as registered in ZIMRA
DeviceModelVersionNo Yes Device model version number as registered in ZIMRA

During processing of request validations are performed and these errors may be
returned:

 If device model is blacklisted error DEV04 is returned.

 If taxpayer is not active error DEV05 is returned.
 If device is not active error DEV01 is returned.

4.1. verifyTaxpayerInformation
verifyTaxpayerInformation endpoint is used to retrieve taxpayer information from FDMS
before device registration (in order user could double check if device is going to be registered
to correct taxpayer). Activation key is not yet used.
This API endpoint does not require certificate for authentication.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID
activationKey String (8) Yes Activation key.
deviceSerialNo String (20) Yes Device serial number assigned by manufacturer.

Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
taxPayerName String (250) Yes Taxpayer name
taxPayerTIN String (10) Yes Taxpayer TIN code
vatNumber String (9) No Taxpayer’s VAT number. Field is not returned if taxpayer is not a VAT payer.
deviceBranchName String (250) Yes Device branch name (or trade name) assigned by taxpayer.
deviceBranchAddress Address Yes Device branch address.
deviceBranchContacts Contacts No Device branch contacts information.

4.2. registerDevice
registerDevice endpoint is used to get device certificate and register device in FDMS
(link device with FDMS).
This API endpoint does not require certificate for authentication.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID

Copyright © ZIMRA 9 of 77
activationKey String Yes Activation key.
(8)
Case insensitive 8 symbols key.
certificateRequest String Yes Certificate signing request (CSR) for which certificate will be generated (in PEM
format).
Assigned by ZIMRA device name (format: ZIMRA-<Fiscal_device_serial_no>-
<zero_padded_10_digit_deviceId>) should be provided in CSR`s Subject
Example of CN value, when fiscal device serial no is “SN: 001” and device id is
“187”: “ZIMRA-SN: 001-0000000187”.
Other CSR’s Subject fields are optional, however if provided must match these
values (otherwise device registration will be rejected):
 C = ZW
 O = Zimbabwe Revenue Authority
 S = Zimbabwe

Supported algorithms and key types (in order of suggested preference):

1) ECC ECDSA on SECG secp256r1 curve (also named as ANSI prime256v1,
NIST P-256); Signature Algorithm: ecdsa-with-SHA256.
2) RSA 2048; Signature Algorithm - SHA256WithRSA.
Note: RSA 2k and ECC 256 implement same security level, which is considered safe
until 2030 year (considering trends due to upgrade in computer software and
hardware combination).

Most cryptographic tools and libraries support this format giving easy-to-use API
and hiding all technical representation and encoding details.
CSR is “CertificationRequest” structure, as defined by PKCS #10 (CSR syntax
specified by RFC2986).
Serialized in PEM format (i.e., base64 encoded with “------BEGIN CERTIFICATE
REQUEST-----” header and “-----END CERTIFICATE REQUEST-----” footer).
For more info, please refer to “12 Certificate signing request (CSR) and Certificate
examples”.

Output parameters:
Name Type Mandatory Description
operationID String (60) Yes Operation ID assigned by FDMS.
certificate String Yes X.509 v3 type device certificate (in PEM format).
It must be used by device in further communication with Fiscal
Device Gateway API. Certificate is multi-purpose:

 Client Certificate for SSL with Client Authentication.

 For data signing when device signature is required.

Certificate is “Certificate” structure specified by RFC5280.

Serialized in PEM format (i.e. base64 encoded with “-----BEGIN
CERTIFICATE-----” header and “-----END CERTIFICATE-----” footer).
For more info, please refer to “12 Certificate signing request (CSR)
and Certificate examples”.

4.3. issueCertificate
issueCertificate endpoint is used to renew certificate before the expiration of the
current certificate.
It is recommended to renew certificate a month before its expiration.
Certificate reissuance can be done at any time. It does not depend on fiscal day status,
however it is recommended to be done before opening a new fiscal day.

Input parameters:
Name Type Mandatory Description
deviceID Int Yes Device ID

Copyright © ZIMRA 10 of 77