Custom POS & Direct REST API Guide

Learn how to generate Bearer API keys and send JSON receipt payloads directly to Mutero VFD from custom POS software, web checkout engines, or ERP backends.

Direct Synchronous Fiscalization

The Mutero REST API returns official ZIMRA digital signatures, receipt numbers, and QR verification URLs synchronously within 200ms.

Same FDMS rules as other integrations

Send explicit zimra_tax_id (1 / 2 / 3) or a known tax label. Unknown taxes are blocked — they never silently become 15%. Zero-rated / exempt lines need an 8-digit hs_code. Include customer.tin with a real customer name so Mutero can emit ZIMRA buyerData. Optional tax_inclusive is persisted for correct RCPT026/027 totals.

1Generate Bearer API Key

Go to API Keys Manager in your Mutero Dashboard. Click Generate New API Key and select your target Virtual Fiscal Device.

Authorization Header Formathttp

Authorization: Bearer mtr_live_9a8b7c6d5e4f3a2b1c...

2Submit Receipt for Fiscalization

Send a HTTP POST request to the receipt submission endpoint:

POST /api/v1/vfd/receipts Request Payloadjson

{
  "device_id": "vfd_dev_65f4e3a2b1c",
  "invoice_number": "INV-2026-089",
  "currency": "USD",
  "tax_inclusive": false,
  "customer": {
    "name": "Acme Zimbabwe Ltd",
    "tin": "2001984756"
  },
  "items": [
    {
      "item_name": "Dell XPS 15 Laptop",
      "quantity": 1,
      "unit_price": 1200.00,
      "total_amount": 1200.00,
      "zimra_tax_id": 1,
      "hs_code": "8471.30.00"
    }
  ]
}

3Synchronous Fiscal Verification Response

Mutero responds with the official ZIMRA signature, receipt number, and verification link for printing QR codes on customer receipts:

200 OK Response Payloadjson

{
  "success": true,
  "receipt_number": "ZIMRA-2026-0098475",
  "verification_url": "https://fdms.zimra.co.zw/verify/ZIMRA-2026-0098475",
  "qr_code_data": "https://fdms.zimra.co.zw/verify/ZIMRA-2026-0098475",
  "zimra_signature": "MEQCID3k8A...==",
  "status": "VERIFIED"
}

How to issue a credit note

Easiest option: Mutero web app

Open the fiscalised invoice in the Mutero web app, then click Issue Credit Note. Use the API below only when your POS / backend needs to issue credits automatically.

Or send a credit note to Mutero with the original invoice (or FRN) and a reason:

Endpointhttp

POST /api/v1/vfd/receipts/credit-note

Examplejson

{
  "original_invoice_number": "INV-2026-089",
  "reason": "Customer returned goods",
  "credit_note_number": "CN-2026-089"
}

Use original_invoice_number or original_fiscal_receipt_number.
reason is required.
Leave lines out to credit the full invoice, or send specific line numbers/quantities for a partial credit.