HeroJSON Specification

Merchant object

"merchant": {
    "name": "Global Receipt Delicatesse",
    "companyID": "123456-7",
    "branch": {
      "id": "340",
      "posId": "2",
      "name": "Receipt Restaurant",
      "subName":"FastFood",
      "email": "[e-mail]",
      "phone": "040-5086462",
      "websiteURL": "https://www.getreceipthero.com/",
      "address": {
        "streetAddress": "Itsenäisyydenkatu 17 a 15",
        "city": "Tampere",
        "zipCode": "33500",
        "country": "Finland"
      }
    }

Key	Type	Description	Required
name	String	Company name	✅
companyID	String	Company's business id or VAT number	✅

Branch object

Key	Type	Description	Required
id	String	Unique identifier for a branch (e.g., cost center number or another identifier used to distinguish branches of a Merchant)	✅
posId	String	Logical cash register id	✅
name	String	Branch name	✅
subName	String	Freetext slogan etc, placed under branch name
email	String	Email address to branch / company support
phone	String	Phone number to branch / company support
websiteURL	String	Website URL of branch / company
address	Object	Address values	✅
〰️ streetAddress	String	Branch location street address	✅
〰️ city	String	Branch location city	✅
〰️ zipCode	String	Branch location zip code	✅
〰️ country	String	Branch location country	✅

Products array

Products array contains all product on receipt

 "products": [
    {
      "name": "Ground Control",
      "EANCode": "42222130165",
      "quantity": "4",
      "productId": "1234",
      "quantityCode": "PCS",
      "freeText": "Product instructions etc",
      "categorization": { "main": "12", "product": "122", "sub": "1224" },
      "unitPriceIncVAT": 5180,
      "unitPriceIncVATDecimal": "51,80",
      "totalAmountExcVAT": 18836,
      "totalAmountIncVAT": 20720,
      "vats": [
        {
          "VATRate": "24",
          "VATAmount": 1884,
          "totalAmountExcVAT": 18836,
          "totalAmountIncVAT": 20720
        }
      ],
      "discounts": [
        {
          "amount": 0,
          "percentage": "0.00",
          "description": ""
        }
      ],
      "customAttributes": [
        { "Warranty": "2 years" },
        { "Valid until": "2020-11-26" }
      ]
    }
  ],

Key	Type	Description	Required
name	String	Product name	✅
EANCode	String	Product EAN code
quantity	String	Quantity of product	✅
productId	String	Merchants internal productID
quantityCode	String	Quantity code for product	✅
freeText	String	Product related text field
unitPriceIncVAT	Integer	Unit price including VAT in fractional unit (Cents in Euros etc.)	✅
unitPriceIncVATDecimal	String	Unit price including VAT in main currency unit. Mainly used by petrol receipts
totalAmountExcVAT	Integer	Total price for product row without VAT in fractional unit	✅
totalAmountIncVAT	Integer	Total price for product row with VAT in fractional unit	✅
vats	Array	Product level VAT specifications One object represents one VAT rate. If product has multiple taxrates -> multiple objects	✅
〰️ VATRate	String	VAT rate. Integer or Decimal	✅
〰️ VATAmount	Integer	VAT amount in fractional unit	✅
〰️ totalAmountExcVAT	Integer	Amount without VAT in fractional unit	✅
〰️ totalAmountIncVAT	Integer	Amount with VAT in fractional unit	✅
discounts	Array	Product level discount objects.
〰️ amount	Integer	Amount of discount in fractional unit	✅
〰️ percentage	String	Discount percentage in decimal
〰️ description	String	Discount reason in free text	✅
customAttributes	Array	Key value pair for custom attributes on product These key value pair will be shown on receipt as table under product.
〰️ key	String	Free key name	✅
〰️ value	String	Free value	✅

Product Categorization

"categorization": 
  { 
    "main": "12",
    "product": "122",
    "sub": "1224",
    "tags": ["stampcard-identifier"]
  }

Key	Type	Description	Required
main	String	Main category identifier
product	String	Product category identifier	✅
sub	Integer	Sub category identifier
tags	String Array	A list of custom tags, used for purposes such as marking a product's inclusion in a stamp card offer

Product Journey

When dealing with travel-related products such as bus, train, taxi, or other transportation services, it is possible to include structured journey details alongside the product line item. The journey object allows specifying relevant metadata such as the type of transport, schedule, distance, emissions, and location data for both origin and destination.

"journey": {
  "type": "TRAIN",
  "id": "IC924",
  "distance": 185000,
  "duration": 120,
  "CO2Emissions": 222,
  "origin": {
    "name": "Pasila",
    "city": "Helsinki",
    "country": "Finland",
    "latitude": "60.1988",
    "longitude": "24.9333",
    "datetime": "2025-04-02T10:00:00+02:00"
  },
  "destination": {
    "name": "Turku (City Centre, Logomo)",
    "city": "Helsinki",
    "country": "Finland",
    "latitude": "60.45694",
    "longitude": "22.25750",
    "datetime": "2025-04-02T12:00:00+02:00"
  }
}

Journey Object

Key	Type	Description	Required
type	String	Type of Journey Allowed values TRAIN BUS TAXI FLIGHT FERRY	✅
id	String	Journey identifier, such as train connection or flight number
distance	Number	Journey distance in meters
duration	Number	Journey duration in minutes
CO2Emissions	Integer	CO2 Emissions in grams
origin	Journey Location Object	Journey origin	✅
destination	Journey Location Object	Journey destination	✅

Journey Location Object

Key	Type	Description	Required
name	String	Journey location name	✅
city	String	Journey location city
country	String	Journey location country
latitude	String	Journey location latitude
longitude	String	Journey location longitude
datetime	String	Departure or Arrival time as ISO 8601 datetime with offset

Receipt VAT specification

 "vats": [
    {
      "VATRate": "24",
      "totalVATAmount": 1884,
      "totalAmountExcVAT": 18836,
      "totalAmountIncVAT": 20720,
      "VATCode": "A"
    }
  ],

Key	Type	Description	Required
vats	Array	Receipt total VATs as array of objects per VAT rate	✅
〰️ VATRate	String	VAT rate. Integer or Decimal	✅
〰️ totalVATAmount	Integer	VAT amount in fractional unit	✅
〰️ totalAmountExcVAT	Integer	Amount without VAT in fractional unit	✅
〰️ totalAmountIncVAT	Integer	Amount with VAT in fractional unit	✅
VATCode	String	VAT identifier

Payments

HeroJSON supports a variety of payment types including card, cash, gift card, and online payments — see the full list of Payment Types for details. Payments are mapped as an array of Payment Objects as shown in the example below.

Payments Example

  "payments": [
    {
      "type": "CARD",
      "amount": 20720,
      "attributes": {
        "cardType": "Debit Mastercard",
        "maskedPAN": "557760******3201",
        "timeStamp": "2022-09-01T12:35:34.678+02:00",
        "terminalId": "BS-4545F9",
        "referenceNumber": "220901015555",
        "authorizationCode": "HIU456",
        "authorizationMethodType": "CHIP_AND_PIN",
        "transactionId": "05555",
        "transactionType": "PURCHASE",
        "transactionRawText": "CARD TRANSACTION\n\nCard: Debit Mastercard\n **** **** **** 3201 LN\nApplication: A0000000041010\nTr.Nr/Auth: 05555/HIU456\nPayee/business: 0029432413000/0001\n\nReference: 220901015555\n\nCredit/Charge 207,20 EUR\nPayPass Contactless \n\n"
      }
    },
    {
      "type": "CASH",
      "amount": 34920,
      "attributes": {
        "handedAmount": 40000
      }
    }
  ]

General Receipt Data

 "type": "PURCHASE",
 "customAttributes": [
    { "key": "value" },
    { "key2": "value2" },
    { "key3": "value3" }
  ],
  "freeText": "Custom greetings etc",
  "receiptNumber": "89942344234",
  "receiptTimeStamp": "2018-11-26T12:35:34.678+02:00",
  "currencyISOCode": "EUR",
  "totalVATAmount": 1884,
  "totalPriceExcVAT": 18836,
  "totalPriceIncVAT": 20720,
}

Key	Type	Description	Required
type	String	Type of Receipt Allowed values PURCHASE RETURN
freeText	String	Freetext field to be displayed on receipt
receiptNumber	String	Merchant's internal receiptnumber	✅
receiptTimeStamp	String	ISO 8601 datetime with offset	✅
currencyISOCode	String	Currency code	✅
totalVATAmount	Integer	Total VAT amount in fractional unit	✅
totalPriceExcVAT	Integer	Total price excluding VAT	✅
totalPriceIncVAT	Integer	Total price including VAT	✅
customAttributes	Array	Key value pair list, to be show on receipt
〰️ Key	String	Free text key	✅
〰️ Value	String	Free text value	✅

Verifications array

"verifications": [
  {
    "type": "OCMF",
    "version": "1.0",
    "publicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEqHEykfqZhspgok6zCQh/329B38xine8ujzT8p5Nh7lek47cYeZj507aN6E4/QirF1b7Q57ln4VGfK6h0d0GOQA==",
    "transactionId": "848182519",
    "currentType": "AC",
    "transactionBegin": {
      "signedData": "OCMF|{\"FV\" : \"1.0\",\"GI\" : \"Nano CH-10311C\",\"GS\" : \"060643\",\"GV\" : \"v017\",\"PG\" : \"T198\",\"MV\" : \"DZG\",\"MM\" : \"DVH4013\",\"MS\" : \"1DZG0033016824\",\"IS\" : true,\"IL\" : \"VERIFIED\",\"IF\" : [\"RFID_NONE\",\"OCPP_NONE\",\"ISO15118_NONE\",\"PLMN_NONE\"],\"IT\" : \"EMAID\",\"ID\" : \"04ab076a345b85\",\"CT\" : \"CBIDC\",\"CI\" : \"CI\",\"RD\" : [{\"TM\" : \"2021-10-26T10:20:52,000+0200 I\",\"TX\" : \"B\",\"RV\" : \"       9.038\",\"RI\" : \"01-00:01.08.00.FF\",\"RU\" : \"kWh\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"}]}|{\"SA\" : \"ECDSA-secp256k1-SHA256\",\"SD\" : \"3046022100A4C188533ECA1793336520F7F99E010E62DEC32ABD344A562B00D396F65DFFE9022100CB0FB3782E406525641D689F4326D2118365A722EE75AAAB976C14B090BE49DA\"}"
    },
    "transactionEnd": {
      "signedData": "OCMF|{\"FV\" : \"1.0\",\"GI\" : \"Nano CH-10311C\",\"GS\" : \"060643\",\"GV\" : \"v017\",\"PG\" : \"T199\",\"MV\" : \"DZG\",\"MM\" : \"DVH4013\",\"MS\" : \"1DZG0033016824\",\"IS\" : true,\"IL\" : \"VERIFIED\",\"IF\" : [\"RFID_NONE\",\"OCPP_NONE\",\"ISO15118_NONE\",\"PLMN_NONE\"],\"IT\" : \"EMAID\",\"ID\" : \"04ab076a345b85\",\"CT\" : \"CBIDC\",\"CI\" : \"CI\",\"RD\" : [{\"TM\" : \"2021-10-26T10:21:22,000+0200 I\",\"TX\" : \"E\",\"RV\" : \"       9.038\",\"RI\" : \"01-00:01.08.00.FF\",\"RU\" : \"kWh\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"},{\"TM\" : \"2021-10-26T10:21:22,000+0200 I\",\"TX\" : \"E\",\"RV\" : \"      30\",\"RI\" : \"01-00:00.08.06.FF\",\"RU\" : \"sec\",\"RT\" : \"AC\",\"EF\" : \"\",\"ST\" : \"G\"}]}|{\"SA\" : \"ECDSA-secp256k1-SHA256\",\"SD\" : \"3045022016FD6DF51EE338CC56F6035670172653C93A77F263B7B24DD5DC84EF7C4A98AB022100ADE8D7D9EC4EFFE2B3C0781C108B9DF2688776F81AE94D9230C92ED570C9693C\"}"
    }
  }
]

Verification Object

Key	Type	Description	Required
type	String	Type of verification	✅
version	String	Standard version	✅
publicKey	String	Public key for verifying data	✅
transactionId	String	Transaction identifier	✅
currentType	String	Current type Allowed values AC DC	✅
transactionBegin	Transaction Event Object	Transaction Begin event data	✅ *
transactionEnd	Transaction Event Object	Transaction End event data	✅

* transactionBegin is mandatory when type=AC

Transaction Event Object

Key	Type	Description	Required
signedData	String	Signed transaction event data for verification	✅

Attachments

Attachments such as entrance tickets and gift cards can be included.

This is a premium feature. To enable this option, please reach out to the ReceiptHero sales team.

"attachments": [
    {
        "type": "QRCODE",
        "kind": "TICKET",
        "title": "Here is your ticket!",
        "description": "Present this code at the entrance to maintain your access.",
        "data": "89942344234",
        "validUntil": "2024-09-10T00:00:00.000+02:00"
    }
]

Key	Type	Description	Required
type	String	Type of attachment Allowed values BARCODE QRCODE	✅
kind	String	Kind represents the purpose of the attachment Allowed values TICKET RETURN VOUCHER	✅
title	String	Title shown on top of the attachment	✅
data	String	Data encoded to the attachment according to the provided type	✅
description	String	Description providing more details on how this attachment is used
validUntil	String	ISO 8601 string with offset, representing the last moment the attachment is valid for use