Search
K

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