Callback URL - v3.1.4

1. Overview
2. Endpoints
   1. POST /callback-urls
   2. GET /callback-urls
   3. PUT /callback-urls/{CallbackUrlId}
   4. DELETE /callback-urls/{CallbackUrlId}
3. Data Model
   1. Callback Url - Request
      1. UML Diagram
      2. Data Dictionary
   2. Callback Url - Response
      1. UML
      2. Data Dictionary
   3. Callback Urls - Response
      1. UML
      2. Data Dictionary
4. Usage Examples
   1. Create Callback Url
      1. POST Callback Url Request
      2. POST Callback Url Response
   2. Get Callback Urls
      1. GET Callback Url Request
      2. GET Callback Url Response

Overview

The Callback URL resource is used by a TPP to subscribe to events with an ASPSP.

This resource description should be read in conjunction with a compatible Callback URL Profile.

Endpoints

A TPP will set up and maintain its call back details (URL and version number) using the callback-url resource.

Resource	HTTP Operation	Endpoint	Mandatory ?	Scope	Grant Type	Message Signing	Idempotency Key	Request Object	Response Object
callback-url	POST	POST /callback-urls	Optional	accounts payments fundsconfirmations	Client Credentials	Signed Request Signed Response	No	OBCallbackUrl1	OBCallbackUrlResponse1
callback-url	GET	GET /callback-urls	Mandatory (if resource POST implemented)	accounts payments fundsconfirmations	Client Credentials	Signed Response	No	n/a	OBCallbackUrlsResponse1
callback-url	PUT	PUT /callback-urls/{CallbackUrlId}	Conditional (See Note 1)	accounts payments fundsconfirmations	Client Credentials	Signed Request Signed Response	No	OBCallbackUrlResponse1	OBCallbackUrlResponse1
callback-url	DELETE	DELETE /callback-urls/{CallbackUrlId}	Conditional (See Note 1)	accounts payments fundsconfirmations	Client Credentials	n/a	No	n/a	n/a

Note 1

Implementation for an ASPSP is:

• Optional, where both the following are true:

  • The ASPSP supports aggregated polling only
  • The ASPSP only supports a single event type for aggregated polling

• Mandatory, when the above is not true and ASPSP implemented POST /callback-urls

POST /callback-urls

The API endpoint allows the TPP to ask an ASPSP to create a new callback-url resource.

• The POST action allows the TPP to register a callback URL for an ASPSP to send event notifications to.
• The ASPSP creates the callback-url resource and responds with a unique CallbackUrlId to refer to the resource.
• An ASPSP must respond with a 409 error if a callback-url exists for that TPP.

GET /callback-urls

The API endpoint allows the TPP to ask an ASPSP to retrieve its callback-url resource.

• The ASPSP retrieves the callback-url resource and responds with the resource.

PUT /callback-urls/{CallbackUrlId}

The API endpoint allows the TPP to ask an ASPSP to update a callback-url resource.

• The PUT action allows the TPP to update a callback URL for an ASPSP to send event notifications to.
• The ASPSP updates the callback-url resource and responds with the updated resource.

DELETE /callback-urls/{CallbackUrlId}

The API endpoint allows the TPP to ask an ASPSP to delete a callback-url resource.

• The ASPSP deletes the callback-url resource.

Data Model

Callback Url - Request

The OBCallbackurl1 object will be used for the call to:

• POST /callback-urls

UML Diagram

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBCallbackUrl1	OBCallbackUrl1	OBCallbackUrl1
Data	1..1	OBCallbackUrl1/Data	OBCallbackUrlData1
Url	1..1	OBCallbackUrl1/Data/Url	Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.	xs:anyURI
Version	1..1	OBCallbackUrl1/Data/Version	Version for the event notification.	Max10Text

Callback Url - Response

The OBCallbackUrlResponse1 object will be used for a response to a call to:

• POST /callback-urls
• PUT /callback-urls/{CallbackUrlId}

The OBCallbackUrlResponse1 object will also be used for the call to:

• PUT /callback-urls

UML

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBCallbackUrlResponse1	OBCallbackUrlResponse1	OBCallbackUrlResponse1
Data	1..1	OBCallbackUrlResponse1/Data	OBCallbackUrlResponseData1
CallbackUrlId	1..1	OBCallbackUrlResponse1/Data/CallbackUrlId	Unique identification as assigned by the ASPSP to uniquely identify the callback URL resource.	Max40Text
Url	1..1	OBCallbackUrlResponse1/Data/Url	Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.	xs:anyURI
Version	1..1	OBCallbackUrlResponse1/Data/Version	Version for the event notification.	Max10Text

Callback Urls - Response

The OBCallbackUrlsResponse1 object will be used for a response to a call to:

• GET /callback-urls

UML

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBCallbackUrlsResponse1	OBCallbackUrlsResponse1	OBCallbackUrlsResponse1
Data	1..1	OBCallbackUrlsResponse1/Data	OBCallbackUrlsResponseData1
CallbackUrl	0..n	OBCallbackUrlsResponse1/Data/CallbackUrl	OBCallbackUrlResponseData1
CallbackUrlId	1..1	OBCallbackUrlsResponse1/Data/CallbackUrl/CallbackUrlId	Unique identification as assigned by the ASPSP to uniquely identify the callback url resource.	Max40Text
Url	1..1	OBCallbackUrlsResponse1/Data/CallbackUrl/Url	Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.	xs:anyURI
Version	1..1	OBCallbackUrlsResponse1/Data/CallbackUrl/Version	Version for the event notification.	Max10Text

Usage Examples

Create Callback Url

POST Callback Url Request

POST /callback-urls HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json
Accept: application/json

{
  "Data": {
	"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
	"Version": "3.1"
  }
}

POST Callback Url Response

HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json

{
	"Data": {
		"CallbackUrlId": "CB-101",
		"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
		"Version": "3.1"
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/CB-101"
	},
	"Meta": {}
}

Get Callback Urls

GET Callback Url Request

GET /callback-urls HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Accept: application/json

GET Callback Url Response

GET/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json

{
	"Data": {
		"CallbackUrl": [{
			"CallbackUrlId": "CB-101",
			"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
			"Version": "3.1"
		}]
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/"
	},
	"Meta": {}
}