Strong customer authentication (SCA)

API history

This process allows to authenticate user in bank environment and authorize user requests. If process is successful, it returns authorization code for:

  • AISP/PISP/PIISP – code for 90 days access to account (binding accounts to scope(s) and TPP)
  • PISP - code for submitting Payment order, Standing order, Standing order update, Standing order cancellation or Payment order cancellation (binding token to specific payment order)

Step 1: Redirect to CSOB for Strong Customer Authentication (SCA) and requests authorization

Strong Customer Authentication (SCA) is based on OAuth 2.0 Authorization code grant flow. SCA and request authorization is realized by the client after redirection to bank environment using credentials isued by the bank. SCA process must be done within 20 min.


Redirect URL

TPP has to prepare the redirect URL by adding parameters to the query component of the authorization URL using the "application/x-www-form-urlencoded" format.

Redirect URL
Version1
URL LIVE
https://apiauthorization.csob.sk/connect/authorize?client_id={client_id}&response_type={response_type}&redirect_uri={redirect_uri}&scope={scope}&state={state}&nonce={nonce}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}&request={orderId}

Attributes structure
Optionality
Type
Description
client_id
Mandatory
String
TPP ID obtained from enrollment
response_type
Mandatory
String
Authorization code grant flow, value is „code“
redirect_uri
Mandatory
String
Redirect URL to be redirected after SCA, redirect URL must be in list of URL addresses from enrollment
scope
Mandatory
String
The scope of the access request according to SBAS: AISP, PISP, PIISP. These scopes can be combined according to TPP rights. For 90 days access, scope offline_access must be also present (not for payment authorization).
Example for obtaining long-term token: AISP offline_access
Example for obtaining token for submitting payment: PISP
state
Mandatory
String
An opaque value used by the TPP to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the TPP. The parameter should be used for preventing cross-site request forgery
nonce
Mandatory
String
String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
code_challenge
Mandatory
String
code_challenge must be composed according RFC 7636:
BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
code_challenge_method
Mandatory
String
Value: S256
request
Optional
String
OrderId (in JSON response in field orderId) or BatchId (in XML response (pain.002) in field MsgId) from Payment initiation, Standing order initiation, Standing order update, Standing order cancellation or Payment order cancellation must be used when this order is being authorized during SCA process.


Response URL

After succesfull SCA proces and request authorization, the authorization server issues an authorization code and delivers it to the TPP by adding the following parameters to the query component of the redirection URL using the "application/x-www-form-urlencoded" format. Code validity is due to security reasons limited to 5 min.

Response URL
Version1
URL LIVE
https://{redirectURL}?code={code}&scope= {requested scopes}&state={state}

Attributes structure
Optionality
Type
Description
code
Mandatory
String
The authorization code generated by the authorization server. The authorization code expires in 5 min after it is issued to mitigate the risk of leaks. The client must not use the authorization code more than once. If an authorization code is used more than once, the authorization server deny the request.
scope
Mandatory
String
The exact value of scope parameter received from the client.
State
Mandatory
String
The exact value of state parameter received from the client.


Error Response URL

If the SCA or request authorization fails, the authorization server informs TPP by adding the following parameters to the query component of the redirection URL using the "application/x-www-form-urlencoded" format.

Error response URL
Version1
URL LIVE
https://{redirectURL}?error={error}&error_description={error_description}

Attributes structure
Optionality
Type
Description
error
Mandatory
String
One of the following error codes may be present:
  • invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  • unauthorized_client
The client is not authorized to request an authorization code using this method.
  • access_denied
The resource owner or authorization server denied the request.
  • unsupported_response_type
The authorization server does not support obtaining an authorization code using this method.
  • invalid_scope
The requested scope is invalid, unknown, or malformed.
  • server_error
The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
  • temporarily_unavailable
The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
error_description
Optional
String
Additional information to the error code


Example:

Redirect URL for obtaining authorization code for token for payment submitting

https://apiauthorization.csob.sk/connect/authorize?client_id=TIDgjzKuS7k&response_type=code&redirect_uri=https://www.csob.sk/psd2tpp&scope=PISP&state=aaaa&nonce=aaaa&code_challenge=GR_ZPQOvmFRmdtRXg6KsdNTOnUduFvzOvfqZnWS62cA&code_challenge_method=S256&request=mGFW1Lmch8ux838wR56I51


Response URL with authorization code for token for payment submitting

https://www.csob.sk/psd2tpp?code=6ba9fe5808e2b0e7d8901f56a24dbef28a5ae76425e6e2872eb0ce228c907c36&scope=PISP&state=aaaa


Redirect URL for obtaining authorization code for long-term token (90 days access to account)

https://apiauthorization.csob.sk/connect/authorize?client_id=TIDgjzKuS7k&response_type=code&redirect_uri=https://www.csob.sk/psd2tpp&scope=AISP PISP PIISP offline_access&state=aaaa&nonce=aaaa&code_challenge=sz17t2L581__p3FJU_5HgaDhCHUIsbPGRaY5FQLLHbI&code_challenge_method=S256&request=


Response URL with authorization code for long-term token (90 days access to account)

https://www.csob.sk/psd2tpp?code=1f8247638988812f93f93053b71da73e3ef9c9a83e0f32b73c5158b7daa07379&scope=AISP%20PISP%20PIISP%20offline_access&state=aaaa


Step 2: Exchange authorization code for access token

Initiate POST request for Authorization code with a code obtained in Step 1. For details see Authorization API / Authorization Code. In response, there is an access token, which is binded to specific operation (payment or binding accounts to scope(s) and TPP) and must be used in further requests.

Strong customer authentication (SCA) – alternative flow


Alternative flow allows to authenticate user in bank environment and authorize 90 day access to account sent from TPP. Client account is sent to the bank within previous communication and is not selected by client during SCA process. If process is successful, it returns authorization code for:

  • AISP/PISP/PIISP – code for 90 days access to account (binding specific account to scope(s) and TPP)

Step 1: Get the access token with the scope AISP

Access token must be based on OAuth 2.0 Client credentials grant flow (Token by secret). See Authorization API section.


Step 2: Send client account to the bank by calling AISP endpoint

Initiate POST requests for Account transactions / Account information / Standing order list with valid access token obtained in Step 1 and specific IBAN.


Request

See specific section for endpoints Account transactions / Account information / Standing order list


Response

HTTP/1.1 400 Bad Request is correct response as token based on Client credentials grant flow is not enough to get the answer. This call is used only for transmitting IBAN from TPP to the bank.


Header

Attributes structure
Optionality
Type
Description
Content-Type
Mandatory
String
application/json
Response-ID
Mandatory
String
A unique identifier of a particular request message. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
Correlation-ID
Optional
String
A unique correlation identifier correlates the request and the response messages as a pair especially useful for audit logs. Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).
Process-ID
Optional
String
Identifier of a business or technical process to what the set of requests and response pairs are organized (e.g. paging of transaction history should have same ProcessID). Although it may be arbitrary string, it is strongly recommended to use a Universally Unique Identifier (UUID) version 4 form (RFC4122).

Body

Attributes structure
Optionality
Type
Description
errorCode
Mandatory
String
parameter_invalid is correct response
errorMessage
Mandatory
String
access_token_not_loged_in
TokenId
Optional
String
A unique identifier binds IBAN sent in request with following SCA.


Example:

Request

POST https://api.csob.sk/aisp/api/v1/accounts/information HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: 2d0e7c93d26b996bdbac105d92cab09ad28f73ff7082534fe7058e4539735670
Request-ID: 1822217325
Correlation-ID: 5842560052
Process-ID: 9226449240
PSU-Device-OS: Windows
PSU-User-Agent: Chrome
PSU-Geo-Location: 2.050279, 45.338591
PSU-Last-Logged-Time: 2020-09-22T08:25:31+02:00
PSU-IP-Address: 192.168.88.1
Content-Type: application/json;charset=UTF-8
Content-Length: 68
Host: api-acc.csob.sk
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
  "iban": "SK4075000000007777777777"
}

Response

HTTP/1.1 400 Bad Request
Content-Length: 136
Content-Type: application/json
Response-ID: 1822217325
Correlation-ID: 5842560052
Process-ID: 9226449240
Request-Context: appId=cid-v1:9bc136c9-7e98-4fa2-be98-5d03cc5fe907
Date: Tue, 22 Sep 2020 06:25:34 GMT

{
  "errorCode": "parameter_invalid",
  "errorMessage": "access_token_not_loged_in",
  "TokenId": "4XHR3hy2EfHvDTnwXSbxpRbTJ2C6Y4"
}


Step 3: Redirect to CSOB for Strong Customer Authentication (SCA) using tokenId

Strong Customer Authentication (SCA) is based on OAuth 2.0 Authorization code grant flow. SCA is realized by the client after redirection to bank environment using credentials isued by the bank.


Redirect URL

TPP has to prepare the redirect URL by adding parameters to the query component of the authorization URL using the "application/x-www-form-urlencoded" format.

Redirect URL
Version1
URL LIVE
https://apiauthorization.csob.sk/connect/authorize?client_id={client_id}&response_type={response_type}&redirect_uri={redirect_uri}&scope={scope}&state={state}&nonce={nonce}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}&request={TokenId}

Attributes structure
Optionality
Type
Description
client_id
Mandatory
String
TPP ID obtained from enrollment
response_type
Mandatory
String
Authorization code grant flow, value is „code“
redirect_uri
Mandatory
String
Redirect URL to be redirected after SCA, redirect URL must be in list of URL addresses from enrollment
scope
Mandatory
String
The scope of the access request according to SBAS: AISP, PISP, PIISP. These scopes can be combined according to TPP rights. For 90 days access, scope offline_access must be also present.
Example for obtaining long-term token: AISP offline_access
state
Mandatory
String
An opaque value used by the TPP to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the TPP. The parameter should be used for preventing cross-site request forgery
nonce
Mandatory
String
String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
code_challenge
Mandatory
String
code_challenge must be composed according RFC 7636:
BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
code_challenge_method
Mandatory
String
Value: S256
request
Optional
String
TokenId from previous step. TokenId is used for binding IBAN with client, TPP and Scopes and is valid 20 min.


Response URL

After succesfull SCA proces and request authorization, the authorization server issues an authorization code and delivers it to the TPP by adding the following parameters to the query component of the redirection URL using the "application/x-www-form-urlencoded" format. Code validity is due to security reasons limited to 5 min.

Response URL
Version1
URL LIVE
https://{redirectURL}?code={code}&scope= {requested scopes}&state={state}

Attributes structure
Optionality
Type
Description
code
Mandatory
String
The authorization code generated by the authorization server. The authorization code expires in 5 min after it is issued to mitigate the risk of leaks. The client must not use the authorization code more than once. If an authorization code is used more than once, the authorization server deny the request.
scope
Mandatory
String
The exact value of scope parameter received from the client.
State
Mandatory
String
The exact value of state parameter received from the client.


Error Response URL

If the SCA or request authorization fails, the authorization server informs TPP by adding the following parameters to the query component of the redirection URL using the "application/x-www-form-urlencoded" format.

Error response URL
Version1
URL LIVE
https://{redirectURL}?error={error}&error_description={error_description}

Attributes structure
Optionality
Type
Description
error
Mandatory
String
One of the following error codes may be present:
  • invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  • unauthorized_client
The client is not authorized to request an authorization code using this method.
  • access_denied
The resource owner or authorization server denied the request.
  • unsupported_response_type
The authorization server does not support obtaining an authorization code using this method.
  • invalid_scope
The requested scope is invalid, unknown, or malformed.
  • server_error
The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)
  • temporarily_unavailable
The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)
error_description
Optional
String
Additional information to the error code


Example:

Redirect URL for obtaining authorization code for long-term token (90 days access to account)

https://apiauthorization.csob.sk/connect/authorize?client_id=TIDgjzKuS7k&response_type=code&redirect_uri=https://www.csob.sk/psd2tpp&scope=AISP offline_access&state=aaaa&nonce=aaaa&code_challenge=GR_ZPQOvmFRmdtRXg6KsdNTOnUduFvzOvfqZnWS62cA&code_challenge_method=S256&request=4XHR3hy2EfHvDTnwXSbxpRbTJ2C6Y4


Response URL with authorization code for long-term token (90 days access to account)

https://www.csob.sk/psd2tpp?code=6ba9fe5808e2b0e7d8901f56a24dbef28a5ae76425e6e2872eb0ce228c907c36&scope=AISP%20offline_access&state=aaaa


Step 4: Exchange authorization code for access token

Initiate POST request for Authorization code with a code obtained in Step 3. For details see Authorization API / Authorization Code. In response, there is an access token, which is binded to specific account, scope(s) and TPP.