Feature: Callback URLs

Learn how to use callback URLs to hear about flagged receipts, halted sending and restamped receipts

Understanding Callback URLs

When you issue a receipt, DigiTax responds straight away, with the receipt's status set to PENDING. DigiTax then sends the receipt to ZIMRA in the background.

Below is a snippet of the response to a POST receipts request.

{
  "id": "receipt_01HC3J1VVVM05YCTS61G7V3KC6",
  "fiscal_day_no": 103,
  "receipt_global_no": 4822,
  "invoice_number": "25415-4822",
  "trader_invoice_number": "INV-001",
  "status": "PENDING",
  "submit_attempts": 0,
  "verification_code": "4C8B-E276-6333-0417",
  // other key-value pairs
}

Once ZIMRA has the receipt, its status changes to ACCEPTED or FLAGGED, which you can see in the DigiTax Dashboard or with a GET request:

{
  "id": "receipt_01HC3J1VVVM05YCTS61G7V3KC6",
  "status": "ACCEPTED",
  "fdms_receipt_id": 9081726,
  "fdms_operation_id": "0HN7VQ2B3K4L5:00000001",
  "submitted_at": "2026-07-14T09:15:03+02:00",
  "validation_errors": [],
  // other key-value pairs
}

Most receipts are simply accepted. Callback URLs tell you, as soon as it happens, about the events that need your attention, so you don't have to poll for them. See Receipt statuses and validation for what each status means.

Configure callbacks in the DigiTax Dashboard

Callback URLs are set per business in the DigiTax Dashboard. Test and Live are configured separately, so set your URLs in each environment you use.

Step 1: Open Event Callbacks

In the sidebar, open Integrations, then click Event Callbacks.

Step 2: Choose an event

The Event Callbacks page lists the events you can subscribe to. Click + Add Callback URL next to the event you want.

Eventevent valueFired when
ZIMRA Receipt Flaggedzimra.receipt.flaggedZIMRA grades a receipt it received Red or Grey, marking it FLAGGED. The sale is fiscalised and must not be issued again, and its fiscal day can't be closed through FDMS while the grade stands
ZIMRA Submission Haltedzimra.submission.haltedYour device's receipts stop being sent to ZIMRA until the cause is fixed
ZIMRA Receipt Restampedzimra.receipt.restampedAn unsent receipt is moved onto a new fiscal day and signed again, which changes its verification code and QR

Step 3: Enter your URL and save

Enter an HTTPS URL, for example https://your-server.com/webhooks/zimra, then click Save.

How callbacks work

  • DigiTax sends a JSON payload to your URL with a POST request when the event fires.
  • Every payload has the same envelope: the event's details in data, and the event's name in event.
  • Every time in a payload is RFC 3339 in Central Africa Time (+02:00).
  • HTTPS is required so payloads stay encrypted in transit.
  • Each callback is delivered once, on a best-effort basis. Answer with a 2xx status quickly. If you miss one, the same information is on GET /receipts and GET /fdms-info.
  • You can toggle a callback off at any time without deleting its URL.
  • The Delivery readiness panel shows how many events have a callback URL configured.

Payloads

zimra.receipt.flagged

{
  "data": {
    "branch_id": "zimrabranch_01HC3J1VVVM05YCTS61G7V3KC6",
    "zimra_device_id": "25415",
    "receipt_id": "receipt_01HC3J1VVVM05YCTS61G7V3KC6",
    "trader_invoice_number": "INV-001",
    "invoice_number": "25415-4822",
    "receipt_global_no": 4822,
    "fiscal_day_no": 103,
    "fdms_receipt_id": 9081726,
    "fdms_operation_id": "0HN7VQ2B3K4L5:00000001",
    "status": "FLAGGED",
    "validation_colour": "Grey",
    "validation_errors": [
      {
        "code": "RCPT011",
        "colour": "Grey",
        "description": "Previous receipt missing"
      }
    ]
  },
  "event": "zimra.receipt.flagged"
}

What to do: don't issue the receipt again. A Grey grade clears by itself. For a Red grade, issue a credit note and a new receipt only if the sale itself was wrong, and contact DigiTax support about closing the fiscal day. See Flagged receipts.

zimra.submission.halted

{
  "data": {
    "branch_id": "zimrabranch_01HC3J1VVVM05YCTS61G7V3KC6",
    "zimra_device_id": "25415",
    "halt_source": "FDMS_REJECTION",
    "reason": "<what stopped sending>",
    "blocking_receipt_id": "receipt_01HC3J1VVVM05YCTS61G7V3KC6",
    "blocking_receipt_global_no": 4822,
    "halted_at": "2026-11-09T12:27:53+02:00"
  },
  "event": "zimra.submission.halted"
}

halt_source is FDMS_REJECTION (ZIMRA refused a receipt; DigiTax retries every 15 minutes) or RECONCILE (ZIMRA's records disagree with DigiTax's; DigiTax support resumes sending). blocking_receipt_id and blocking_receipt_global_no are left out when the receipt sending stopped at isn't yours, as can happen on the shared test device.

What to do: keep issuing receipts. They stay PENDING until sending resumes, and the fiscal day can't close until then. See When sending halts.

zimra.receipt.restamped

{
  "data": {
    "branch_id": "zimrabranch_01HC3J1VVVM05YCTS61G7V3KC6",
    "zimra_device_id": "25415",
    "receipt_id": "receipt_01HC3J1VVVM05YCTS61G7V3KC6",
    "trader_invoice_number": "INV-001",
    "invoice_number": "25415-4822",
    "receipt_global_no": 4822,
    "previous_fiscal_day_no": 103,
    "fiscal_day_no": 104,
    "receipt_counter": 1,
    "receipt_date": "2026-07-15T09:02:11+02:00",
    "verification_code": "9D1A-03F2-77B4-1C60",
    "qr_url": "<ZIMRA's verification URL for the receipt>"
  },
  "event": "zimra.receipt.restamped"
}

What to do: replace any copy of the receipt you've already printed or sent to the buyer, using the new verification_code and qr_url. The old ones no longer check out with ZIMRA. See Receipts left on a day closed in the portal.