HeroJSON Specification
"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 | ✅ |
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 | ✅ |
〰 | String | Branch location street address | ✅ |
〰 | String | Branch location city | ✅ |
〰 | String | Branch location zip code | ✅ |
〰 | String | Branch location country | ✅ |
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 | ✅ |
〰 | 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 | ✅ |
"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": [
{
"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 | ✅ |
〰 | 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 | ✅ |
{
"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 | ✅ |
{
"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 | ✅ |
{
"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 | |
{
"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 | |
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 | |
"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": [
{
"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\"}"
}
}
]
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