<Č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, 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}&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 orders: 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
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&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&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

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

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

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