anybill
Developer Documentation

Appearance

Bill Data Model ​

The receipt payload sent to POST /v3/bill is described here: first the structure of the BillDTO, then the reference of the values its fields accept.

BillDTO object ​

Our BillDTO object bundles all receipt information, which are based on the DFKA standard with anybill specific extensions. As root object of the receipt it links to five different categories of data:

  • Cash register* Information about the cash register.
  • Head* Head data of the receipt.
  • Data* Receipt data.
  • Security* Data to secure the receipt via TSE.
  • Misc Optional additional data.

To guarantee that only valid information is added to the anybill system, a variety of validation rules is executed. If the validation of the receipt object fails a response with a HTTP status code of 400 is returned with a description of validation errors in the body of the request.
Most of the rules are set in the open api specification, but some rules are far too complex in order to be able to be represented in the open api specification.

Id ​

This is null by default to let anybill's backend create a unique UUID for each receipt.

The Receipt Id can be set by the POS under two situations:

  1. Set an Id that has already been created in advance via the GET /v3/bill/url endpoint (recommended from a UX perspective)
  2. You have the Self-generated Receipt ID feature enabled.

Cash Register ​

Contains data about the cash register. Currently only the serial number of the cash register is needed.

Contains common data of the head of a receipt. E.g. invoice number, date, seller or buyer information.
Important rules:

  • If deliveryPeriodStart is set deliveryPeriodEnd must be set too or vice versa.
  • date must be after 1900-01-01
  • The seller object overrides the internal information set in the anybill system. E.g. if some information about the store has temporarily changed that is not yet updated in the anybill system this can be used to override the defaults.

Data ​

Contains the most important information for the buyer. The items he has bought and the value of the shopping cart. Important rules:

  • currency must be a valid three digit ISO 4217 code.
  • Each vatAmount must be unique by the percentage.

Important rules paymentTypes:

  • If foreignAmount is set foreignCurrency must be set and vice versa.
  • foreignCurrency must be a valid three digit ISO 4217 code.
  • The anybill extension must not be null.
  • Only the matching paymentDetails for the type set in the anybill extension will be read.

Important rules lines:

  • The anybill extension must not be null.
  • DefaultLine:
    • Each vatAmount must be unique by the percentage.
    • Each vatAmount set for a discount in the anybill extensions must have a corresponding vatAmount set in the default line.
    • A maximum of 5 reminders can be set per warranty in the item
    • warrantyEnd must be after warrantyStart.
    • warrantyEnd and warrantyStart must be after 1900-01-01.

Important rules for data extensions:

  • If barcode is set barcodeType must be set and vice versa.
  • Each vatAmount must be unique by the percentage.
  • Each discount must have a unique id

Security ​

The security object contains information about the technical security equipment required in the different countries. With the help of the Type attribute, the appropriate TSE can be transmitted depending on the country.

Globale important rules:

  • tse must be set unless tseFailure is set to true in the security extensions.
  • tse must be set unless tseRequiredis set to false in the security extensions.

Important rules TSE (Germany):

  • timestampStart, timestampEnd and firstOrder must be after 1900-01-01.
TSE (Germany)
json
{
   "serialNumber": "623323B6C170DF2200...8F3A78E5BA7C4BA60B",
   "signatureAlgorithm": "ecdsa-plain-SHA384",
   "logTimeFormat": "unixTime",
   "certificate": "LS0tLS...S0tCg ==",
   "timestampStart": "2021-11-29T15:00:57.22976+01:00",
   "timestampEnd": "2021-11-29T15:00:57.22976+01:00",
   "firstOrder": "2021-11-29T15:00:57.22976+01:00",
   "transactionNumber": 50,
   "signatureNumber": 121,
   "processData": "Kassenbeleg-V1",
   "processType": "Beleg^42.31_16.26_0.00_0.00_0.00^58.57:Bar:Visa",
   "signature": "AjEGS...dhRitb",
   "extension:anybill": {
      "posInspectionQrData": "_R1-AT1_4690F01D01_68_2021-10-04T13:54:19_4,00_0,00_0,00_0,00_0,00_jVWJIf9wOCDo544VtmI7dQ==_15BE7FD2_eUwHgkS8AGE=_GkWvZVamt1RKsUBSbGACKgcfhX7iNiRq4iQgZ8E4CUPHStNAnC6k7IPA5cG4OFlyAh0GsbSRanKBUfy0PsyVqg==",
      "additionalLegalText": "Additional legal text",
      "additionalTseData": {
         "firstName": {
               "displayName": "display value",
               "value": "Value"
         },
         "secondName": {
               "displayName": "display value",
               "value": "Value"
         }
      }
   }
}
RKSV (Austria)
json
{
   "type": "rksv",
   "signature": "AjEGS...dhRitb",
   "serialNumber": "Tpzx/mesZGSu/XO6ZaKZO/bk87HKejMaU2VCDoAgmp4=",
   "transactionNumber": 1459,
   "signatureNumber": 3833,
   "posInspectionQrData": "_R1-AT1_4690F01D01_68_2021-10-04T13:54:19_4,00_0,00_0,00_0,00_0,00_jVWJIf9wOCDo544VtmI7dQ==_15BE7FD2_eUwHgkS8AGE=_GkWvZVamt1RKsUBSbGACKgcfhX7iNiRq4iQgZ8E4CUPHStNAnC6k7IPA5cG4OFlyAh0GsbSRanKBUfy0PsyVqg==",
   "additionalLegalText": "Additional legal text",
   "additionalData": {
      "firstName": {
         "displayName": "display value",
         "value": "Value"
      },
      "secondName": {
         "displayName": "display value",
         "value": "Value"
      }
   }
}

Misc ​

Optional additional data.

Important rules misc extensions:

  • If returnBarcodeType is set returnBarcode must be set and vice versa.

Description of possible values ​

For better understanding some values are described below.

Values for enumerations like QuantityMeasure, PriceModifier or PaymentType can be the integer value or the string equivalent, whereas integers are preferred. The descriptions always show the integer value and the string equivalent/meaning of the value.

Lines ​

There are three types of lines. The type of the line is determined with the type-discriminator in the extension of the line. Possible discriminators:

  • default or no value (null) for default lines
  • text for text only lines
  • discount for discount line

Default line ​

The default line represents an item or service that was sold. You can add useful information in the additionalText or even add warranty information and let the user be notified before the warranty ends.

Text line ​

The text line can be used to add text in between other lines. This can be as easy as a product group separation or further useful information.

Discount line ​

The discount line displays a discount that is applied to the whole receipt. Therefore the values must have a negative balance.

Possible QuantityMeasure values ​

The quantity measure describes the type of quantity of the line item. For bananas, whose price is often measured by weight, you would choose 1 (kilogram) and for t-shirts that are sold per unit you would choose 0 (count).

NameValue
Count0
Kilogram1
Lbs2
Meters3
Inches4
Liter5
CubicMeters6
SquareMeters7
KilowattHour8

Example:

qantityMeasure: "Count"

PaymentTypes ​

The payment type describes the type of payment used in the payment type information object. The type used should be specified further with the name-property. E.g. for a payment with visa the payment type should be 3 (credit card) and name should be "Visa". The name should be human readable and will be displayed for the user.

Possible PaymentType values ​

NameValue
Miscellaneous0
Cash1
DirectDebit2
CreditCard (Deprecated)3
OnlinePayment4
GiftCard5
BankTransfer6
Check7
LoyaltyCard8
Girocard (Deprecated)9
Elv10
Maestro (Deprecated)11
VisaElectron (Deprecated)12
CardPayment12

Example:

type: "Cash"

For every payment type, except for miscellaneous, additional details can be provided in the paymentDetails-property. E.g. for the cash payment type the CashPaymentDetails-object can be optionally used. Any details given, that do not match the correct payment type will be ignored.

Check payment details
json
{
  "name": "Check",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "Check",
     "paymentDetails": {
        "drawee": "The person in whose favour the cheque",
        "payee": "Person who receives payment",
        "dateOfIssue": "Date and Time in iso 8601",
        "drawer": "The one who has written out the cheque",
        "sortCode": "",
        "accountNumber": ""
     }
  }
}
BankTransfer payment details
json
{
  "name": "Bank XY Transfer",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "BankTransfer",
     "paymentDetails": {
        "purposeOfUsage": "Some usage description",
        "iban": "DE 1234",
        "bic": "1342",
        "accountHolderName": "MS Pos GmbH",
        "accountNumber": "1234",
        "bankName": "Bank Name",
        "bankAddress": "Some Address",
        "sortCode": "1234",
        "routingNumber": "abcd",
        "ifscCode": "1234",
        "routingCode": "abcd",
        "terminalId": "1234",
        "terminalDateTime": null,
        "terminalTime": "12:37:04",
        "terminalDate": "20.07.2020",
        "traceNumber": "4321",
        "cardPan": "The primary account number",
        "cardSequenceNumber": 1234,
        "cardExpiryDate": "12/27"
    }
  }
}
Cash payment details
json
{
  "name": "Cash",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "Cash",
     "paymentDetails": {
        "amountGiven": 120.00,
        "amountReturned": 17.10
    }
  }
}
CardPayment payment details (CardPayment, Girocard, Maestro, VisaElectron, CreditCard)
json
{
  "name": "Visa",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "CardPayment",
     "paymentDetails": {
        "cardNumber": "123456",
        "bankName": "Some Bank",
        "terminalId": "1234",
        "terminalDateTime": null,
        "terminalTime": "12:37:04",
        "terminalDate": "20.07.2020",
        "traceNumber": "4321",
        "cardPan": "The primary account number",
        "cardSequenceNumber": 1234,
        "cardExpiryDate": "12/27",
    }
  }
}
DirectDebit payment details (DirectDebit, Elv)
json
{
  "name": "Elv",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "Elv",
     "paymentDetails": {
        "sepaCreditorId": "",
        "sepaMandateReference": "",
        "cardNumber": "",
        "bankName": "",
        "terminalId": "1234",
        "terminalDateTime": null,
        "terminalTime": "12:37:04",
        "terminalDate": "20.07.2020",
        "traceNumber": "4321",
        "cardPan": "The primary account number",
        "cardSequenceNumber": 1234,
        "cardExpiryDate": "12/27",
    }
  }
}
GiftCard payment details
json
{
  "name": "Geschenkkarte",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "GiftCard",
     "paymentDetails": {
        "initialBalance": 200.00,
        "remainingBalance": 87.10,
        "dateOfExpiry": "Date and Time in iso 8601"
    }
  }
}
LoyaltyCard payment details
json
{
  "name": "Shop XY Card",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "LoyaltyCard",
     "paymentDetails": {
        "name": "MS-Pos Loyalty Card",
        "accountNumber": "21341234",
        "pointsUsed": 11290.0,
        "pointsLeft": 1293403.0,
        "pointsGained": 32.0
    }
  }
}
OnlinePayment payment details
json
{
  "name": "Paypal",
  "amount": 112.90,
  "foreignAmount": null,
  "foreignCurrency": null,
  "extension:anybill": {
     "type": "OnlinePayment",
     "paymentDetails": {
        "senderAccountName": "CSymeoudakis@mspos.net",
        "recipientAccountName": "yourmail@anybill.de",
        "transactionId": "1293403"
    }
  }
}

Terminal customer receipt ​

The Terminal text attribute is available on bill.misc.additonalReceipts and have to be filled with the payment information text which is provided by the terminal. This is an example of the terminal text:

Terminal customer receipt example

json
"additionalReceipts": [
    {
        "contentType": "text/plain",
        "content": "Terminal-ID :   61400710
        TA-Nr 000584    BNr 0062
        
             Kartenzahlung
            Visa kontaktlos
                  Visa
        
        EUR 10,00
         
        PAN     ############2515
        Karte 0
        EMV-AID   A0000000031010
        VU-Nr             123456
        Genehmigungs-Nr   123456
        Datum 19.02.20 15:38 Uhr
        EMV-Daten
        0000000000/0000///"
    }
],

Terminal merchant receipt ​

The Terminal text attribute is available on bill.misc.additonalReceipts and have to be filled with the payment information text which is provided by the terminal. This is an example of the terminal text:

Terminal merchant receipt example

json
"additionalReceipts": [
   ...,
    {
        "type": "VendorReceipt",
        "contentType": "text/plain",
        "content": "ICAgICAgLUgtw4QtTi1ELUwtRS1SLUItRS1MLUUtRy1cblxuICAgICAgICAgICAgSm95YHMgU2hvcFxuICAgICAgICAgIEFtIFN0ZWluZmVscyAxXG4gICAgICAgICAgIDY1NjE4IFNlbHRlcnNcblxuVGVybWluYWwtSUQgOiAgICAgICAgICAgICAgNTQwNjE1ODNcblRBLU5yIDA3MDk0MiAgICAgICAgICAgICAgIEJOciA0MzAzXG5cbiAgICAgICAgICAgS2FydGVuemFobHVuZ1xuICAgICAgICAgICAga29udGFrdGxvc1xuICAgICAgICAgICAgTUFTVEVSQ0FSRFxuXG4gICAgRVVSIDExLDU0XG5cblBBTiAgICAgICAgICAgICAgICAjIyMjIyMjIyMjIyMzMjg3XG5LYXJ0ZSAwXG5FTVYtQUlEICAgICAgICAgICAgICBBMDAwMDAwMDA0MTAxMFxuVlUtTnIgICAgICAgICAgICAgICAgICAgICA4MDM2MjQ0NTBcbkFJRFBhcmEgICAgICAgICAgICAgICAgICAwMTAwMDAwMDAyXG5HZW5laG1pZ3VuZ3MtTnIgICAgICAgICAgICAgIDA3MDMxMVxuRGF0dW0gMTMuMDQuMjIgICAgICAgICAgICAyMDoxMyBVaHJcbkVNVi1EYXRlblxuMDAwMDAwODAwMS9BODAwLzAwMDAwMDAwMDAvRjQ1MDg0ODBcbjBDL0Y0NTA4NDgwMEMvM0YwMDAyLy8vMjE3OEEwOTQvODBcblxuWmFobHVuZyBlcmZvbGd0XG5cbj09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG5BUy1Qcm9jLUNvZGUgPSAwMCAwNzUgMDBcbkNhcHQuLVJlZi49IDAyNjBcbkFJRDU5OiAxNDI5OTFcbj09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XG5cbiAgICAgIEJJVFRFIEJFTEVHIEFVRkJFV0FIUkVOXG5cbg=="
    }
],

Possible CurrencyCode values ​

To specify the currency, the 3-digit ISO 4217 standard is used. Any currency codes that do not match the standard will result in a invalid response.

Example 1:

currency: "EUR"

Example 2:

foreignCurrency: "USD"