<ČSOB SK> developer portal

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.