Micros POS Integration Guide

This is the integration contract for connecting Oracle Simphony (Micros POS) terminals to the middleware. It covers the endpoint, authentication, the full payload schema, field reference, document types, responses and errors.

Endpoint

POST  https://server.zra.co.zm/pckzra/api/taxint/pos/upload

Header	Value	Description
`Content-Type`	`application/json`	Request body format
`Accept`	`application/json`	Expected response format
`Authorization`	`Bearer <JWT_TOKEN>`	Oracle Restaurant IDM JWT token

Use cases covered by this one endpoint: standard invoices (sales), credit notes (refunds/voids) and debit notes (adjustments). A health check is available at GET /pckzra/api/taxint/health.

Removed endpoints POST /pos/fiscal-update and GET /api/taxint/statistics are not supported. Statistics are available via the Reports API only.

Complete payload schema

{
  "DocumentInfo": {
    "FolioType": "Invoice",
    "FiscalFolioId": "",
    "Application": "POS",
    "PropertyTaxNumber": "1234567890"
  },
  "FolioInfo": {
    "FolioHeaderInfo": {
      "FolioType": "STD",
      "AssociatedBillFiscalBillNo": "",
      "InvoiceCurrencyCode": "ZMW",
      "InvoiceCurrencyRate": 1.0,
      "CashierNumber": "CASHIER01"
    },
    "Postings": [
      {
        "TrxNo": 1,
        "TrxCode": "ITEM-001",
        "UnitPrice": 100.00,
        "Quantity": 2,
        "NetAmount": 200.00,
        "GrossAmount": 232.00,
        "Product": "Product Description"
      }
    ],
    "TrxInfo": [
      {
        "Code": "ITEM-001",
        "TrxType": "C",
        "Description": "POS Transaction",
        "FiscalTrxCodeType": "A"
      }
    ]
  },
  "SellerInfo": {
    "SellerName": "Store Name",
    "Address": {
      "Address": "123 Main Street",
      "City": "Lusaka",
      "Country": "Zambia",
      "PostalCode": 10101,
      "State": "Lusaka Province"
    },
    "SellerContactDetails": { "Number": "+260 211 123456" },
    "SellerBRN": "BRN123456"
  },
  "PaymentInfo": {
    "PaymentType": "Cash",
    "TotalWoVat": 200.00,
    "Total": 232.00
  }
}

Field reference

DocumentInfo

Field	Type	Required	Description	Valid values
`FolioType`	String	Yes	Type of document	`Invoice`, `CRN`, `DRN`
`FiscalFolioId`	String	Yes	Folio identifier; must be non-blank	Any string
`Application`	String	Yes	Application type	Always `POS`
`PropertyTaxNumber`	String	Yes	Store TPIN for ZRA	Valid TPIN

FolioInfo.FolioHeaderInfo

Field	Type	Required	Description
`FolioType`	String	Yes	`STD`, `CRN` or `DRN`
`AssociatedBillFiscalBillNo`	String	For CRN/DRN	Original invoice's fiscal bill number
`InvoiceCurrencyCode`	String	Yes	ISO currency code, `ZMW` for Kwacha
`InvoiceCurrencyRate`	Decimal	Yes	Exchange rate, `1.0` for local currency
`CashierNumber`	String	Yes	Cashier/register identifier — becomes the Chrilan `auditNumber`

FolioInfo.Postings (line items)

Field	Type	Required	Description
`TrxNo`	Integer	Yes	Sequential line number
`TrxCode`	String	Yes	Product code — must match a TrxInfo `Code`
`UnitPrice`	Decimal	Yes	Price per unit
`Quantity`	Decimal	Yes	Quantity sold
`NetAmount`	Decimal	Yes	Amount before tax (UnitPrice × Quantity)
`GrossAmount`	Decimal	Yes	Amount including tax
`Product`	String	Yes	Product description
`Remark`	String	For CRN	Reason for the credit note (at least one line)

FolioInfo.TrxInfo (VAT classification)

Field	Type	Required	Description
`Code`	String	Yes	Must match the Posting's `TrxCode`
`TrxType`	String	Yes	Transaction type
`Description`	String	Yes	Description
`FiscalTrxCodeType`	String	Yes	VAT category code (see below)

VAT category codes

Code	Description	ZRA classification
`A`	Standard rate	Standard VAT (16%)
`D`	Zero rated	Zero-rated by nature
`E`	Exempt	Tax exempt
`T`	Tourism levy	Treated as standard rated

SellerInfo

Field	Type	Required	Description
`SellerName`	String	Yes	Store identifier used for the API-key lookup — must exactly match the registered store
`SellerBRN`	String	No	Business Registration Number
`Address`	Object	Yes	Store address details
`SellerContactDetails`	Object	Yes	Store contact information (`Number` becomes the Chrilan `cell`)

PaymentInfo

Field	Type	Required	Description
`PaymentType`	String	Yes	`Cash` or `Card`
`TotalWoVat`	Decimal	Yes	Total excluding VAT (sum of NetAmount)
`Total`	Decimal	Yes	Total including VAT (sum of GrossAmount)

BuyerInfo (optional)

Field	Description
`BuyerTIN`	Buyer/customer TPIN — mapped to the Chrilan `tpin` field (empty string if absent)
`BuyerLpo`	LPO number — sets Chrilan `lpo` and `isLpo`
Buyer address fields	Passed through to the response for POS check printing

Successful response (HTTP 200)

{
  "fiscalFolioNo": "211",
  "fiscalBillGenerationDateTime": "2026-01-14T11:32:01",
  "fiscalOutputs": {
    "output": [
      { "name": "COLL_TAX1",              "value": "211" },
      { "name": "QR_CODE_URL",            "value": "https://siportal.zra.org.zm/common/link/ebm/receipt/indexEbmReceiptData?Data=..." },
      { "name": "BASE64_TO_IMAGE",        "value": "iVBORw0KGgoAAAANSUhEUg..." },
      { "name": "sdcId",                  "value": "SDC0010022742" },
      { "name": "mrcNo",                  "value": "WIS00037264" },
      { "name": "intrlData",              "value": "IXCI2VHBMB3QWYTQJC4G5W6L4M" },
      { "name": "rcptSign",               "value": "4BQOZAXZVTQGRLAQ" },
      { "name": "taxData",                "value": "ZRA Invoice: INV0010022742/3470\n..." },
      { "name": "vsdcRcptPbctDate",       "value": "20260114113201" },
      { "name": "$PartnerFiscalStatus$",  "value": "COMPLETED" }
    ]
  },
  "statusMessages": { "messages": [] }
}

Field	Description
`fiscalFolioNo`	ZRA fiscal receipt number
`QR_CODE_URL` / `BASE64_TO_IMAGE`	QR code as URL and as base64 image for printing
`sdcId`, `mrcNo`	Smart Device Controller ID and MRC number
`rcptSign`	Digital receipt signature
`taxData`	Tax breakdown text for the receipt
$PartnerFiscalStatus$	`COMPLETED` or `FAILED`

Document types

Standard invoice (STD)

Normal sale: DocumentInfo.FolioType = "Invoice", FolioHeaderInfo.FolioType = "STD".

Credit note (CRN)

Refund or void. Requirements:

FolioType = CRN in both DocumentInfo and FolioHeaderInfo
AssociatedBillFiscalBillNo = the original invoice's fiscal bill number
At least one Posting includes a Remark explaining the reason

The middleware automatically looks up the original receipt number and SDC ID from its database and links the refund at ZRA.

Error handling

HTTP	Meaning	Typical cause
200	Success	Invoice registered at ZRA
400	Bad Request	Validation failed — missing/invalid fields
401	Unauthorized	Invalid or missing JWT
403	Forbidden	Store not registered or inactive
500	Server Error	Chrilan API failure or internal error

{
  "error": "Validation failed",
  "details": [
    "PropertyTaxNumber is required",
    "FolioType must be Invoice, CRN, or DRN"
  ]
}

Error	Cause	Resolution
`SellerName is required`	Missing SellerInfo/SellerName	Include the SellerInfo block with SellerName
`Store not registered: X`	SellerName not in the middleware database	Register the store; check exact spelling
`PropertyTaxNumber is required`	Missing TPIN	Include a valid TPIN in DocumentInfo
`TrxInfo missing for TrxCode`	A Posting has no matching TrxInfo entry	Ensure every TrxCode has a TrxInfo.Code

Critical integration rules

TrxCode linkage Every Posting must have a TrxInfo entry with a matching Code. This linkage determines the VAT treatment of the line.

SellerName must match exactly the value registered in the middleware (case and spacing included).
Amount consistency: NetAmount = UnitPrice × Quantity; PaymentInfo totals must equal the sums of the line amounts.
Currency: pass-through; use ZMW with rate 1.0 for local sales.