Fiscalise receipts from any system

Integration in six steps

From first email to a live merchant. Most integrations take two to five working days.

1. 1

   Contact QRFRS for a test device

   Before you write any code, email us and we set up an FDMS test device for you on the ZIMRA test environment. Self-service test devices are not available yet — every sandbox is provisioned by our team so the certificate, taxes and fiscal day are correct from day one.

   • Tell us the merchant name, TIN and VAT number (or use ours for a pure sandbox).
   • We register the test device, open a fiscal day and create the merchant portal account.
   • You receive the portal login plus a test API token — usually within one business day.
   
2. 2

   Get the API token

   The merchant opens their QRFRS portal, goes to Settings → External API and generates a token. One token per merchant, revocable at any time. Send it on every request.

   Authorization: Bearer <api_token>

3. 3

   Post each completed sale

   One HTTP call per sale, and one per refund (a CREDIT_NOTE referencing original_receipt_number). We fiscalise with ZIMRA and answer in the same response.

   curl -X POST https://qrfiscalreceipt.com/api/public/v1/receipts?formats=escpos80 \
     -H "Authorization: Bearer <api_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "receipt_number": "INV-000123",
       "receipt_date": "2026-08-28T10:15:00Z",
       "receipt_type": "SALE",
       "currency": "USD",
       "branch_id": "SHOP-01",
       "device_id": "TILL-2",
       "lines": [
         { "description": "Baby food puree", "hs_code": "21041000",
           "quantity": 5, "unit_price": 1.00, "line_total": 5.00,
           "tax_code": "A", "tax_rate": 15 }
       ],
       "payments": [{ "method": "Cash", "amount": 5.00 }],
       "total": 5.00
     }'

4. 4

   Print what comes back

   Write the ESC/POS bytes straight to the thermal printer, or open the A4 PDF. If you prefer your own layout, print our qr_url and verification_code on it — both are mandatory on a ZIMRA fiscal receipt.

   

   const bytes = Buffer.from(res.escpos_80_base64, "base64");
   socket.write(bytes);                       // network printer on port 9100
   // Windows: fs.writeFileSync("\\\\.\\USB001", bytes)

5. 5

   Certify on the test device

   Run your full flow against the test device: a normal sale, a multi-line sale, a zero-rated and an exempt line, a multi-currency sale, a credit note, and a retry of the same receipt_number. Send us the receipt numbers and we verify them against ZIMRA with you.

6. 6

   Go live

   The merchant registers their production ZIMRA device in the portal and generates a production token. Nothing changes in your code — swap the token, keep the same endpoints.

What the response looks like

{
  "receipt_id": "0f0b…",
  "receipt_number": "INV-000123",
  "status": "fiscalised",
  "fiscal_day_no": 42,
  "receipt_global_no": 1187,
  "verification_code": "A1B2-C3D4-E5F6",
  "qr_url": "https://receipt.zimra.org/…",
  "pdf_url": ".../api/public/v1/receipts/0f0b…/pdf",
  "escpos_url": ".../api/public/v1/receipts/0f0b…/escpos",
  "escpos_80_base64": "G0AbYQE…"
}

Re-posting the same receipt_number returns the original result with status: "duplicate" — retries never double-fiscalise.

Endpoints

Error codes