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.
When working with notifications of the accounting module, the following notification types are available.
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
.
{
"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"
}
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:
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
.
{
"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"
}
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:
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
.
{
"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"
}
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:
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.
{
"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"
}
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:
To arrive at a notification of type accounting/documentCreated
to be triggered, the following sample process steps illustrate a potential scenario:
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.
{
"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"
}
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:
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
.
{
"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"
}
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:
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
.
{
"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"
}
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:
accounting/paymentReceived
once 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-callbacks
request using the type accounting/paymentReceived
as value in the list of notificationTypes
.
{
"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"
}
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:
accounting/dailyGlaccountBalance
once a day.In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks
request using the type accounting/dailyGlaccountBalance
as value in the list of notificationTypes
.
{
"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"
}