Consents and consent management are core concepts of the PSD2 solution, and are defined with dedicated API endpoints in the Berlin Group specification. The general mechanism for validating and authorizing consents is through a Redirect SCA Approach - utilising implicit start of the authentication process. This is described in NextGenPSD2 XS2A Framework - Implementation Guide, Section 6.1.1.1, Page 101.
Access to the Consent Information Service API is controlled through the general onboarding/enrollment flow. I.e. the API is only accessible to valid TPPs, who have completed the enrollment in order to upload and verify their qualified certificates. By accessing the API, you confirm that you already have status as an authorized TPP - or (for sandbox access only) that your application has been submitted to a local NCA and is pending approval. Only TPPs who can document their authorization status are elegible for support.
The CIS API is part of the general PSD2 XS2A implementation and works in the same security context. In addition to the information contained below, all communication, headers and additional steps adhere to the general security model and flows. Refer to this link for up to date information on required security headers.
At present, consent API only applies to Account Information APIs (AIS) and only supports global consent to all PSD2 accounts.
The API is implemented against Berlin Group XS2A version 1.3.
Note about this version This version of the AIS API now also supports testing of security, consent and SCA flows in sandbox with full security context.
- The sandbox API works on (stateless) mocked account data, while SCA, security and consent flows are identical to production.
- The security model for TPP enrollment and PSU authentication/authorization is implemented and enforced for both production and sandbox API
Access to API Endpoints
Production and sandbox access: Prior to calling the API the TPP must complete the (one-time) process for Onboarding on a per-bank basis. Separate API URL/host endpoints are required for each bank under the BEC Umbrella. Consult the Environments section for information on URL schemas in production and sandbox environments. See list of included ASPSPs and their corresponding urls by following this link. The X-IBM-Client-Id attribute is not required in this version.
Paths
/consents
Create consent
Called by TPP to request a consent from PSU to access account information services at the ASPSP on behalf of the PSU. The implementation is based on Berlin Group NextGenPSD2 XS2A Framework. Currently only global consent to all accounts is supported.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
URI to which the PSU is redirected after SCA.
URI to which the PSU is redirected in case of a negative result of the SCA.
Client ID of the TPP in the ASPSP client interface (elaborated under the description of general security model).
Payload for consent creation
Created
Bad request. For example: Timestamp not in accepted time period.
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/{consentId}/status
Can check the status of an account information consent resource.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/{consentId}
Returns the content of an account information consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.
Query status of an already created consent.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
OK
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
The TPP can delete an account information consent object if needed.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
OK
No Content
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
/consents/{consentId}/authorisations/{authorisationId}
The TPP get the information of authorisation related to the consent
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
Authorisation identifier returned upon the consent creation.
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/confirmation-of-funds
Creates confirmation of funds consent resource at the ASPSP regarding access to accounts specified in this request.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
URI to which the PSU is redirected after SCA.
URI to which the PSU is redirected in case of a negative result of the SCA.
Payload for confirmation of funds consent creation
Created
Bad request. For example: Timestamp not in accepted time period.
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/confirmation-of-funds/{consentId}
Returns a confirmation of funds consent object. This is returning the data for the TPP.
Query status of an already created consent.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the confirmation of funds consent resource (as returned by a previous Post operation)
OK
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/confirmation-of-funds/{consentId}/authorisations/{authorisationId}
The TPP get the information of authorisation related to the confirmation of funds consent
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
Authorisation identifier returned upon the consent creation.
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
/consents/confirmation-of-funds/{consentId}/status
Can check the status of a confirmation of funds consent resource.
ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness).
The ID of the content resource (as returned by a previous Post operation)
Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed.
Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore.
Not found. For example: The addressed resource is unknown relative to the TPP.
Definitions
Account representation. Either iban or bban MUST be filled out
{
"type": "object",
"properties": {
"bban": {
"type": "string",
"example": "01234567890123",
"description": "BBAN (Basic Bank Account Number) up to 14 digits forming the\naccount number used to identify an account intranationally\\nPattern: [0-9]{1,14}",
"maxLength": 14
},
"iban": {
"type": "string",
"example": "DK9520000123456789",
"description": "IBAN (International Bank Account Number) up to 34 alphanumeric\ncharacters consisting of a two letter country code, a two digit checksum,\nand a BBAN\\nPattern: [A-Z]{2}[0-9]{2}[A-Z0-9]{1-30}",
"maxLength": 34
}
},
"title": "Account"
}
This is a collection of links to other endpoints where the consent can be used.
{
"type": "object",
"properties": {
"accounts": {
"$ref": "#\/definitions\/Link"
}
},
"title": "AccountLinks"
}
{
"type": "object",
"properties": {
"scaStatus": {
"type": "string",
"enum": [
"CREATED",
"PENDING",
"APPROVED",
"REJECTED"
]
}
},
"title": "Authorisation"
}
ConsentRequest
{
"type": "object",
"properties": {
"access": {
"$ref": "#\/definitions\/ScimAccountAccess"
},
"frequencyPerDay": {
"type": "integer",
"format": "int32",
"description": "The maximum number of request, this consent can be used for per day, this is default 4."
},
"recurringIndicator": {
"type": "boolean",
"description": "true if the consent should be authorised for multiple requests, false of the consent should be authorised for only one request"
},
"validUntil": {
"type": "string",
"example": "2019-10-30T00:00:00.000Z",
"description": "The date of when the consent should expire in ISODate Format. If a maximal available date is requested, a date in far future is to be used: '9999-12-31'.\n"
}
},
"title": "ConsentRequest"
}
Consent
{
"type": "object",
"properties": {
"_links": {
"$ref": "#\/definitions\/AccountLinks"
},
"access": {
"$ref": "#\/definitions\/ScimAccountAccess"
},
"consentId": {
"type": "string",
"description": "Identification of the consent resource as it is used in the API structure"
},
"consentStatus": {
"type": "string",
"description": "Authentication status of the consent"
},
"frequencyPerDay": {
"type": "integer",
"format": "int32",
"description": "The maximum number of request, this consent can be used for per day, this is default 4."
},
"lastActionDate": {
"type": "string",
"description": "This date is containing the date of the last action on the consent object either through the XS2A interface or the PSU\/ASPSP interface having an impact on the status."
},
"recurringIndicator": {
"type": "boolean",
"description": "true if the consent should be authorised for multiple requests, false of the consent should be authorised for only one request"
},
"validUntil": {
"type": "string",
"example": "2019-10-30T00:00:00.000Z",
"description": "The date of when the consent should expire in ISODate Format. If a maximal available date is requested, a date in far future is to be used: '9999-12-31'.\n"
}
},
"title": "Consent"
}
A collection of links
{
"type": "object",
"properties": {
"scaRedirect": {
"description": "The link to retrieve the transaction status of the consent request",
"$ref": "#\/definitions\/Link"
},
"scaStatus": {
"description": "The link to retrieve the scaStatus of the corresponding authorisation subresource.",
"$ref": "#\/definitions\/Link"
},
"self": {
"description": "The link to the Consent resource created by this request. This link can be used to retrieve the resource data.",
"$ref": "#\/definitions\/Link"
},
"status": {
"description": "The URL which the PSu must be redirected to in order to perform the SCA",
"$ref": "#\/definitions\/Link"
}
},
"title": "ConsentLinks"
}
Create and status consent response
{
"type": "object",
"properties": {
"_links": {
"$ref": "#\/definitions\/ConsentLinks"
},
"consentId": {
"type": "string"
},
"consentStatus": {
"type": "string"
}
},
"title": "ConsentResponse"
}
{
"type": "object",
"properties": {
"account": {
"$ref": "#\/definitions\/Account"
},
"consentStatus": {
"type": "string",
"description": "Authentication status of the consent",
"enum": [
"RECEIVED",
"VALID",
"REJECTED",
"TERMTPP",
"REVOKPSU"
]
},
"registrationInformation": {
"type": "string",
"description": "Additional description"
}
},
"title": "FcsConsent"
}
Link to a resource
{
"type": "object",
"properties": {
"href": {
"type": "string",
"example": "\/v1\/link\/to\/some\/resource",
"description": "URL pointing to a resource"
}
},
"title": "Link"
}
Requested access services
{
"type": "object",
"properties": {
"allPsd2": {
"type": "string",
"example": "allAccounts",
"enum": [
"allAccounts",
"allAccountsWithOwnerName"
]
}
},
"title": "ScimAccountAccess"
}
TPP Message Information
{
"type": "object",
"properties": {
"category": {
"type": "string",
"example": "ERROR",
"description": "Error category",
"enum": [
"ERROR",
"WARNING"
]
},
"code": {
"type": "string",
"example": "CONSENT_UNKNOWN",
"description": "Message code to explain the nature of the underlying error.",
"enum": [
"FORMAT_ERROR",
"SERVICE_INVALID",
"SERVICE_BLOCKED",
"CONSENT_UNKNOWN",
"CONSENT_INVALID",
"CONSENT_EXPIRED",
"..."
]
},
"text": {
"type": "string",
"example": "Product invalid",
"description": "Detailed message description"
}
},
"title": "TppMessage"
}
Messages to the TPP on operational issues.
{
"type": "object",
"properties": {
"tppMessages": {
"type": "array",
"items": {
"$ref": "#\/definitions\/TppMessage"
}
}
},
"title": "TppMessages"
}