04. How to Create and Authorise an AIS Consent

Your certificate must contain the PSP role = PSP_AI.

Exclusions

1. one-time consents are not supported ("recurringIndicator": false).
2. combined AIS and PIS sessions are not supported ("combinedServiceIndicator": true).

Step 1 Consent creation

On this step request to create a consent with consent data is sent to XS2A.

XS2A validates the role from the certificate, PSU-ID and request syntax. If all the validations have been completed successfully, XS2A returns a consentId.

It means that a consent resource has been created and must be authorised by PSU.

Created consent resource will be accessible under given consentId during 30 minutes from the moment of creation. Authorisation of given consent must be completed within this time.

If a consent is not authorised and its validity time is over the access to this resource will be cancelled and consent creation flow will be terminated.

Request

1. Go to /v1/consents.
2. Fill in mandatory data
   
   • Method = POST
   • PSU-ID = one of PSU-IDs from 09. Sandbox Test Accounts and Test Data
   • X-Request-ID = valid UUID
3. Fill in consent data according to the consent model

Example
{
 "access": {
"balances": [
{ "iban": "DE52500105173911841934" },
{ "iban": "DE89370400440532013005" }
],
"transactions": [
{ "iban": "DE52500105173911841934" },
{ "iban": "DE89370400440532013005" }
]
},
"recurringIndicator": true,
"validUntil": "2019-12-28",
"frequencyPerDay": "4",
"combinedServiceIndicator": false
}

     4. Execute the request.

Response

HTTP status code: 201 Created

Example
{ "consentStatus": "received",
"consentId": string,
"_links": { "startAuthorisation": "/v1/consents/{consentId}/authorisations" }
}

Step 2 Consent authorisation initiation

On this step consent authorisation is initiated.

XS2A validates the role from the certificate, consentId and request syntax. If all the validations have been completed successfully, XS2A returns an authorisationId inside the "updatePsuAuthentication" link.

It means that an authorisation sub-resource has been created for given consentId.

Created authorisation sub-resource will be accessible under given authorisationId during 30 minutes from the moment of creation. Authorisation of given consent must be completed within this time.

If a consent is not authorised and its validity time is over the access to this resource will be cancelled and consent creation flow will be terminated.

Request

1. Go to /v1/consents/{consentId}/authorisations or follow the "startAuthorisation" link from the response in Step 1.
2. Fill in mandatory data
   
   • Method: POST
   • PSU-ID: same as in Step 1
   • X-Request-ID: valid UUID
   • consentId: consentId received in response in Step 1
   • body: no body
3. Execute the request.

Response

HTTP status code: 200 Ok

On this step PSU password must be provided.

Please, use correspondent password from 09. Sandbox Test Accounts and Test Data.

Request

1. Go to /v1/consents/{consentId}/authorisations/{authorisationId} or follow the "updatePsuAuthentication" link from the response in Step 2.
2. Fill in mandatory data
   
   • Method: PUT
   • PSU-ID: same as in Step 1
   • X-Request-ID: valid UUID
   • authorisationId: authorisationId received in response in Step 2
   • consentId: consentId received in response in Step 1

3. Fill in psuData

   Example
   {
   "psuData": {"password": "string"}
   } 

4. Execute the request.

Response

HTTP status code: 200 Ok

Example
{
"scaStatus": "psuAuthenticated",
"scaMethods": [
{
"authenticationType": "SMS_OTP",
"authenticationMethodId": "sms"
},
{
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
}
],
"_links": {"selectAuthenticationMethod": "/v1/consents/{consentId}/authorisations/{authorisationId}",
"scaStatus": "/v1/consents/{consentId}/authorisations/{authorisationId}"}
}

Step 4 Select SCA method

PSU was authenticated successfully with its PSU-ID and password in the previous step and now XS2A offers selection of authentication methods.

An authentication method is a format of the 2nd factor that must be provided by PSU in order to complete the authorisation of a consent.

To trigger Decoupled SCA please use authenticationMethodId where "authenticationType" = "PUSH_OTP” in the response in the Step 3.

Request

1. Go to /v1/consents/{consentId}/authorisations/{authorisationId} or follow the "selectAuthenticationMethod" link from the response in Step 3.
2. Fill in mandatory data
   
   • Method: PUT
   • PSU-ID: same as in Step 1
   • X-Request-ID: valid UUID
   • authorisationId: authorisationId received in response in Step 2
   • consentId: consentId received in response in Step 1

3. Fill in authenticationMethodId 

   Example
   {
   "authenticationMethodId": "chip"
   }

4. Execute.

Response

HTTP status code: 200 Ok

Note: "authoriseTransaction" link will only be returned if EMBEDDED SCA has been chosen.

Example
{
"scaStatus": "scaMethodSelected",
"chosenScaMethod": {
"authenticationType": "CHIP_OTP",
"authenticationMethodId": "chip"
},
"_links": {"scaStatus": "/v1/consents/{consentId}/authorisations/{authorisationId}",
"authoriseTransaction": "/v1/consents/{consentId}/authorisations/{authorisationId}"}
}

Step 5 Provide 2nd factor

This is the final step where PSU completes consent authorisation by providing the 2nd factor (this is only applicable for EMBEDDED SCA approach).

In real-live operations, a bank will generate and send the 2nd factor to PSU.

In the Sandbox the behaviour of a bank is simulated: XS2A doesn't generate and sent any 2nd factors but offers default format of authentication data. Please, see 09. Sandbox Test Accounts and Test Data.

Request

1. Go to /v1/consents/{consentId}/authorisations/{authorisationId} or follow the "authoriseTransaction" link from the response in Step 4.
2. Fill in mandatory attributes
   
   • Method: PUT
   • PSU-ID: same as in Step 1
   • X-Request-ID: valid UUID
   • authorisationId: authorisationId received in response in Step 2
   • consentId: consentId received in response in Step 1

3. Fill in scaAuthenticationData according to the authentication method selected in the previous step. Please, see 09. Sandbox Test Accounts and Test Data.

Example
{
"scaAuthenticationData": "string"
}

      4. Execute the request.  

Response

HTTP status code: 200 Ok

Example
{
"scaStatus": "finalised",
"_links": {"scaStatus": "/v1/consents/{consentId}/authorisations/{authorisationId}"}
}