Strong customer authentication (SCA)
API historyThis 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:
|
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.