Notifications

An overview of the notification types supported by the accounting module.

Accounting as a Service supports the concept of notifications, allowing the merchant to be informed upon certain events happening inside the system. The concept is based around the idea of having different notification types, for which the merchant can provide a URL to be called back whenever an event of such type occurs.

This page is supposed to provide an overview of the notification types of the payment module. In case you need more general information about notifications in Accounting as a Service, please refer to the related section of the common API elements.

As for the accounting module, the notifications are essential to be fully functional given that the accounting module handles all incoming requests in an asynchronous fashion. That means, when using the REST API of the accounting module to send requests, the synchronous response that will be provided to you will only contain the internalRequestId which will help you to map upcoming notifications back to your request.

Supported notification types

When working with notifications of the accounting module, the following notification types are available.

EDI Error sent

Due to the nature of handling all incoming requests following an asynchronous processing approach, all the endpoints of the REST API for the accounting module will only provide you with a internalRequestId as part of the synchronous HTTP response. However, once the system starts processing your request, it will have to pass the validation step in first place. Upon completion of the validation, you will be provided with a notification of type accounting/EdiErrorSent containing the results of the validation process.

To arrive at a notification of type accounting/EdiErrorSent to be triggered, you need to send a request to any of the endpoints from the accounting module as outlined in the API Explorer.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/EdiErrorSent as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "details": {
      "errorDetails": [
        {
          "errorDescription": "Format of decimal field not correct. Please correct format (XX.XX)",
          "fieldName": "TaxRate",
          "providedValue": "2,00"
        }
      ],
      "orderReference": "TFI2021072801_03"
    },
    "requestType": "ORD",
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/EdiErrorSent"
}

Balance updated

To ensure that you can keep track of your customer accounts, the accounting module provides you with the notification type accounting/balanceUpdated which is triggered whenever there is a change in one of your customer accounts (e.g. payment received, new open position booked, chargeback, etc.), This way you can keep related accounts synchronized on your end and act appropriate on related changes.

To arrive at a notification of type accounting/balanceUpdated to be triggered, the following sample process steps illustrate a potential scenario:

  1. Merchant provides a new invoice, return, goodwill or the related PSP/Bank confirms payment/payout or any other booking changes the debtor account balance.
  2. Accounting as a Service executes the appropriate booking.
  3. Accounting as a Service generates and triggers notification of type accounting/balanceUpdated.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/balanceUpdated as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "balance": 1123.1,
    "businessCode": "1000",
    "companyCode": "1000",
    "currency": "EUR",
    "customerNumber": "TFI2021072801",
    "debitCredit": "DEBIT",
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/balanceUpdated"
}

Chargeback received

In case there is a chargeback provided by a PSP or Bank, the accounting module triggers a notification of type accounting/chargebackReceived to make sure that you are aware of such events. This type of event can only occur in case of using wallet payments (e.g. PayPal), card payments (e.g. Visa), or SEPA Direct Debit as underlying payment method.

The information might be required if you provide a digital service, as you might want to cancel the provision of the service until the payment is done.

To arrive at a notification of type accounting/balanceUpdated to be triggered, the following sample process steps illustrate a potential scenario:

  1. Bank or PSP provides settlement file / bank account statement.
  2. Accounting as a Service processes settlement / bank account statement information.
  3. Accounting as a Service books chargeback / reverse debit.
  4. Accounting as a Service generates and triggers notification of type accounting/chargebackReceived.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/chargebackReceived as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "amount": 303.65,
    "businessCode": "1000",
    "companyCode": "100",
    "currency": "EUR",
    "customerNumber": "TFI2021072801",
    "invoiceReference": "IDE12345678901",
    "orderReference": "TFI2021072801_03",
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2",
    "type": "CCB"
  },
  "type": "accounting/chargebackReceived"
}

Invoice created

To make sure that you are informed whenever a new invoice is created, the accounting module provides you with the notification type accounting/invoiceCreated. The notification is triggered whenever a new invoice has been successfully generated and provides you with detailed information about the data that has been used in the scope of the invoice generation.

To arrive at a notification of type accounting/invoiceCreated to be triggered, the following sample process steps illustrate a potential scenario:

  1. Merchant requests creation of an invoice for a previously created webshop order (for more information, check out Create invoice for webshop order).
  2. Accounting as a Service validates the request and creates the new invoice document.
  3. Accounting as a Service generates and triggers notification of type accounting/invoiceCreated.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/invoiceCreated as value in the list of notificationTypes.

We provide you with the documents via URL for online retrieval. You are free to download and embed the retrievable documents according to your internal process for distribution to your customers. As the data controller, you are free to choose the specific technical and organizational means. Please note that the URL per se is not protected information once it has been made known to your customers.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "billToAddress": {
      "careOf": "Jane c/o John",
      "countryCode": "DE",
      "postalCode": "48213",
      "postalPlace": "Muenster",
      "street": "Beispielstr.",
      "streetNumber": "13A",
      "firstName": "Max",
      "language": "de",
      "lastName": "Mustermann",
      "salutation": "MRS",
      "title": "DR",
      "birthDate": "1983-09-15",
      "customerGroup": "Gold Clients",
      "email": "max.mustermann@outlook.com",
      "nationality": "German",
      "phone": "+491345789555",
      "taxIdentificationNumber": "DE999999999"
    },
    "businessCode": "1000",
    "businessCountryCode": "DE",
    "creationDate": "2018-11-05T16:15:03.0000000+00:00",
    "currency": "EUR",
    "customerNumber": "TFI2021072801",
    "dueDate": "2018-11-05",
    "goodwillReference": "GDE12345678901",
    "invoiceDate": "2018-11-24",
    "invoiceDocumentUrl": "https://files.aqount.com/invoice/27/1/13/ec058f8a-35c6-411f-a0b6-cc086b64ddbd",
    "invoiceReference": "IDE12345678901",
    "items": [
      {
        "description": "Lizenz zum Buchen",
        "grossUnitPrice": 119.12,
        "quantity": 2.5,
        "vatAmount": 19.02,
        "vatPercent": 19.0,
        "orderItemReference": 3,
        "positionType": "SHIPPING_COSTS_EXPRESS",
        "productId": "BEF12346512A/1",
        "vatType": "NORMAL"
      }
    ],
    "orderReference": "TFI2021072801_03",
    "totals": {
      "exchangeRate": 1,
      "grossUnitPrice": 119.12,
      "grossUnitPriceEUR": 119.12,
      "netUnitPrice": 100.1,
      "netUnitPriceEUR": 100.1,
      "vatAmount": 19.02,
      "vatAmountEUR": 19.02
    },
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/invoiceCreated"
}

Document created

After a document is created and processed by the accounting module, e.g. an invoice, due date reminder, payment reminder, or booking confirmation, the document is saved in the archiving system so that it can be downloaded at any time. To get a notification whenever a new document has been created, the accounting module provides you with the notification type accounting/documentCreated. The notification will contain the URL to be used for the download.

The following document-types are created and handed over:

  1. Invoices (documentType=INVOICE)
  2. Dunning notifications (documentType=DUNNING)
  3. booking confirmations (documentType=BOOKING)
  4. settlement-files (e.g. for marketplaces) (documentType=SETTLEMENT)

To arrive at a notification of type accounting/documentCreated to be triggered, the following sample process steps illustrate a potential scenario:

  1. Accounting as a Service generates and sends a document to a customer.
  2. Accounting as a Service uploads the document to the archiving system and receives a unique document ID (GUID) in return.
  3. Accounting as a Service generates and triggers notification of type accounting/documentCreated.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/documentCreated as value in the list of notificationTypes.

We provide you with the documents via URL for online retrieval. You are free to download and embed the retrievable documents according to your internal process for distribution to your customers. As the data controller, you are free to choose the specific technical and organizational means. Please note that the URL per se is not protected information once it has been made known to your customers.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "businessCode": "1000",
    "documents": [
      {
        "documentInformation": [
          {
            "customerNumber": "TFI2021072801",
            "documentCreationDate": "2020-07-23T00:00:00.0000000",
            "dunningLevel": "01",
            "invoiceReference": "IDE12345678901",
            "orderReference": "TFI2021072801_03"
          }
        ],
        "documentType": "DUNNING",
        "urlKey": "http://192.168.1.1/050/3215sadf9"
      }
    ],
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/documentCreated"
}

Reminder sent

If a customer has not paid his debts and the debts are overdue, the payment reminder and dunning procedure is automatically triggered (if activated during the technical application). To make sure that you are made aware of such events, you can use the notification type accounting/reminderSent. The type of notification will also inform you in case that the case has been handed over to a collecting agency or in case the accounting module has received information about a payment to the collecting agency. This information may be especially important for you if you have set the related service for the customer on hold.

To arrive at a notification of type accounting/reminderSent to be triggered, the following sample process steps illustrate a potential scenario:

  1. Accounting as a Service increases reminder level.
  2. Accounting as a Service generates and sends a reminder communication to the customer or transfers funds to a collection agency.
  3. Accounting as a Service generates and triggers notification of type accounting/reminderSent.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/reminderSent as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "businessCode": "1000",
    "companyCode": "100",
    "customerNumber": "TFI2021072801",
    "invoiceReference": "IDE12345678901",
    "orderReference": "TFI2021072801_03",
    "reminderLevel": 1,
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/reminderSent"
}

Refund completed

If you want to be informed whenever a refund based on a return, goodwill or cancellation has been completed, you can make use of the notification type accounting/refundCompleted. A refund is considered complete once the outgoing payment has been posted and settled with the return/goodwill/cancellation. If a return/goodwill/cancellation is offset against an open invoice, this does not lead to any notification as no refund is triggered in this case.

Please be aware that e.g. bank refunds based on overpayments or double payments initiated by customers are not considered.

To arrive at a notification of type accounting/refundCompleted to be triggered, the following sample process steps illustrate a potential scenario:

  1. Customer returns a webshop order.
  2. Merchant passes request for order return to Accounting as a Service.
  3. Accounting as a Service takes over the booking of the revenue, taxes and discounts.
  4. Accounting as a Service takes over the refund towards the customer.
  5. Accounting as a Service takes over the booking of the outgoing payment and the clearing of the open items.
  6. Accounting as a Service generates and triggers notification of type accounting/refundCompleted.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type accounting/refundCompleted as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "businessCode": "1000",
    "currency": "EUR",
    "customerNumber": "TFI2021072801",
    "invoiceReference": "IDE12345678901",
    "orderReference": "TFI2021072801_03",
    "refundedToOriginalPaymentInstrument": -12.99,
    "returnReference": "RDE12345678901",
    "transactionId": "Refund-1000-005056A304E11EEBBC825A7482D0D6F2"
  },
  "type": "accounting/refundCompleted"
}

Payment received

To provide details about paid amounts for single orders, the accounting module provides you with the notification type accounting/paymentReceived. It is triggered daily and provides the paid amount booked and matched for a single order. This way you can see, which order has been paid successfully. Furthermore it provides details about open amounts. A single entry is posted for every order and invoice.

The notification accounting/paymentReceived is triggered as following:

  1. Merchant provides a new invoice and the order amount is captured or the customer pays (i.e. to merchant bank account)
  2. Accounting as a Service receives settlement file or bank account statement and books incoming payment
  3. Accounting as a Service matches payment to open amount in end-customer account and order/invoice
  4. Accounting as a Service generates and triggers notifications of type accounting/paymentReceivedonce a day.

If an open amount (due to a goodwill or return) is cleared with a new dept (e.g. new invoice), this is not considered as a payment and will therefore not be sent as a notification.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacksrequest using the type accounting/paymentReceived as value in the list of notificationTypes.

Sample notification

{
   "id":"PaymentInformation-20190307-150753-0000001",
   "type":"accounting/paymentReceived",
   "parameters":{
      "businessCode":"1000",
      "companyCode":"1001",
      "currency":"EUR",
      "customerNumber":"C154432660897",
      "fiscalYear":2023,
      "invoiceReference":"IDE12345678901",
      "orderAmount":452.00,
      "orderReference":"O154432660897",
      "paidAmount":452.00,
      "paymentDocument":"100000000183",
      "remainingAmount":0.00,
      "tolerance":0.00,
      "transactionId":"PaymentInformation-20190307-150753-0000001"
   },
   "timestamp":"2023-12-18T22:02:12.5057094Z"
}

Daily general ledger balances generated

To ensure that you can keep track of the general ledger bookings the accounting module provides you with the notification type accounting/dailyGlaccountBalance. It is triggered daily and provides the account balances booked on previous day. This way you can keep your BS and P&Ls accounts synchronized on your end. One notification is sent for each combination of entry date, business code, fiscal year, fiscal period and currency.

To arrive at a notification of type accounting/dailyGlaccountBalance to be triggered, the following sample process steps illustrate a potential scenario:

  1. Merchant provides a new invoice/return/goodwill etc., the related PSP/Bank provides a settlement file/bank statement or any other booking is processed.
  2. Accounting as a Service executes the appropriate booking within the general ledger (BS and P&L).
  3. Accounting as a Service generates and triggers notifications of type accounting/dailyGlaccountBalanceonce a day.

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacksrequest using the type accounting/dailyGlaccountBalance as value in the list of notificationTypes.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2022-01-20T00:05:01.5110000+00:00",
  "documents": [
    {
      "entryDate": "2022-01-19",
      "businessCode": "1000",
      "documentNumber": "1001234567",
      "fiscalYear": "2022",
      "fiscalPeriod": "01",
      "currency": "EUR",
      "documentHeaderText": "",
      "documentReference": "01/2022",
      "lineItems": [
        {
          "lineItemNumber": "001",
          "postingKey": "Debit",
          "accountNumber": "141550",
          "alternativeAccountNumber": "240000",
          "accountDescription": "Debtors Receivables",
          "amountLocalCurrency": 119,
          "taxCode": "A1",
          "assignmentNumber": "",
          "itemText": "",
          "itemReference": ""
        },
        {
          "lineItemNumber": "002",
          "postingKey": "Credit",
          "accountNumber": "800000",
          "alternativeAccountNumber": "500000",
          "accountDescription": "Sales Income Normal",
          "amountLocalCurrency": -100,
          "taxCode": "A1",
          "assignmentNumber": "",
          "itemText": "",
          "itemReference": ""
        },
        {
          "lineItemNumber": "003",
          "postingKey": "Credit",
          "accountNumber": "188095",
          "alternativeAccountNumber": "460000",
          "accountDescription": "VAT Normal",
          "amountLocalCurrency": -19,
          "taxCode": "A1",
          "assignmentNumber": "",
          "itemText": "",
          "itemReference": ""
        }
      ],
      "transactionId": "DailyGLBalances-1000-005056A304E11EEBBC825A7482D0D6F2"
    },
  ],
  "type": "accounting/dailyGlaccountBalance"
}

See also