Quick Menu

Notifications

An overview of the notification types supported by the subscription 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 subscription 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.

In addition to the notifications described on this page, you may also be interested in the notifications from the accounting module, providing additional notification types that might help you to stay informed and react appropriately to changes.

Supported notification types

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

Billing information

To provide merchants with invoice information on their customers before the official invoice document is processed (e.g. a customer of a car sharing company is returning his car after a trip and directly after parking his car, he is provided with an overview in the app of the merchant about the associated costs), the subscription module offers the notification type subscription/billingInformationAvailable.

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

  • (Prerequisite) Customer has subscribed to usage-based service of merchant.
  • Customer consumes service (e.g. customer is using a car of a car sharing company for a trip).
  • Merchant is automatically informed once the service consumption has been completed (e.g. customer is returning the car).
  • Merchant passes the information as customer usage data to Accounting as a Service (see usage-based contract handling).
  • Accounting as a Service stores the received information and starts immediate processing based on the existing configuration.
  • After successfully calculating the due amount by the billing and rating engine, Accounting as a Service triggers a notification of type subscriptions/billingInformationAvailable (i.e. calling the configured endpoint on the merchant side).
  • (Optional) Merchant starts processing the billing information from the notification (e.g. customer gets push notification on his mobile app informing him about the costs associated with his recent trip).

In case you want to register a callback for this notification type, make a POST /administration/{version}/notification-callbacks request using the type subscriptions/billingInformationAvailable 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": {
    "customerNumber": "123456789",
    "externalContractId": "DFGDSFG3213213",
    "invoice": {
      "billToAddress": {
        "careOf": "Jane c/o John",
        "countryCode": "DE",
        "postalCode": "48213",
        "postalPlace": "Muenster",
        "street": "Beispielstr.",
        "streetNumber": "13A",
        "streetNumberAdditional": "string"
      },
      "billingEndDate": "2021-06-17T00:00:00.0000000",
      "billingStartDate": "2021-06-17T00:00:00.0000000",
      "currency": "SEK",
      "dueDate": "2021-06-17T00:00:00.0000000",
      "invoiceDate": "2021-06-17T00:00:00.0000000",
      "invoiceReference": "321321654",
      "items": [
        {
          "description": "Lizenz zum Buchen",
          "grossUnitPrice": 119.12,
          "quantity": 2.5,
          "vatAmount": 19.02,
          "vatPercent": 19
        }
      ],
      "orderChannel": "01",
      "orderDate": "2021-06-17T00:00:00.0000000",
      "orderReference": "SufYuBUU9sJ3OWpu",
      "shipToAddress": {
        "careOf": "Jane c/o John",
        "countryCode": "DE",
        "postalCode": "48213",
        "postalPlace": "Muenster",
        "street": "Beispielstr.",
        "streetNumber": "13A",
        "streetNumberAdditional": "string"
      },
      "totalGrossAmount": 2,
      "totalNetAmount": 2
    },
    "orderReference": "DSFGDS31231321",
    "transactionId": "123456789"
  },
  "type": "subscriptions/billingInformationAvailable"
}

Expiry warning

Depending on the payment method selected by the customer, there might be a situation that the customer's payment method is about to expire (e.g. in case your customer is using a credit card). To provide merchants with expiry warnings on their customers' payment methods, the subscription module offers the notification type subscriptions/expiryWarning.

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

  • (Prerequisite) Customer has subscribed to a subscription product of merchant using a credit card as payment method.
  • The credit card is about to expire.
  • Merchant is automatically informed about the expiration of the payment method 30 days in advance.
  • Merchant is automatically informed about the expiration of the payment method 7 days in advance.
  • Merchant is automatically informed about the expiration of the payment method 1 day in advance.

As the expiry warning normally results in having the merchant informing the customer about a replacement of the payment method to be required, the revised payment method will result in the existing registration to be cancelled and replaced by a new registration. Once a new registration exists, you need to update the related customer information.

Once the affected registration has been cancelled, no more notifications about the expiry warning will be triggered.

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

HINT Please note that the indicated frequency (i.e. 30days, 7days, 1day) represents the default configuration. In case you need the configuration to be adapted, please get in touch.

Sample notification

{
  "id": "40ffceca-642a-4158-85fc-3efa0e970db5",
  "timestamp": "2021-04-23T18:25:43.5110000+00:00",
  "parameters": {
    "customerNumber": "123456789",
    "paymentRegistration": {
      "id": "string",
      "paymentMethodName": "string"
    }
  },
  "type": "subscriptions/expiryWarning"
}

See also