HeroJSON Specification

Merchant object

"merchant": {
    "name": "Global Receipt Delicatesse",
    "companyID": "123456-7",
    "branch": {
      "id": "340",
      "posId": "2",
      "name": "Receipt Restaurant",
      "subName":"FastFood",
      "email": "restaurant@example.com",
      "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

✅

String

Branch location street address

✅

String

Branch location city

✅

String

Branch location zip code

✅

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

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

✅

String

VAT rate. Integer or Decimal

✅

Integer

VAT amount in fractional unit

✅

Integer

Amount without VAT in fractional unit

✅

Integer

Amount with VAT in fractional unit

✅

discounts

Array

Product level discount objects.

Integer

Amount of discount in fractional unit

✅

String

Discount percentage in decimal

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.

String

Free key name

✅

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

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

✅

String

VAT rate. Integer or Decimal

✅

Integer

VAT amount in fractional unit

✅

Integer

Amount without VAT in fractional unit

✅

Integer

Amount with VAT in fractional unit

✅

VATCode

String

VAT identifier

Payments

Card Payment

  "payments": [
    {
      "type": "CARD",
      "amount": 20720,
      "attributes": {
        "cardType": "Debit Mastercard",
        "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: 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"
      },
      "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

✅

String

Card type description if available.

String

Cards masked PAN. At least 4 last digits

(POINT ECR API Card Number field 6)

✅

String

Payment ISO 8601 datetime in UTC

(POINT ECR API Date and time of transaction field 13)

✅

String

Terminal ID from terminal.

(POINT ECR API Reader serial number, field 16)

✅

String

Reference number / Filing code for transaction

(POINT ECR API Filing code, field 12)

✅

String

Payment Authorization code (6 characters, alphanumeric)

✅

String

Payment authorization method free text

String

Transaction id

(POINT ECR API TransactionID, field 11)

String

Type of Transaction PURCHASE | RETURN

✅

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.

String

Free text key name

✅

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

✅

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

✅

String

Free text card type / name

✅

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

✅

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

✅

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

String

Free text key

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

String

Free text key

✅

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

✅

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.000Z"
    }
]
Key
Type
Description
Required

type

String

Type of attachment (BARCODE|QRCODE)

✅

kind

String

Kind represents the purpose of the attachment (TICKET|RETURN|GIFT_CARD)

✅

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 representing the last moment the attachment is valid for use

PreviousReceiptHero JSONNextFinvoice XML eReceipt

Last updated