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"
      }
    }

Key

Type

Description

Required

name

String

Company name

✅

companyID

String

Company's business id or VAT number

✅

Branch object

Key

Type

Description

Required

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" }
      ]
    }
  ],

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

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

✅

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": {
        "transactionType": "PURCHASE",
        "currencyISOCode": "EUR",
        "MID": "12346543",
        "timeStamp": "2022-09-01T12:35:34.678+02:00",
        "terminalId": "BS-4545F9",
        "referenceNumber": "220901015555",
        "authorizationCode": "HIU456",
        "transactionId": "05555",
        "receiptNumber": "12923",
        "maskedPAN": "525400******9876",
        "APP": "MASTERCARD DEBIT",
        "cardType": "DEBIT",
        "cardProgram": "Nordic Tech Bank — MC Debit",
        "transactionRawText": "CARD TRANSACTION\n\nCard: Debit Mastercard\n **** **** **** 9876 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",
        "preAuthorizedAmount": 30000,
        "ENTRY": "Contactless ICC (07)",
        "ARC": "APPROVED (00)",
        "TVR": "8000008000",
        "TSI": "E800",
        "AID": "A0000000031010",
        "AC": "9F270180",
        "CID": "0x80 (ARQC)",
        "CVM": "Online PIN"
      }
    },
    {
      "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
PURCHASE_AND_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

PreviousReceiptHero JSON NextPayment Types

Last updated 2 months ago

hashtagMerchant object

hashtagBranch object

hashtagProducts array

hashtagProduct Categorization

hashtagProduct Journey

hashtagJourney Object

hashtagJourney Location Object

hashtagReceipt VAT specification

hashtagPayments

hashtagPayments Example

hashtagGeneral Receipt Data

hashtagVerifications array

hashtagVerification Object

hashtagTransaction Event Object

hashtagAttachments

Merchant object

Branch object

Products array

Product Categorization

Product Journey

Journey Object

Journey Location Object

Receipt VAT specification

Payments

Payments Example

General Receipt Data

Verifications array

Verification Object

Transaction Event Object

Attachments