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:
statusisACTIVEandis_liveistrue. Otherwise receipts can't be issued yet, and POST /receipts returns 412.vat_numberis set or empty. This decides whetherhs_codeis required. See HS codes.receipt_submission.haltedisfalse. If it'strue, new receipts will wait asPENDING. 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:
| Endpoint | Lines and buyer |
|---|---|
| POST /receipts | You send each line's name, tax and HS code, and the buyer's details, in full |
| POST /detailed-receipts | Each 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 safeIf 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_idandsubmitted_atare 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.
Updated about 2 hours ago