Paths
/v1/consents
TPP Requests a new Consent.
Request ID
Client ID of the PSU in the ASPSP client interface. Might be mandated in the ASPSP's documentation. Is not contained if an OAuth2 based authentication was performed in a pre-step or an OAuth2 based SCA was performed in an preceding AIS service in the same session. Example: PSU-1234
Type of the PSU-ID, needed in scenarios where PSUs have several PSU-IDs as access possibility.
Might be mandated in the ASPSP's documentation. Only used in a corporate context.
Might be mandated in the ASPSP's documentation. Only used in a corporate context.
If it equals "true", the TPP prefers a redirect over an embedded SCA approach. If it equals "false", the TPP prefers not to be redirected for SCA. The ASPSP will then choose between the Embedded or the Decoupled SCA approach, depending on the choice of the SCA procedure by the TPP/PSU. If the parameter is not used, the ASPSP will choose the SCA approach to be applied depending on the SCA method chosen by the TPP/PSU.
URI of the TPP, where the transaction flow shall be redirected to after a Redirect.
Mandated for the Redirect SCA Approach, specifically when TPP-Redirect-Preferred equals "true". It is recommended to always use this header field.
Remark for Future: This field might be changed to mandatory in the next version of the specification.
If this URI is contained, the TPP is asking to redirect the transaction flow to this address instead of the TPP-Redirect-URI in case of a negative result of the redirect SCA method. This might be ignored by the ASPSP.
The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU.
The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available.
The forwarded Agent header field of the HTTP request between PSU and TPP, if available.
HTTP method used at the PSU ? TPP interface, if available. Valid values are:
- GET
- POST
- PUT
- PATCH
- DELETE
UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of an installation identification this ID need to be unaltered until removal from device.
The forwarded Geo Location of the corresponding http request between PSU and TPP if available.
{
"pattern": "GEO:-?[0-9]{1,2}\\.[0-9]{6};-?[0-9]{1,3}\\.[0-9]{6}"
}Consent body request
Successful response
Bad Request
Not Found
Request Timeout
Internal Server Error
/v1/consents/{consentId}
Returns the content of an account information consent object.
Request ID
ID of the corresponding consent object as returned by an Account Information Consent Request.
Successful response
Bad Request
Not Found
Request Timeout
Internal Server Error
Deletes an account information consent object.
Request ID
OAuth2 based SCA was performed in the corresponding consent transaction or if OAuth2 has been used in a pre-step.
Contains the resource-ID of the consent to be deleted.
Successful response
Bad Request
Not Found
Request Timeout
Internal Server Error
/v1/consents/{consentId}/status
Returns the content of an account information consent object.
Request ID
The consent identification assigned to the created resource.
Successful response
Not Found
Request Timeout
Internal Server Error
Definitions
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Optional error code for reporting purposes."
},
"errorDescription": {
"type": "string",
"description": "The description of the error."
}
}
}
{
"type": "object",
"properties": {
"access": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Account_Access"
},
"recurringIndicator": {
"type": "boolean",
"description": "true - if the consent is for recurring access to the account data. false - if the consent is for one access to the account data",
"example": true
},
"validUntil": {
"description": "Datetime the transaction was created.",
"type": "string",
"format": "date",
"example": "2017-11-01"
},
"frequencyPerDay": {
"description": "This field indicates the requested maximum frequency for an access per day. For a one-off access, this attribute is set to \"1\".",
"type": "integer",
"example": 4
},
"combinedServiceIndicator": {
"type": "boolean",
"description": "true - indicates that a payment initiation service will be addressed in the same \"session\" - NOT IMPLEMENTED AT THE MOMENT",
"example": true
}
},
"required": [
"access",
"recurringIndicator",
"validUntil",
"frequencyPerDay",
"combinedServiceIndicator"
]
}
All attributes are optional but at minimum one of these should exist.
{
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Resources"
}
},
"balances": {
"type": "array",
"items": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Resources"
}
},
"transactions": {
"type": "array",
"items": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Resources"
}
}
}
}
{
"type": "object",
"properties": {
"consentStatus": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Status"
},
"consentId": {
"type": "string",
"description": "Identification of the consent resource as it is used in the API structure. Shall be contained, if a consent resource was generated."
},
"scaMethods": {
"type": "array",
"items": {
"$ref": "#/definitions/XS2A_Sca_Methods"
}
},
"_links": {
"$ref": "#/definitions/XS2A_Berlin_Links"
}
},
"required": [
"consentStatus",
"_links"
]
}
This data element might be contained, if SCA is required and if the PSU has a choice between different authentication methods.
Depending on the risk management of the ASPSP this choice might be offered before or after the PSU has been identified with the first relevant factor, or if an access token is transported.
If this data element is contained, then there is also an hyperlink of type 'startAuthorisationWithAuthenticationMethodSelection' contained in the response body.
These methods shall be presented towards the PSU for selection by the TPP.
{
"type": "array",
"items": {
"$ref": "#/definitions/authenticationObject"
}
}
Authentication Object
{
"title": "authenticationObject",
"required": [
"authenticationMethodId",
"authenticationType"
],
"type": "object",
"properties": {
"authenticationType": {
"$ref": "#/definitions/authenticationType"
},
"authenticationVersion": {
"type": "string",
"description": "Depending on the \"authenticationType\".\nThis version can be used by differentiating authentication tools used within performing OTP generation in the same authentication type.\nThis version can be referred to in the ASPSP?s documentation."
},
"authenticationMethodId": {
"maxLength": 35,
"type": "string",
"description": "An identification provided by the ASPSP for the later identification of the authentication method selection.",
"example": "myAuthenticationID"
},
"name": {
"type": "string",
"description": "This is the name of the authentication method defined by the PSU in the Online Banking frontend of the ASPSP.\nAlternatively this could be a description provided by the ASPSP like \"SMS OTP on phone +49160 xxxxx 28\".\nThis name shall be used by the TPP when presenting a list of authentication methods to the PSU, if available.",
"example": "SMS OTP on phone +49160 xxxxx 28"
},
"explanation": {
"type": "string",
"description": "Detailed information about the SCA method for the PSU.",
"example": "Detailed information about the SCA method for the PSU."
}
}
}
{
"title": "authenticationType",
"type": "string",
"enum": [
"SMS_OTP",
"CHIP_OTP",
"PHOTO_OTP",
"PUSH_OTP",
"APP_TO_APP_IOS",
"APP_TO_APP_ANDROID",
"SCAREDIRECT"
]
}
{
"type": "object",
"properties": {
"consentStatus": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Status"
}
},
"required": [
"consentStatus"
]
}
{
"type": "object",
"properties": {
"scaRedirect": {
"$ref": "#/definitions/XS2A_Berlin_Href",
"description": "In case of an SCA Redirect Approach, the ASPSP is transmitting the link to which to redirect the PSU browse."
},
"status": {
"$ref": "#/definitions/XS2A_Berlin_Href",
"description": "The link to retrieve the transaction status of the account information consent."
}
},
"required": [
"scaRedirect",
"status"
]
}
{
"type": "object",
"properties": {
"href": {
"type": "string",
"example": "https://api.testbank.com"
}
},
"required": [
"href"
]
}
{
"type": "object",
"properties": {
"iban": {
"type": "string",
"description": "IBAN of an account.",
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{12,30}$",
"example": "DE2310010010123456789"
},
"currency": {
"type": "string",
"description": "Currency of an account.",
"pattern": "^[A-Z]{3,3}$",
"example": "USD"
}
}
}
{
"type": "object",
"properties": {
"access": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Account_Access"
},
"recurringIndicator": {
"type": "boolean",
"description": "true - if the consent is for recurring access to the account data. false - if the consent is for one access to the account data"
},
"validUntil": {
"description": "Datetime the transaction was created.",
"type": "string",
"format": "date",
"example": "2017-11-01"
},
"frequencyPerDay": {
"description": "This field indicates the requested maximum frequency for an access per day. For a one-off access, this attribute is set to \"1\".",
"type": "number",
"format": "integer",
"example": 4
},
"lastActionDate": {
"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.",
"type": "string",
"format": "date",
"example": "2017-11-01"
},
"consentStatus": {
"$ref": "#/definitions/XS2A_Berlin_Consent_Status"
}
},
"required": [
"access",
"recurringIndicator",
"validUntil",
"frequencyPerDay"
]
}
Authentication status of the consent.
{
"type": "string",
"enum": [
"received",
"valid",
"rejected",
"revokedByPsu",
"expired",
"terminatedByTpp"
]
}