Callback URL - v4.0

• Overview
• Endpoints
  • POST /callback-urls
  • GET /callback-urls
  • PUT /callback-urls/{CallbackUrlId}
  • DELETE /callback-urls/{CallbackUrlId}
• Data Model
  • Callback Url - Request
    • UML Diagram
    • Data Dictionary
  • Callback Url - Response
    • UML
    • Data Dictionary
  • Callback Urls - Response
    • UML
    • Data Dictionary
• Usage Examples
  • Create Callback Url
    • POST Callback Url Request
    • POST Callback Url Response
  • Get Callback Urls
    • GET Callback Url Request
    • 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..*	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/v4.0/event-notifications",
	"Version": "4.0"
  }
}

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/v4.0/event-notifications",
		"Version": "4.0"
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v4.0/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/v4.0/event-notifications",
			"Version": "4.0"
		}]
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v4.0/callback-urls/"
	},
	"Meta": {}
}