HeroJSON Specification
Merchant object
"merchant": {
"name": "Global Receipt Delicatesse",
"companyID": "123456-7",
"branch": {
"id": "340",
"posId": "2",
"name": "Receipt Restaurant",
"subName":"FastFood",
"email": "[email protected]",
"phone": "040-5086462",
"websiteURL": "https://www.getreceipthero.com/",
"address": {
"streetAddress": "Itsenäisyydenkatu 17 a 15",
"city": "Tampere",
"zipCode": "33500",
"country": "Finland"
}
}name
String
Company name
✅
companyID
String
Company's business id or VAT number
✅
Branch object
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
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" }
]
}
],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"]
}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
type
String
Type of Journey
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
Journey Location Object
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"
}
],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,
}type
String
Type of Receipt
PURCHASE
RETURNfreeText
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
type
String
Type of verification
✅
version
String
Standard version
✅
publicKey
String
Public key for verifying data
✅
transactionId
String
Transaction identifier
✅
currentType
String
Current type
AC
DC✅
transactionBegin
Transaction Event Object
Transaction Begin event data
✅ *
transactionEnd
Transaction Event Object
Transaction End event data
✅
Transaction Event Object
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"
}
]type
String
Type of attachment
BARCODE
QRCODE✅
kind
String
Kind represents the purpose of the attachment
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
Last updated