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 (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.


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
Hybrid flow, value is „code id_token“
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. With requested scopes there must also be the scope openid. If 90 days access is needed, scope offline_access must be present (not for payment authorization).
Example for obtaining long-term token: AISP openid offline_access
Example for obtaining token for submitting payment: PISP openid
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 from Payment initialization must be used when payment 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}&id_token={id_token}&scope= {requested scopes}&state={state}&session_state={session_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.
id_token
Mandatory
String
JSON Web Token (JWT) that contains encoded user‘s authentication information which is represented in the form of claims. These claims are statements about the user, which can be trusted if the consumer of the token can verify its signature.
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.
session_state
Mandatory
String
JSON string that represents the End-User's login state at the OP.


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 id_token&redirect_uri=https://www.csob.sk/psd2tpp&scope=PISP openid&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&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjExYzBhNzg1YWMyZGZiZjEzYmJiNmMyNjhmZTI0ZDY1IiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NjAyNDM3MTUsImV4cCI6MTU2MDI0NDAxNSwiaXNzIjoiaHR0cHM6Ly9hcGlhdXRob3JpemF0aW9uLWFjYy5jc29iLnNrIiwiYXVkIjoiVElEQkJ0cnRINVUiLCJub25jZSI6ImFhYWEiLCJpYXQiOjE1NjAyNDM3MTUsImNfaGFzaCI6IkhBRGptSGZBMU5qdXZxUmRUT09sUUEiLCJzaWQiOiJlN2YwOTBkNWViYjBiYmRlMmIzZjczODYzNjkzMjU3NSIsInN1YiI6IkwxeU0xbXhGM2kyQ0xJZDJMTjVJUTlsTjhwd2ZCblNIajdsVSIsImF1dGhfdGltZSI6MTU2MDI0MzcxNCwiaWRwIjoibG9jYWwiLCJhbXIiOlsicHdkIl19.ow2d2Hsm0lR-KBqHuBY0Xyq66i8Swb85gvgwMsE8shkjOZYxjVfIjLOmHyNwOuZuIN4mqbjAwljQdf-J93j2
hovZuoOb6Z1hTv-GNTf91u-Dh0C58nJ4RCMtLmbgAbGJT5VMQjDABjtyoTykIx9ZhIOe7UrhEIs-yXr_TyEthj
cn3mUNJu-Ut2lBk0p4pBsbOAqa-5tdl6bEzG1jcFC690DyrHYy0hW6KNDVWpVq2q1KxLLfe4uczfefsN5zG0iA
2Oq3yv7tWaZYb1xbqrZPvVTEzFqHW7KqGmu7ZlIoyZQtS8aFkSbAbwz3z6YGOkDQyzGFvcJjNwtBF2zVj7deXw&scope=openid%20PISP&state=aaaa&session_state=48Rvcn5xAGHoW_YFDJfrr51wHtH6dFhstP2IcOboN-Y.149b87c537db0ebdd82fe92ff84c0094


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 id_token&redirect_uri=https://www.csob.sk/psd2tpp&scope=AISP PISP PIISP openid 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&id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjExYzBhNzg1YWMyZGZiZjEzYmJiNmMyNjhmZTI0ZDY1IiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NjAyNDE4MzksImV4cCI6MTU2MDI0MjEzOSwiaXNzIjoiaHR0cHM6Ly9hcGlhdXRob3JpemF0aW9uLWFjYy5jc29iLnNrIiwiYXVkIjoiVElEQkJ0cnRINVUiLCJub25jZSI6ImFhYWEiLCJpYXQiOjE1NjAyNDE4MzksImNfaGFzaCI6IjdkUFRlOE5jRkpDT1BON2tvSFBRNGciLCJzaWQiOiIzMTVmMzE5Mzc4NTA3OGU2YjdlZWQ0YzlmMWI4MDM3NSIsInN1YiI6InZvUjRhODFoVWppQVNhQmpPNmptRjhjTkxTaDhGWUQ2c2M4YyIsImF1dGhfdGltZSI6MTU2MDI0MTgzOSwiaWRwIjoibG9jYWwiLCJhbXIiOlsicHdkIl19.TsANlVgWsM2bFtGjHLBANvwAVgIiwvQ5wgog0-4KpORmteXCo6uWEdj_b5hwHVhzWo_GdahrUqLB6Nfej6po
BA8N9bAU4m9UDdJ7H20nRf0EJBHoHuYXZQFxDwjv27XICgX8vd9eiPG11e7xFOXnPjeVEAYglysZEK6mao1yysLQt8enk9t2hKwDCwjZRZV_yaUzE8fcZ4Rzw3N583hWNvEr57URe7QchFNZBKRVJqFOaT7ugMpANpn7RYaVQIow6R91jZvI8yL-ipDonI6OW1bF4IAcqOsTTXv6eewd7XmNxKYPdgqmf_aj3DB7XnYGltOzM49_L5BTr4byGwNV5Q
&scope=openid%20AISP%20PISP%20PIISP%20offline_access&state=aaaa&session_state=Kuh7hV8q_X9ka9YbklfweRoUEwwyYn4oljmnmxmMOT4.fea0c42e219c49281fddb065b37682a3


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.