NAV Navbar
Logo
ReceiptHero

Introduction

ReceiptHero Partner App API provides endpoints for integrated applications.

API enables partner apps to get information on users and receipts.

Users

User is induvidual person who has signed up to Receipthero and uses ReceiptHero to receive eReceipts from merchants. Partner apps can only access data of those users that have granted access to app trought oauth process.

Receipts

Receipts are eReceipts in Finvoice eReceitp format. Partner application can access only receipts that are owned by users that have granted access to partner application

Changelog

Date Change Explanationn
1.11.2019 Intial Beginning of docsdocs đŸŽ”
16.5.2019 Merchant API & HeroJSON Update Added Merchant API Details (one endpoint) and updated HeroJSON to support multiple VATs per product, discounts, freeText fields
2.10.2019 HeroJSON Update - Added payments array. One receipt can now have multiple payment methods
- Added customAttributes to payment
- Added subName for Merchant branch
- Added unitPriceiNcVATDecimal to product to support more than 2 decimals
Partner App API

Partner App API

Authentication

ReceiptHero API has two access levels:

  1. Partner Application general access
  2. User specific resource access

Partner App general access

To acces any endpoint partner app must include ReceiptHero API key in every request in custom HTTP header:

RECEIPTHERO_APIKEY <partner applications api key>

User specific resource access

To access any resource that is owned by ReceiptHero user partner application must add Oauth access token to Http Authorization header:

HTTP_AUTHORIZATION Bearer <oatuh bearer token>

! This acces token is user specific so every user has different access token

List Users

Get list of all users that have granted access for your application

Request

GET /api/v1/users/ HTTP/1.1
Host: api.dev.receipthero.io
RECEIPTHERO_APIKEY: <PARTNER_APP_API_KEY>

Response

HTTP 200 OK
content-type: application/json

{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 17,
    },
    {
      "id": 25,
    },]
}

List Users receipts

Get list of users receipts

Get list of users receipts. list provides meta data on receipt and links to get full receipt data in following formats:

  • Finvoice XML
  • Finvoice PDF
  • ReceiptHero JSON
  • ReceiptHero PDF

Request

GET /api/v1/users/<user_id>/receipts/ HTTP/1.1
Host: api.dev.receipthero.io
RECEIPTHERO_APIKEY: <PARTNER_APP_API_KEY>
Authorization: Bearer <USERS_OAUTH_TOKEN>
Parameter Value Explanationn
user_id number Users id provided in Users list endpoint

Response

HTTP 200 OK
content-type: application/json

{
  "count": 148,
  "next": "https://api.dev.receipthero.io/api/v1/users/96/receipts/?page=2",
  "previous": null,
  "results": [
    {
      "uuid": "afb2d159-81ef-4072-a9b8-da5f7fe384f6",
      "date": "2018-03-20T06:46:33.608000Z",
      "price": 73460,
      "finvoice_xml_url": "https://api.dev.receipthero.io/api/v1/receipts/afb2d159-81ef-4072-a9b8-da5f7fe384f6/finvoice_xml/",
      "finvoice_pdf_url": "https://api.dev.receipthero.io/api/v1/receipts/afb2d159-81ef-4072-a9b8-da5f7fe384f6/finvoice_pdf/",
      "hero_json_url": "https://api.dev.receipthero.io/api/v1/receipts/afb2d159-81ef-4072-a9b8-da5f7fe384f6/",
      "hero_pdf_url": "https://api.dev.receipthero.io/api/v1/receipts/afb2d159-81ef-4072-a9b8-da5f7fe384f6/hero_pdf/"
    },]
  }

GET Receipt

Get full receipt by receipt id. Data formats are:

  • Finvoice XML
  • Finvoice PDF
  • ReceiptHero JSON
  • ReceiptHero PDF

Request


GET /api/v1/receipts/<receipt_uuid>/<data_format>/
Host: api.dev.receipthero.io
RECEIPTHERO_APIKEY: <PARTNER_APP_API_KEY>
Authorization: Bearer <USERS_OAUTH_TOKEN>
Parameter Value Explanationn
receipt_uuid uuid receipt UUID provided in receipts list endpoint
data_format finvoice_xml Receipt is returned in finvoice xml format
finvoice_pdf Receipt is returned in rendered finvoice pdf format
hero_json Receipt is returned in ReceiptHero JSON
hero_pdf Receipt is returned in rendered JSON pdf format

Response

Response depends on requested data format

Notification webhook

ReceiptHero delivers webhook notification on new receipt arrival with receipt details.

Get Webhook url

Request

GET /api/v1/webhooks/ HTTP/1.1
RECEIPTHERO-APIKEY: <RECEIPTHERO_API_KEY>
Host: api.dev.receipthero.io

Response

{"webhook_url":"https://www.webhookexample.com/"}

Set Webhook url

Request

POST /api/v1/webhooks/ HTTP/1.1
RECEIPTHERO-APIKEY: <RECEIPTHERO_API_KEY>
Host: api.dev.receipthero.io

{"webhook_url":"https://www.new_url_to_set.com/"}

Response

{"webhook_url":"https://www.new_url_to_set.com/"}

Webhook payload

Webhook will return data that can be used to get receipt

{
  "receipthero_id":"124124124",
  "notification_type":"receipt_notification",
  "receipt_id":"93d22d66-f4bd-11e8-8eb2-f2801f1b9fd1"
}
Parameter Value Explanationn
receipthero_id number User id NOTE: this is same that ID in users list!
notification_type receipt_notification Notification type. Receipt notification for now
receipt_id uuid Receipts uuid

Trigger webhook on receipt

Trigger webhook with reeipt id. This is for testing purposes

POST /api/v1/webhooks/test/{receipt_uuid} HTTP/1.1
RECEIPTHERO-APIKEY: <RECEIPTHERO_API_KEY>
Host: api.dev.receipthero.io

This triggers new webhook call for give receipt_uuid.

Pagination

Endpoints that return lists of objects are paginated. Response cointains all necessry information for using paginated data efficently:


GET /api/v1/users/<user_id>/receipts/?page=4

page_number query parameter can be used to get specifc page on dataset

Paginated response

every paginated response containns following info:

Parameter Value Explanationn
count number Count of objects
next url / null Url to get next page of objects
previous url / null Url to get previous page

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
Merchant API

Merchant API

This api provides endpoints for Merchants to deliver receipts to ReceiptHero

Authentication

Merchant API is authenticated with RECEIPTHERO_API_KEY

HTTP_AUTHORIZATION Token <RECEIPTHERO_API_KEY>

POST Receipt

This endpoint creates new receipt to ReceiptHero. ReceiptHero uses receiptdata to match receipt to correct ReceiptHero user

Request

POST /api/v1/receipts/ HTTP/1.1
Host: api.dev.receipthero.io
Authorization: Token <RECEIPTHERO_API_KEY>

ReceiptHero JSON as body

Response

HTTP 200 OK
content-type: application/json

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
File Types

File types

Receipthero supports following eReceipt File types:

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>

ReceiptHero JSON

{
  "merchant": {
    "name": "Global Receipt Delicatesse",
    "companyID": "123456-7",
    "branch": {
      "name": "Receipt Restaurant",
      "subName":"FastFood",
      "email": "restaurant@example.com",
      "phone": "040-5086462",
      "address": {
        "streetAddress": "ItsenÀisyydenkatu 17 a 15",
        "city": "Tampere",
        "zipCode": "33500",
        "country": "Finland"
      },

    }
  },
  "products": [
    {
      "name": "Ground Control",
      "EANCode": "42222130165",
      "quantity": "4",
      "productId": "1234",
      "quantityCode": "PCS",
      "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": ""
        }
      ],
      "freeText": "Product instructions etc",
      "customAttributes": [
        { "Warranty": "2 years" },
        { "Valid until": "2020-11-26" },
      ]
    }
  ],
  "freeText": "Custom greetings etc",
  "vats": [
    {
      "VATRate": "24",
      "totalVATAmount": 1884,
      "totalAmountExcVAT": 18836,
      "totalAmountIncVAT": 20720
    }
  ],
  "payments": [
    {
      "type": "CARD,CASH,VOUCHER,LOYALTY",
      "amount": 20720,
      "attributes": {
        "cardType": "PaymentCard",
        "maskedPAN": "401288******1881",
        "timeStamp": "2018-11-26T12:35:34.678Z",
        "terminalId": "BS-4545F9",
        "unixTimeStamp": 1543235735,
        "referenceNumber": "12315352349",
        "authorizationCode": "HIU456HDDF67FH",
        "authorizationMethodType": "00948",
        "transactionId": "123e4567-e89b-12d3-a456-426655440000"
      },
      "customAttributes": [
        { "key": "value" },
        { "key2": "value2" },
        { "key3": "value3" }
      ]
    },
    {
      "type": "LOYALTY",
      "amount": 20720,
      "attributes": {
        "cardType": "Plussa",
        "maskedPAN": "1881"
      },
      "customAttributes": [
        { "ExtraBonus": "234 points" },
        { "key2": "value2" },
        { "key3": "value3" }
      ]
    },
    {
      "type": "CASH",
      "amount": 34920,
      "attributes": {
        "handedAmount": 40000
      }
    }
  ],

  "customAttributes": [
    { "key": "value" },
    { "key2": "value2" },
    { "key3": "value3" }
  ],

  "receiptNumber": "89942344234",
  "totalVATAmount": 1884,
  "currencyISOCode": "EUR",
  "receiptTimeStamp": "2018-11-26T12:35:34.678Z",
  "totalPriceExcVAT": 18836,
  "totalPriceIncVAT": 20720,
  "receiptUnixTimeStamp": 1528290969
}