Notification Service API

A SOAP web service that lets agents subscribe to a customer's payment obligations (utility bills, fines, tariffs, and balance top-ups) tracked by UCC, and retrieve newly generated notifications so they can alert customers — for example, by SMS — when a debt appears.

How it works

A subscribed notification is a standing instruction telling UCC "let me know about this service + customer combination." UCC's processing engine periodically checks that combination and, when it finds something worth reporting, produces a notification — the actual event record your agent fetches and acts on (e.g. by texting the customer that they have a bill due).

Subscription types

Every subscription is registered against a service that supports one of the following patterns:

Prerequisites on UCC's side

A service must be enabled for notifications in UCC's internal configuration before any agent can subscribe to it — this is reflected by notificationSubscriptionAllowed: true on that service when you sync your service catalog. If you try to subscribe to a service that hasn't been enabled, the call fails with SUBSCRIPTION_NOT_SUPPORTED. Ask your UCC integration contact to confirm which services are notification-enabled before building against them.

Authentication & security

Notification Service does not use a separate API key or OAuth token. Instead, every SOAP envelope must be encrypted and signed per the WS-Security specification, using an X.509 certificate registered with UCC for your agent account.

The envelope may optionally carry a WS-Security <Timestamp> element.

The shape below follows the generic OASIS WS-Security standard (not specific to UCC's spec) — included so the algorithms above make sense in context.

Certificate exchange

Trust between your system and UCC is mutual: each side generates its own X.509 key pair, signs its outgoing messages with its own private key, and gives the other side its public certificate for verification/decryption. Nobody issues a certificate on the other party's behalf — you generate yours, UCC generates theirs, and you exchange the public halves.

• Generate your key pair. Create an X.509 key pair on your side, using whatever standard tooling your team already uses (OpenSSL, Java keytool, or similar), and store it in a keystore of your choice. The keystore itself — its type, your alias names, its password — is entirely internal to you; none of it is shared with or dictated by UCC.
• Send UCC only your public certificate. Export the public certificate (not the keystore, not the private key) and send it to your UCC integration contact. This is the only artifact that crosses the boundary in this direction.
• Import UCC's public certificate into your own keystore once you receive it from UCC, so your side can verify/decrypt what UCC signs.
• Test. Confirm the exchange worked by having UCC synchronize your agent record on their side — your integration contact will run this check with you.
• Renewal follows the same flow: generate a new key pair, send the new public certificate to UCC, and import UCC's public certificate again if UCC has also rotated theirs.

SOAP conventions

Every operation lives under a single WSDL namespace and has its own SOAPAction. If you're generating a client from the WSDL, these are handled for you automatically — this table is for anyone wiring up requests by hand.

WSDL target namespace: http://ucc.ess.azry.com

The other request/response examples throughout this reference omit the tns: prefix for readability — assume it applies unless you're generating your client straight from the WSDL, in which case your toolkit handles this for you.

Environments

Errors & fault codes

Errors are returned as a standard SOAP Fault. Distinguish error cases using the fault code, not the fault string (which is intended for humans, not branching logic).

Fault structure

The fault code isn't in the generic SOAP <faultstring> — it's in a typed detail block, UCCNotificationsServiceException. Parse this, not the human-readable string, for branching logic:

Registers a new subscribed notification for a service + abonent (customer) pair.

Request parameters

Response

Possible faults

NON_UNIQUE_SUBSCRIPTION SUBSCRIPTION_NOT_SUPPORTED NOTIFICATION_SERVICE_TYPE_NOT_SUPPORTED DUPLICATE_SUBSCRIPTION

Cancels an active subscription. UCC stops checking for new debts/events on this pair.

Request parameters

The WSDL defines this as an empty sequence — absence of a SOAP Fault is the success signal, there's no body to inspect.

Batch version of addNotificationSubscription — registers multiple subscriptions in one call.

Request parameters

Response

Batch version of deleteNotificationSubscription.

Request parameters

Same as the single-delete operation — empty sequence in the WSDL, no per-item result (unlike the batch add operation, which does report per item).

Fetches notifications generated since the last one your agent processed. This is a pull operation — poll it on your own schedule (UCC generates new notifications roughly once per day per subscription).

Request parameters

Data types

NotificationSubscription

NotificationServiceOverridableParams

Set on NotificationSubscription.Params to override the service-level defaults for this specific subscription. All fields optional — omit to inherit the default.

AddNotificationSubscriptionResult

Notification

NotificationType enum

Describes the notification event itself — distinct from NotificationServiceType, which describes the subscription that produced it.

NotificationServiceType enum

AmountLimitExceedAction enum

Subscription lifecycle

UCC runs a nightly processing job across all active subscriptions. Understanding this loop makes retry and polling behavior on your side predictable.

• Registered — you call addNotificationSubscription; UCC stores it with status Created, not yet run.
• Checked — during its configured processing window, UCC checks the subscription for a debt/event once per day.
• Generated, skipped, or flagged — the run resolves to one of: a notification was generated; no debt exists; the result was ignored (e.g. a duplicate within the configured suppression window, or the same amount fetched again); or the run hit a problem and is flagged for review.
• Delivered — you retrieve the notification via getNotifications and advance your LastId cursor.
• Expired or cancelled — the subscription ends when EndDate passes, you explicitly delete it, or it sits idle past the configured inactivity threshold with no notifications generated.

Duplicate suppression & timing controls

UCC applies default processing windows so agents don't get flooded with repeat notifications for the same underlying debt. Each can be overridden per subscription via NotificationSubscription.Params:

Best practices

• Always send a non-empty AgentSubscriptionId. It's your only idempotency and lookup key for cancellation.
• Store LastId durably before acting on notifications, or advance it only after your side has fully processed the batch — whichever order avoids silently dropping notifications on a crash.
• Set MaxPaymentAmount deliberately. Pairing it with AmountLimitExceedAction: IGNORE is a simple way to avoid notifying customers about unexpectedly large or erroneous debts.
• Confirm a service is notification-enabled with your UCC integration contact before subscribing — otherwise every call fails with SUBSCRIPTION_NOT_SUPPORTED.
• Poll getNotifications on a schedule that matches UCC's nightly processing cadence (e.g. once every few hours) rather than continuously — new data won't appear faster than the processing window regenerates it.