Receipt statuses and validation
What PENDING, ACCEPTED and FLAGGED mean, ZIMRA's Red, Grey and Yellow grades, and what to do about each
How a receipt reaches ZIMRA
- You issue it. DigiTax checks the receipt against ZIMRA's rules. If it passes, DigiTax numbers it, signs it, chains it to the previous receipt and stores it, then responds with 201 Created.
- DigiTax sends it. Receipts are sent to ZIMRA in the background, one device at a time and in order, because each receipt is chained to the one before it.
- ZIMRA grades it. ZIMRA records the receipt and may grade it Red, Grey or Yellow if it finds a problem.
Receipt statuses
status | Meaning | What to do |
|---|---|---|
PENDING | Issued and signed, but ZIMRA hasn't received it yet | Nothing. Check last_submit_error if it stays pending, and see When sending halts |
ACCEPTED | ZIMRA received it with no findings, or only Yellow ones | Nothing |
FLAGGED | ZIMRA received it but graded it Red or Grey (see validation_colour and validation_errors) | See Flagged receipts |
Once ZIMRA has a receipt, it has fdms_receipt_id, fdms_operation_id (quote this to ZIMRA support) and submitted_at. Filter GET /receipts by status=FLAGGED or by validation_colour to find receipts that need attention.
ZIMRA's grades
| Colour | Receipt status | Blocks the fiscal day from closing? | Clears by itself? |
|---|---|---|---|
| 🟡 Yellow | ACCEPTED | No | Not needed |
| ⚪ Grey | FLAGGED | Yes | Yes, once the missing earlier receipt reaches ZIMRA |
| 🔴 Red | FLAGGED | Yes | No. The day can only be closed in ZIMRA's portal |
Flagged receipts
Never issue a FLAGGED receipt againA FLAGGED receipt is still fiscalised. It has an
fdms_receipt_id, counts in ZIMRA's totals for the day, and can't be sent again. Issuing the same sale again would report it twice.
- Grey is a gap in the receipt chain: ZIMRA got this receipt before an earlier one. Wait. It clears once the earlier receipt arrives.
- Red means the receipt broke a rule that ZIMRA only checks once it has the receipt. Issue a credit note and a new receipt only if the sale itself was wrong, for example wrong amounts or taxes, or buyer details the buyer needs. A chain or numbering error needs no credit note. Then contact DigiTax support about closing the day, because a day with a Red receipt can only be closed in ZIMRA's portal. See The close-of-day caveat.
Set up the zimra.receipt.flagged callback to hear about flagged receipts as soon as ZIMRA grades them.
Checks before a receipt is issued
DigiTax checks every receipt before issuing it, so that most problems are caught before they reach ZIMRA. A receipt that fails is not issued. You get 400 Bad Request. Its message describes the broken rule, or summarises when there are several, and metadata holds the details:
codes: the rule codes it broke, comma-separated, for exampleRCPT019,RCPT047fields: the request fields concerned, comma-separated, for exampletotal_cents,lines[0].hs_codeviolations: a JSON array (as a string) of{code, colour, field, message, line_no, meta}, one per broken rule.line_nois the 1-based line, and is left out for a rule about the receipt as a whole
Fix the receipt and send it again with the same trader_invoice_number. See Errors for an example.
Codes starting RCPT are ZIMRA's own rules. Codes starting LOCAL_ are DigiTax checks for problems ZIMRA would reject without a code. The most common:
| Code | Rule |
|---|---|
RCPT019 | total_cents must equal the total worked out from the lines and their taxes |
RCPT022 | A line's price_cents has the wrong sign for the receipt and line type |
RCPT024 | A line's total must be its price times its quantity, rounded to the cent |
RCPT034 | A credit or debit note needs notes saying why it was issued |
RCPT047 | hs_code must be 4 or 8 digits, and is required on a sale line for a VAT-registered taxpayer |
RCPT048 | hs_code must be 8 digits on a sale line whose tax is 0% or exempt |
LOCAL_TAX | tax_id is not one of the device's taxes valid at the receipt date. List them with GET /resources/tax-categories |
LOCAL_PAYMENTS | Payments must add up to the receipt total, with the receipt's sign |
LOCAL_SIGN | An amount has the wrong sign for the receipt type |
Credit and debit notes have further rules (RCPT029, RCPT033, RCPT035, RCPT036, RCPT042). See Credit and debit notes.
Some problems surface only once ZIMRA has the receipt, and come back as a Red grade rather than a 400. DigiTax guards against the most common one, buyer data without both a TIN and a registered name (RCPT043): it refuses a TIN without a registered name, and doesn't send ZIMRA a buyer with no TIN. See The buyer.
Yellow findings don't stop a receipt. Those found before issue are in the receipt's findings, and those ZIMRA reports are in validation_errors.
When sending halts
Because receipts are chained, ZIMRA must receive them in order. If ZIMRA refuses a receipt outright, DigiTax stops sending that device's receipts until the cause is fixed, rather than sending later receipts out of order. While sending is halted:
- you can still issue receipts, but they stay
PENDING - the fiscal day can't close until sending resumes
GET /fdms-info shows the state in receipt_submission:
| Field | Meaning |
|---|---|
halted | true while sending is stopped |
halt_source | FDMS_REJECTION: ZIMRA refused a receipt. DigiTax retries automatically every 15 minutes. RECONCILE: ZIMRA's records disagree with DigiTax's. DigiTax support resumes sending |
halted_reason, halted_at | What stopped sending, and when |
blocking_receipt_id | Your receipt that sending is stopped at. Empty when it is another business's receipt on the shared test device |
pending_receipt_count, oldest_pending_receipt_at | Receipts not yet received by ZIMRA |
stranded_receipt_count | Unsent receipts left on a day closed in ZIMRA's portal, waiting to be moved onto the open day. See Receipts left on a day closed in the portal |
DigiTax sends the zimra.submission.halted callback when sending halts.
Test businesses share a deviceTest businesses share DigiTax's test device. Another business's receipt can halt sending, or hold a fiscal day open, for everyone on that device. In that case
blocking_receipt_idis empty. This doesn't happen in production, where your device is your own.
Updated about 2 hours ago