NAV Navbar
Logo
ReceiptHero

ReceiptHero

Welcome to ReceiptHero developer pages.

What is ReceiptHero?

Introduction

File types

Receipthero supports following eReceipt File types:

ReceiptHero JSON eReceipt

{
    "sellerInformation": {
        "sellerName": "Test Company",
        "sellerEmail": "seller@testcompany.com",
        "sellerCompanyId": "123456-7",
        "selletVATNumber": "FI1234567",
        "sellerAddress": {
            "streetAddress": "Chicken Burrito Road 34",
            "zipCode": "23123",
            "city": "Tampere",
            "country": "Finland"
        }
    },
    "products": [{
        "productName": "Awesome Chicken Burrito ",
        "productId": "1231245",
        "productEANCode": "3234234",
        "productQuantity": 1,
        "productUnitPriceExVAT": "10",
        "productVATRate": "24",
        "productVATAmount": "2.4"
    }],
    "receiptDate": "2017-06-27",
    "receiptTimestamp": 1498768794,
    "receiptNumber": 23532,
    "totalPriceIncVAT": "12.4",
    "totalPriceExVAT": "10",
    "totalVATAmount": "2.4",
    "currencyISOCode": "EUR",
    "receiptFile": {
        "fileType": "pdf",
        "fileBase64": "<base64 encodede pdf file>"
    }
}

Finvoice XML eReceipt

ReceiptHero eReceipts are transferred in Finvoice eReceipt XML structure.

The Federation of Finnish Financial Services (Finance Finland, FFI) has described eReceipt based in Finvoice XML specification.

eReceipt XML implementation instructions (in Finnish)


<?xml version="1.0" encoding="ISO-8859-15"?>
<?xml-stylesheet href="Finvoice.xsl" type="text/xsl"?>
<Finvoice Version="2.01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Finvoice2.01.xsd">
  <MessageTransmissionDetails>
    <MessageSenderDetails>
      <FromIdentifier>FI12345678</FromIdentifier>
      <FromIntermediator>NONE</FromIntermediator>
    </MessageSenderDetails>
    <MessageReceiverDetails>
      <ToIdentifier>ReceiptHero</ToIdentifier>
      <ToIntermediator>NONE</ToIntermediator>
    </MessageReceiverDetails>
     <MessageDetails>
      <MessageIdentifier>ElectronicReceipt</MessageIdentifier>
      <MessageTimeStamp>151222101817</MessageTimeStamp>
    <ImplementationCode>ECR1</ImplementationCode>
    </MessageDetails>
     </MessageTransmissionDetails>
  <SellerPartyDetails>
    <SellerPartyIdentifier>1234567-8</SellerPartyIdentifier>
    <SellerOrganisationName>Kauppa Oy</SellerOrganisationName>
    <SellerOrganisationTaxCode>FI12345678</SellerOrganisationTaxCode>
    <SellerPostalAddressDetails>
      <SellerStreetName>Hämeenkatu 1</SellerStreetName>
      <SellerTownName>TAMPERE</SellerTownName>
      <SellerPostCodeIdentifier>33100</SellerPostCodeIdentifier>
    </SellerPostalAddressDetails>
  </SellerPartyDetails>
  <SellerOrganisationUnitNumber>123456789</SellerOrganisationUnitNumber>
  <BuyerPartyDetails>
    <BuyerOrganisationName>Tunnistamaton asiakas</BuyerOrganisationName>
    <BuyerOrganisationName>524342xxxxxx1401</BuyerOrganisationName>
  </BuyerPartyDetails>
   <AnyPartyDetails>
    <AnyPartyText AnyPartyCode="Site">Ketju1</AnyPartyText>
    <AnyPartyOrganisationName>Liike 1</AnyPartyOrganisationName>
    <AnyPartyCommunicationDetails>
      <AnyPartyPhoneNumberIdentifier>03-1234 123</AnyPartyPhoneNumberIdentifier>
    </AnyPartyCommunicationDetails>
    <AnyPartyPostalAddressDetails>
      <AnyPartyStreetName>Hämeenkatu 12</AnyPartyStreetName>
      <AnyPartyTownName>Tampere</AnyPartyTownName>
      <AnyPartyPostCodeIdentifier>33100</AnyPartyPostCodeIdentifier>
    </AnyPartyPostalAddressDetails>
  </AnyPartyDetails>
  <InvoiceDetails>
    <InvoiceTypeCode>INF09</InvoiceTypeCode>
    <InvoiceTypeText>Sähköinen kuitti</InvoiceTypeText>
    <OriginCode>Original</OriginCode>
    <InvoiceNumber>12</InvoiceNumber>
    <InvoiceDate Format="CCYYMMDD">20161120</InvoiceDate>
    <SellerReferenceIdentifier>12345678</SellerReferenceIdentifier>
    <InvoiceTotalVatExcludedAmount AmountCurrencyIdentifier="EUR">153,08</InvoiceTotalVatExcludedAmount>
    <InvoiceTotalVatAmount AmountCurrencyIdentifier="EUR">36,73</InvoiceTotalVatAmount>
    <InvoiceTotalVatIncludedAmount AmountCurrencyIdentifier="EUR">189,81</InvoiceTotalVatIncludedAmount>
    <VatSpecificationDetails>
      <VatBaseAmount AmountCurrencyIdentifier="EUR">153,08</VatBaseAmount>
      <VatRatePercent>24,00</VatRatePercent>
      <VatCode>S</VatCode>
      <VatRateAmount AmountCurrencyIdentifier="EUR">36,73</VatRateAmount>
    </VatSpecificationDetails>
  </InvoiceDetails>
  <PaymentStatusDetails>
    <PaymentStatusCode>PAID</PaymentStatusCode>
  </PaymentStatusDetails>
  <InvoiceRow>
    <ArticleIdentifier>H8624</ArticleIdentifier>
    <ArticleName>Hanwag WaterProofing </ArticleName>
    <InvoicedQuantity QuantityUnitCode="M2">1.0000</InvoicedQuantity>
    <UnitPriceAmount AmountCurrencyIdentifier="EUR">10,71</UnitPriceAmount>
    <RowVatRatePercent>24,00</RowVatRatePercent>
    <RowVatCode>S</RowVatCode>
    <RowVatAmount AmountCurrencyIdentifier="EUR">2,07</RowVatAmount>
    <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">8,64</RowVatExcludedAmount>
    <RowAmount AmountCurrencyIdentifier="EUR">10,71</RowAmount>
  </InvoiceRow>
  <InvoiceRow>
    <ArticleIdentifier>2001168</ArticleIdentifier>
    <ArticleName>Men's 6Inch Premium WP Boots</ArticleName>
    <EanCode>346373734733</EanCode>
    <InvoicedQuantity QuantityUnitCode="KPL">1.0000</InvoicedQuantity>
    <UnitPriceAmount AmountCurrencyIdentifier="EUR">179,10</UnitPriceAmount>
    <RowVatRatePercent>24,00</RowVatRatePercent>
    <RowVatCode>S</RowVatCode>
    <RowVatAmount AmountCurrencyIdentifier="EUR">34,66</RowVatAmount>
    <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">144,44</RowVatExcludedAmount>
    <RowAmount AmountCurrencyIdentifier="EUR">179,10</RowAmount>
  </InvoiceRow>

  <InvoiceRow>
    <SubInvoiceRow>
        <SubIdentifier>PAYMENT</SubIdentifier>
        <SubArticleIdentifier>Kortti</SubArticleIdentifier>
        <SubArticleName>MAKSUTAPA</SubArticleName>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00000">CardMaskedNumber</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>524342xxxxxx1401</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00001">ReferenceNumber</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>151222010038</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00002">TimeStamp</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>151222100715</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00003">RequestedAmount</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>189,81</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00004">AuthorizationCode</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue></SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00005">MerchantNumber</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue></SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00006">AuthorizingTermID</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue></SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00007">VerifiedByPINFlag</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue></SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00008">TenderAuthorizationMethodType</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>ChipPin</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowDefinitionDetails>
          <SubRowDefinitionHeaderText DefinitionCode="CARD00009">CreditCardCompanyCode</SubRowDefinitionHeaderText>
          <SubRowDefinitionValue>L5</SubRowDefinitionValue>
        </SubRowDefinitionDetails>
        <SubRowAmount AmountCurrencyIdentifier="EUR">189,81</SubRowAmount>
    </SubInvoiceRow>
  </InvoiceRow>
  <SpecificationDetails>
    <SpecificationFreeText>KORTTITAPAHTUMA</SpecificationFreeText>
    <SpecificationFreeText></SpecificationFreeText>
    <SpecificationFreeText>Kortti:                        MC Debit</SpecificationFreeText>
    <SpecificationFreeText>**** **** **** 1401 CP</SpecificationFreeText>
    <SpecificationFreeText>Sovellus:              A000000004101001</SpecificationFreeText>
    <SpecificationFreeText>Tap.nro/Varmennus:         00038/179143</SpecificationFreeText>
    <SpecificationFreeText>Yritys/Ala:           111111111111/5399</SpecificationFreeText>
    <SpecificationFreeText></SpecificationFreeText>
    <SpecificationFreeText>Autentisointi:         03072B69B36642F7</SpecificationFreeText>
    <SpecificationFreeText>Viite:                     151222010038</SpecificationFreeText>
    <SpecificationFreeText></SpecificationFreeText>
    <SpecificationFreeText>Debit/Veloitus               189,81 EUR</SpecificationFreeText>
    <SpecificationFreeText></SpecificationFreeText>
  </SpecificationDetails>
  <EpiDetails>
    <EpiIdentificationDetails>
      <EpiDate Format="CCYYMMDD">20161120</EpiDate>
      <EpiReference></EpiReference>
    </EpiIdentificationDetails>
    <EpiPartyDetails>
      <EpiBfiPartyDetails>
        <EpiBfiIdentifier IdentificationSchemeName="BIC">BANKFIHH</EpiBfiIdentifier>
        <EpiBfiName>NORDEA</EpiBfiName>
      </EpiBfiPartyDetails>
      <EpiBeneficiaryPartyDetails>
        <EpiAccountID IdentificationSchemeName="IBAN">FI04904840131313</EpiAccountID>
      </EpiBeneficiaryPartyDetails>
    </EpiPartyDetails>
    <EpiPaymentInstructionDetails>
      <EpiInstructedAmount AmountCurrencyIdentifier="EUR">189,81</EpiInstructedAmount>
      <EpiCharge ChargeOption="SLEV">SLEV</EpiCharge>
      <EpiDateOptionDate Format="CCYYMMDD">20161120</EpiDateOptionDate>
    </EpiPaymentInstructionDetails>
  </EpiDetails>
</Finvoice>

Errors

ReceiptHero API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable
Partner App API

Partner App API

Introduction

Receipt Hero Partner App API constist of two parts:

  • Receipts API provides access to receipt resource
  • Notification API implements ReceiptHero Notification service via webhooks

Big picture

ReceiptHero gets eReceipts from Merchants. Every time a receipt is delivered to ReceiptHero, ReceiptHero will send notification to all Partner Apps that User has activated in her ReceiptHero account. Notifications are sent throught ReceiptHero Notifications Webhooks.

When Partner App gets notification it can get actual eReceipt throught Receipts API.

User grants Partner App acces to her receipths with OAuth2 in Partner App

Players

User

User is end user that uses ReceiptHero to receive eReceipts from Merchants. User can grant access to her eReceipts for Partner App User can have multiple Partner Apps activated.

Partner App

Partner App is any software (mobileapp,SAAS,etc) that provides eReceipts for its users.

Merchant

Merchant is store that provides eReceipts for its customers trought ReceiptHero

Authentication

ReceiptHero Partner APP API uses Token based authentication over SSL.

Every reguest must contains Authorization HTTP header with following contents:

Bearer USERS_OAUTH2_TOKEN

where USERS_OAUTH2_TOKEN is OAuth2 acces token key that is provided to Partner App on behalf of User via OAuth2 flow.

POST /api/v1/receipts/ HTTP/1.1
Host: api.receipthero.io
Authorization: Bearer USERS_OAUTH2_TOKEN

Receipts API

This API provides Partner Apps access to their users receipts in ReceiptHero.

API has following functionalities:

  • Get specific receipt with id
  • Get specific users receipts

GET /receipts/

This endpoint returns users all receipts 

GET /api/v1/receipts/ HTTP/1.1
Host: api.receipthero.io
Authorization: Bearer USERS_OAUTH2_TOKEN

Response:

{
  "receipt_id": "28996538-ff8a-48eb-9171-0c34f3c805d0",
  "timestamp": "1509975882",
  "description": "Jack's Coffee",
  "total_prica": "3.40",
  "currency": "EUR",
  "receipt_url":"/api/v1/receipts/28996538-ff8a-48eb-9171-0c34f3c805d0"
}

GET /receipts/{receipt_id}/

This endpoint returns specific receipt with id

Example request:

GET /api/v1/receipts/28996538-ff8a-48eb-9171-0c34f3c805d0 HTTP/1.1
Host: api.receipthero.io
Authorization: Bearer USERS_OAUTH2_TOKEN

Response:

{
    "sellerInformation": {
        "sellerName": "Test Company",
        "sellerEmail": "seller@testcompany.com",
        "sellerCompanyId": "123456-7",
        "selletVATNumber": "FI1234567",
        "sellerAddress": {
            "streetAddress": "Chicken Burrito Road 34",
            "zipCode": "23123",
            "city": "Tampere",
            "country": "Finland"
        }
    },
    "products": [{
        "productName": "Awesome Chicken Burrito ",
        "productId": "1231245",
        "productEANCode": "3234234",
        "productQuantity": 1,
        "productUnitPriceExVAT": "10",
        "productVATRate": "24",
        "productVATAmount": "2.4"
    }],
    "receiptDate": "2017-06-27",
    "receiptTimestamp": 1498768794,
    "receiptNumber": 23532,
    "totalPriceIncVAT": "12.4",
    "totalPriceExVAT": "10",
    "totalVATAmount": "2.4",
    "currencyISOCode": "EUR",
    "receiptFile": {
        "fileType": "pdf",
        "fileBase64": "<base64 encodede pdf file>"
    }
}

Notification API

Merchant API

ReceiptHero

Welcome to ReceiptHero developer pages.

What is ReceiptHero?

Authentication

ReceiptHero Merchant API uses Token based authentication over SSL.

Every reguest must contains Authorization HTTP header with following contents:

Token RECEIPTHERO_MERCHANT_API_KEY

where RECEIPTHERO_MERCHANT_API_KEY is api key that is provided to Merchant

POST /api/v1/receipts/ HTTP/1.1
Host: receipthero.io
Authorization: Token RECEIPTHERO_MERCHANT_API_KEY