HeroJSON Specification

Merchant object
"merchant": {
    "name": "Global Receipt Delicatesse",
    "companyID": "123456-7",
    "branch": {
      "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
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",
      "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
Products 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
✅
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 
Card Payment
  "payments": [
    {
      "type": "CARD",
      "amount": 20720,
      "attributes": {
        "cardType": "PaymentCard",
        "maskedPAN": "557760******3201",
        "timeStamp": "2022-09-01T12:35:34.678Z",
        "terminalId": "BS-4545F9",
        "referenceNumber": "220901015555",
        "authorizationCode": "HIU456",
        "authorizationMethodType": "00948",
        "transactionId": "05555",
        "transactionType": "PURCHASE",
        "transactionRawText": "CARD TRANSACTION\n\nCard: 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"
      },
      "customAttributes": [
        { "key": "value" }
      ]
​
Key
Type
Description
Required
type
String
Payment type  CARD | CASH | LOYALTY | VOUCHER
✅
amount
Integer
Paid amount in fractional unit 
(POINT ECR API Amount, field 14)
✅
attributes
Object
Payment terminal attributes
All these should be got from payment terminal
✅
​〰
 cardType
String
Card type description if available. 
​
​〰
 maskedPAN
String
Cards masked PAN. At least 4 last digits 
(POINT ECR API Card Number field 6)
✅
​〰
 timeStamp
String
Payment ISO 8601 datetime in UTC
(POINT ECR API Date and time of transaction field 13)
✅
​〰
terminalId
String
Terminal ID from terminal.
 (POINT ECR API Reader serial number, field 16)
✅
​〰
 referenceNumber
String
Reference number / Filing code for transaction 
(POINT ECR API Filing code, field 12)
✅
​〰
 authorizationCode
String
Payment Authorization code (6 characters, alphanumeric)
✅
​〰
 authorizationMethodType
String
Payment authorization method free text
​
​〰
 transactionId
String
Transaction id 
(POINT ECR API TransactionID, field 11)
​
​〰
transactionType
String
Type of Transaction
PURCHASE | RETURN
✅
​〰
 transactionRawText
String
Raw Transaction Receipt data from the payment terminal (POINT ECR API Payer’s receipt texts, field 19)
​
customAttributes
Array
Key value pair for custom attributes on payment
These key value pair will be shown on receipt as table under payment.
​
​〰
 key
String
Free text key name
✅
​〰
 value
String
Free text value
✅
Cash Payment
{
      "type": "CASH",
      "amount": 34920,
      "attributes": {
        "handedAmount": 40000
      }
Key
Type
Description
Required
type
String
CASH
✅
amount
Integer
Paid amount in fractional unit
✅
attributes
Object
Cash payment attributes
✅
​〰
 handedAmount
Integer
Amount that is handed in cash in fractional unit
✅
Loyalty Payment
{
      "type": "LOYALTY",
      "amount": 20720,
      "attributes": {
        "cardType": "Plussa",
        "maskedPAN": "1881"
      },
      "customAttributes": [
        { "ExtraBonus": "234 points" },
      ]
    },
Key
Type
Description
Required
type
String
LOYALTY
✅
amount
Integer
Paid amount in fractional unit
✅
attributes
Object
Loyalty card details
✅
​〰
 cardType
String
Free text card type / name
✅
​〰
 maskedPAN
String
If loyalty card has number it can be placed here
✅
Other Payment
{
      "type": "OTHERPAYMENT",
      "amount": 20720,
      "attributes": {
        "externalType": "Klarna",
      }
  },
Key
Type
Description
Required
type
String
OTHERPAYMENT
✅
amount
Integer
Paid amount in fractional unit
✅
attributes
Object
Payment details
✅
​〰
 externalType
String
Free text card type / name
​
Voucher Payment
{
      "type": "VOUCHER",
      "amount": 20720,
      "attributes": {
        "referenceNumber": "1234567890",
      }
  },
Key
Type
Description
Required
type
String
VOUCHER
✅
amount
Integer
Paid amount in fractional unit
✅
attributes
Object
Payment details
✅
​〰
 referenceNumber
String
Voucher reference number or id
​
​
Payment custom attributes
All payment objects can have custom attributes.
"customAttributes": [
   { "ExtraBonus": "234 points" },
Key
Type
Description
Required
customAttributes
Array
Key value pair list
​
​〰
 Key
String
Free text key
​
​〰
 Value
String
Free text value
​
General Receipt Data
 "customAttributes": [
    { "key": "value" },
    { "key2": "value2" },
    { "key3": "value3" }
  ],
​
  "freeText": "Custom greetings etc",
  "receiptNumber": "89942344234",
  "receiptTimeStamp": "2018-11-26T12:35:34.678Z",
  "currencyISOCode": "EUR",
  "totalVATAmount": 1884,
  "totalPriceExcVAT": 18836,
  "totalPriceIncVAT": 20720,
}
​
Key
Type
Description
Required
freeText
String
Freetext field to be displayed on receipt
​
receiptNumber
String
Merchant's internal receiptnumber
✅
receiptTimeStamp
String
ISO 8601 datetime in UTC , when purchase is made
✅
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 (AC|DC)
​
transactionBegin
Transaction Event Object
Transaction Begin event data
​
transactionEnd
Transaction Event Object
Transaction End event data
✅
Transaction Event Object
Key
Type
Description
Required
signedData
String
Signed transaction event data for verification
✅
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 (AC\|DC)
transactionBegin	Transaction Event Object	Transaction Begin event data
transactionEnd	Transaction Event Object	Transaction End event data	✅
Key	Type	Description	Required
signedData	String	Signed transaction event data for verification	✅
Last modified 6mo ago