Callbacks

Notification Service

This section covers how webhooks are used to notify about events that happen in an E-wallet Program. Some events, like disputed charges or account status changes, are not the result of a direct API request. Webhooks solve these problems by letting you provide a URL to which we will send a notification anytime such an event happens. The "Notification Target URL" will receive a JSON payload depending on the notification type. Based on your integration requirements the individual notifications have to be turned on. Please contact Customer Support or your administrator to check your individual integration use case.

Authentication Options

KontoCloud supports three types of authentication when sending callback notifications to the merchant's Notification Target URL. The merchant defines the preferred program during integration setup with their Product Solution Specialist.

Authentication Type	Behavior
No Authentication	No authentication information is sent in the requests to the merchant's Notification Target URL. IP Whitelisting is mandatory in this case, please contact Customer Support or your Administrator for the IP address which must be whitelisted.
Basic Authentication	The authentication is done by providing a username and password to your Product Solution Specialist for the Notification Service Settings of KontoCloud. These fields are used by KontoCloud for basic authentication for every call made to the Notification Target URL.
OAuth Authentication	Merchants must provide their Authentication URL endpoint along with the username and password to their Product Solution Specialist for OAuth authentication. The authentication token requested from the merchant's authentication server by KontoCloud is then attached to every call to the merchant's Notification Target URL.

important

KontoCloud expects an HTTP 200 OK response from the merchant's endpoint to confirm successful receipt. If the callback fails, KontoCloud retries delivery based on a predefined retry policy.

info

The merchant is responsible for ensuring the availability, security, and validation of their Notification Target URL endpoint as well as the Authentication URL for OAuth.

1. No Authentication

If no authentication is configured, KontoCloud sends a plain POST request without any authentication headers. This method is only recommended for internal testing or controlled environments.

Example request:

POST https://merchantdomain.com/api/kontocloud/notifications
Content-Type: application/json

{
  // callback payload
}

2. Basic Authentication

When Basic authentication is selected, KontoCloud includes an Authorization header containing the base64-encoded combination of the provided username and password.

Header Format:

Authorization: Basic base64(username:password)

Example request:

POST https://merchantdomain.com/api/kontocloud/notifications
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json

{
  // callback payload
}

3. OAuth Authentication

For secure integrations, KontoCloud supports OAuth 2.0 using the Client Credentials Grant. In this setup, the merchant exposes a token endpoint - Authentication URL, and shares the corresponding username and password. KontoCloud initiates the token request directly to the provided endpoint and includes the resulting access token as a Bearer token in all subsequent callbacks.

3.1. Token Request to Merchant Endpoint

To initiate the token request, KontoCloud performs a POST request to the merchant's Authentication URL with the following parameters:

POST https://merchantdomain.com/authorizationserver/oauth/token?grant_type=client_credentials
Content-Type: application/json

Body:

{
  "grant_type": "client_credentials",
  "username": "***",
  "password": "***",
}

Request Header:

Authorization: Basic base64(username:password)

3.2. Token Response

KontoCloud receives an access token from the merchant's authorization server in response to the token request:

{
  "access_token": "H4sIAAAAAAA***IaJ5Tm8QAAA",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": "public openid"
}

3.3. Callback with Bearer Token

The access token is then used to authorize the notification request. KontoCloud sends the callback to the merchant's Notification Target URL with the token included in the Authorization header using the Bearer scheme:

POST https://merchantdomain.com/api/kontocloud/notifications
Authorization: Bearer H4sIAAAAAAA***IaJ5Tm8QAAA
Content-Type: application/json

{
  // callback payload 
}

The token is valid for the duration specified in the expires_in field and reused for all following callbacks until it expires.

Notification Types

There are 2 distinct notification types:

• Program Specific Notifications: sending more detailed transaction information regarding the entire program, in addition to user management, compliance and others.
• Merchant Specific Notifications: only sending transaction related information regarding a specific merchant. They can be configured for each individual merchant.

info

You can provide a different endpoint for the Program's Notifications and each Merchant's Notifications. Please coordinate with your Product Solution Specialist.