Create a receipt

Issue your first ZIMRA fiscal receipt with the DigiTax Zimbabwe API

This guide takes you from an API key to an accepted fiscal receipt. You'll need an X-API-Key for a test business. See Prerequisites of using the API.

Step 1: Check your device

Call GET /fdms-info and check that:

  • status is ACTIVE and is_live is true. Otherwise receipts can't be issued yet, and POST /receipts returns 412.
  • vat_number is set or empty. This decides whether hs_code is required. See HS codes.
  • receipt_submission.halted is false. If it's true, new receipts will wait as PENDING. See When sending halts.

Step 2: Get your device's taxes

Call GET /resources/tax-categories and pick the tax_id for each line. Tax IDs are specific to each device, so read them from this endpoint rather than hard-coding them.

[
  {
    "tax_id": 517,
    "name": "Standard rated 15.5%",
    "tax_percent": 15.5,
    "exempt": false
  }
]

Step 3 (optional): Set up items and customers

You can keep a catalogue of items and customers and refer to them by ID, or skip this step and send everything inline with each receipt.

Step 4: Issue the receipt

There are two ways to issue a receipt. They validate a receipt in exactly the same way:

EndpointLines and buyer
POST /receiptsYou send each line's name, tax and HS code, and the buyer's details, in full
POST /detailed-receiptsEach line names a catalogue item (item_id) or defines one (item), and the buyer names a customer (customer_id) or defines one (customer). New items and customers are created together with the receipt, and a refused receipt creates none of them

A cash sale of two litres of milk, tax included, on POST /receipts:

{
  "receipt_type": "FiscalInvoice",
  "currency": "USD",
  "trader_invoice_number": "INV-001",
  "lines_tax_inclusive": true,
  "lines": [
    {
      "line_type": "Sale",
      "hs_code": "04011000",
      "name": "Fresh milk 1L",
      "price_cents": 150,
      "quantity_milli": 2000,
      "total_cents": 300,
      "tax_id": 517
    }
  ],
  "payments": [
    { "money_type": "Cash", "amount_cents": 300 }
  ],
  "total_cents": 300,
  "buyer": {
    "register_name": "Acme Holdings (Private) Limited",
    "trade_name": "Acme",
    "vat_number": "220123456",
    "tin": "2000123456"
  },
  "print_form": "Receipt48"
}

The same sale on POST /detailed-receipts, using catalogue references:

{
  "receipt_type": "FiscalInvoice",
  "currency": "USD",
  "trader_invoice_number": "INV-001",
  "lines_tax_inclusive": true,
  "lines": [
    {
      "line_type": "Sale",
      "item_id": "item_01HC3J1VVVM05YCTS61G7V3KC6",
      "price_cents": 150,
      "quantity_milli": 2000,
      "total_cents": 300
    }
  ],
  "payments": [
    { "money_type": "Cash", "amount_cents": 300 }
  ],
  "total_cents": 300,
  "buyer": { "customer_id": "customer_01HC3J1VVVM05YCTS61G7V3KC6" },
  "print_form": "Receipt48"
}

What happens

DigiTax checks the receipt, numbers it, signs it and stores it on the open fiscal day, then responds with 201 Created. If no fiscal day is open, this receipt opens one. The receipt comes back with status: "PENDING", its receipt_global_no, verification_code and qr_url, and DigiTax sends it to ZIMRA in the background.

If the receipt breaks a rule, nothing is issued and you get 400 with the rules it broke. Fix the receipt and send it again with the same trader_invoice_number. See Checks before a receipt is issued.

📘

Retries are safe

If a request times out, send it again with the same trader_invoice_number. You get back the receipt already issued, not a second one.

Step 5: Follow the receipt to ZIMRA

Call GET /receipts/{receipt_id} until status is no longer PENDING:

  • ACCEPTED: ZIMRA has the receipt. fdms_receipt_id and submitted_at are set.
  • FLAGGED: ZIMRA has the receipt but graded it Red or Grey. Don't issue it again. See Receipt statuses and validation.

Instead of polling, set up the zimra.receipt.flagged callback to hear about flagged receipts as they happen. See Callback URLs.

Step 6: Print or send the receipt

Print the verification_code and encode qr_url as the receipt's QR code, so the buyer can verify the receipt with ZIMRA.

Correct a receipt

To refund or reduce a sale, issue a CreditNote with negative amounts, a reason in notes, and a reference to the original:

{
  "receipt_type": "CreditNote",
  "currency": "USD",
  "trader_invoice_number": "CN-001",
  "lines_tax_inclusive": true,
  "lines": [
    {
      "line_type": "Sale",
      "hs_code": "04011000",
      "name": "Fresh milk 1L",
      "price_cents": -150,
      "quantity_milli": 2000,
      "total_cents": -300,
      "tax_id": 517
    }
  ],
  "payments": [
    { "money_type": "Cash", "amount_cents": -300 }
  ],
  "total_cents": -300,
  "notes": "Returned - damaged packaging",
  "original_invoice_number": "INV-001",
  "print_form": "Receipt48"
}

See Credit and debit notes for the rules.


Did this page help you?