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

  1. 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.
  2. 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.
  3. ZIMRA grades it. ZIMRA records the receipt and may grade it Red, Grey or Yellow if it finds a problem.

Receipt statuses

statusMeaningWhat to do
PENDINGIssued and signed, but ZIMRA hasn't received it yetNothing. Check last_submit_error if it stays pending, and see When sending halts
ACCEPTEDZIMRA received it with no findings, or only Yellow onesNothing
FLAGGEDZIMRA 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

ColourReceipt statusBlocks the fiscal day from closing?Clears by itself?
🟡 YellowACCEPTEDNoNot needed
⚪ GreyFLAGGEDYesYes, once the missing earlier receipt reaches ZIMRA
🔴 RedFLAGGEDYesNo. The day can only be closed in ZIMRA's portal

Flagged receipts

❗️

Never issue a FLAGGED receipt again

A 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 example RCPT019,RCPT047
  • fields: the request fields concerned, comma-separated, for example total_cents,lines[0].hs_code
  • violations: a JSON array (as a string) of {code, colour, field, message, line_no, meta}, one per broken rule. line_no is 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:

CodeRule
RCPT019total_cents must equal the total worked out from the lines and their taxes
RCPT022A line's price_cents has the wrong sign for the receipt and line type
RCPT024A line's total must be its price times its quantity, rounded to the cent
RCPT034A credit or debit note needs notes saying why it was issued
RCPT047hs_code must be 4 or 8 digits, and is required on a sale line for a VAT-registered taxpayer
RCPT048hs_code must be 8 digits on a sale line whose tax is 0% or exempt
LOCAL_TAXtax_id is not one of the device's taxes valid at the receipt date. List them with GET /resources/tax-categories
LOCAL_PAYMENTSPayments must add up to the receipt total, with the receipt's sign
LOCAL_SIGNAn 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:

FieldMeaning
haltedtrue while sending is stopped
halt_sourceFDMS_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_atWhat stopped sending, and when
blocking_receipt_idYour 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_atReceipts not yet received by ZIMRA
stranded_receipt_countUnsent 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 device

Test 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_id is empty. This doesn't happen in production, where your device is your own.


Did this page help you?