Skip to main content

Signing an Invoice

The core endpoint. Signs a sale on the Secure Element and returns the fiscal result (verification URL, QR, journal, signature). Requires a PIN previously verified via POST /api/v3/pin.

POST /api/v3/invoices
Content-Type: application/json
RequestId: 4b1e...unique-per-sale

Request fields

FieldTypeRequiredNotes
invoiceTypeenumYesNormal, ProForma, Copy, Training, Advance.
transactionTypeenumYesSale or Refund.
paymentarrayYesOne or more { amount, paymentType }. See payment types below.
itemsarrayYesOne or more line items. See item fields below.
dateAndTimeOfIssuestringNoISO date/time; defaults to the SDC clock if omitted.
cashierstringNo≤ 50 chars.
buyerIdstringNo≤ 20 chars (buyer TIN / ID).
buyerCostCenterIdstringNo≤ 50 chars.
invoiceNumberstringNo≤ 60 chars (your POS's own number/ordinal).
referentDocumentNumberstringConditional≤ 50 chars. The signed number of the original invoice — required for Copy and Refund, and whenever referentDocumentDT is present.
referentDocumentDTstringNoDate/time of the referent document; if present, referentDocumentNumber becomes required.
optionsobjectNoKey/value flags, e.g. { "omitTextualRepresentation": 1 } to skip building the journal text.

Item fields

FieldTypeRequiredNotes
namestringYes1–2048 chars.
quantitynumberYes≥ 0.001.
unitPricenumberYesPrice per unit.
labelsarrayYesTax label(s) for the item, e.g. ["A"]. Must be labels present in the active tax group (unknown labels are rejected).
totalAmountnumberYesLine total (quantity × unitPrice).
gtinstringNo8–14 chars if supplied.

Payment types

Other, Cash, Card, Check, WireTransfer, Voucher, MobileMoney.

Example request

{
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "cashier": "Jack",
  "payment": [
    { "amount": 23.00, "paymentType": "Cash" }
  ],
  "items": [
    {
      "name": "Coffee",
      "quantity": 2,
      "unitPrice": 5.00,
      "labels": ["A"],
      "totalAmount": 10.00
    },
    {
      "name": "Sandwich",
      "quantity": 1,
      "unitPrice": 13.00,
      "labels": ["A"],
      "totalAmount": 13.00
    }
  ]
}

Response

On success the SDC returns the fiscal result. Field names are camelCase (see Swagger for the exact schema of your build):

FieldMeaning
invoiceNumberThe signed fiscal invoice number.
invoiceCounter / invoiceCounterExtensionPer-type and combined counters.
totalCounter / transactionTypeCounterRunning counters from the SE.
verificationUrlThe URL a customer uses to verify the invoice with FRCS.
verificationQRCodeThe QR code (base64) encoding the verification URL — print this on the receipt.
journalThe formatted textual receipt (40-column). Omitted if options.omitTextualRepresentation is set.
signature / encryptedInternalDataThe SE signature and encrypted internal data.
signedBy / requestedBySE / requesting-signer identifiers.
taxItemsPer-category tax lines: label, categoryName, rate, amount.
totalAmountInvoice total.
taxGroupRevisionRevision of the tax group applied.
businessName, tin, locationName, address, district, mrcSeller details for the receipt header.
sdcDateTimeThe signing date/time.
 
200 OK
{
  "invoiceNumber": "EKLBHT3Y-EKLBHT3Y-31",
  "verificationUrl": "https://sandbox.vms.frcs.org.fj/v/?vl=...",
  "verificationQRCode": "iVBORw0KGgoAAAANSUhEUgAA...",
  "journal": "============ FISCAL INVOICE ============ ...",
  "totalAmount": 23.00,
  "taxItems": [
    { "label": "A", "categoryName": "VAT", "rate": 15.0, "amount": 3.00 }
  ],
  "sdcDateTime": "2026-08-13T09:42:00"
}

Refunds & copies

For a Refund (or a Copy), set transactionType/invoiceType accordingly and reference the original signed invoice with referentDocumentNumber (and optionally referentDocumentDT). Taxes for a copy/refund are calculated using the tax group in force at the referent document's date.

Validate without signing

POST /api/v3/invoices/validate runs the same request validation and tax rules without touching the card — useful to check a basket before committing. It returns { "valid": true } or a 400 with field errors (see "Errors & Validation").

Back to top