Introduction

Event Notifications is a new feature that is specific to version 3.0 and later of the API Centre standards. A Third Party subscribes to types of notifications they wish to receive which are generated and sent by the API Provider when the related event occurs. The API Provider will send the notifications to the endpoint specified in the subscription created by the Third Party.

To reduce complexity, only a single subscription per Third Party is maintained at the API Provider, however a single subscription can include multiple notification types. Third Parties may update their subscription at any time, including removing (deleting) it.

Glossary

The following terms are used in this explainer:

Prerequisites

Before making use of Event Notifications API, a Third Party must have:

• A bilateral agreement in place with an API Provider

• Established connectivity with the API Provider

• Deployed an endpoint that is capable of receiving and processing Event Notifications

  • The endpoint URI must match the Event Notification requirements

Version applicability

As event notifications is new in v3.0, notifications are currently only supported for resources created using v3.0 API standards. This is because applying event notifications to previous versions would mean:

...

Operation of event notifications

Event notifications in v3.0 are functionally quite simple, in order to reduce the complexity for implementation. A Third Party creates a subscription via the API for any of the two currently available event notification types, and when a change occurs to a resource that matches the event notification type the API Provider sends the event notification to the Third Party endpoint.

Subscribing to events

To create a subscription, an API request is made to POST /event-subscriptions, including three key pieces of information:

...

• Subscriptions for different event types or multiple resource versions managed independently

• Different resource versions of same event type in separate subscriptions

• Subscriptions for different event types sent to different Callback URL using separate subscriptions

...

Subscription example

Examples of the event subscription can be found here. Below is some expanded guidance on key aspects of an event subscription request:

...

"EventTypes": [
  "urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked",
  "urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-revoked"
]

Receive Notifications

Given a subscription for event notifications has been successfully created, a Third Party can now receive notifications for events that relate to the types and resource version specified in the subscription. These will be delivered to the specified callback URL, via POST /${CallbackUrl}, where CallbackUrl was specified in the request.

Notification example

Examples of notifications can be found here. Below is some expanded guidance on the notification that will be sent to the API Provider.

...

"http://apicentre.paymentsnz.co.nz/rid": "bbd-3245-002", \\ resource identifier
"http://apicentre.paymentsnz.co.nz/rlk": [{              \\ resource links array
  "link": "https://examplebank.co.nz/api/open-banking-nz/v3.0/enduring-payment-consents/bbd-3245-002", \\  link to where the resource can be retrieved
  "version": "v3.0"                                       \\ version of the API where the resource can be retrieved
  }],
 "http://apicentre.paymentsnz.co.nz/rty": "enduring-payment-consents", \\ the type of the resource that the event refers to
 "subject_type": "http://apicentre.paymentsnz.co.nz/rid_http://apicentre.paymentsnz.co.nz/rty" \\ the subject type for the updated resource

Multiple link example

If an API Provider has multiple versions of the API where the resource can be retrieved, these must be specified in the links array;

"http://apicentre.paymentsnz.co.nz/rlk": [{
    "link": "https://examplebank.co.nz/api/open-banking-nz/v3.0/enduring-payment-consents/bbd-3245-002",
    "version": "v3.0"
  },
  {
    "link": "https://examplebank.co.nz/api/open-banking-nz/v3.1/enduring-payment-consents/bbd-3245-002",
    "version": "v3.1"
}]

Retrieve resource

To retrieve the updated resource, a Third Party makes a GET request to the endpoint specified in the link array. For example

GET "https://examplebank.co.nz/api/open-banking-nz/v3.0/enduring-payment-consents/bbd-3245-002" HTTP/1.1
Authorization: Bearer ShTe76Gzdqpiun
x-fapi-interaction-id: 79ae17fa-d9c9-11ee-94ee-00155d9e3188
Accept: application/json

Manage subscriptions

A Third Party may optionally choose to update, retrieve or remove their subscriptions.

...