HeroJSON Specification

Merchant object

"merchant": {
    "name": "Global Receipt Delicatesse",
    "companyID": "123456-7",
    "branch": {
      "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

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

KeyTypeDescriptionRequired

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

KeyTypeDescriptionRequired

signedData

String

Signed transaction event data for verification

Last updated