{{ UPDATED }}

In all API calls that require increased security, there is an extra step called Second Factor Authentication (SCA). With this additional step, a second one-time pin (OTP) must be provided by the end-user in all cases when the API response informs them through an appropriate message or error. More specifically, up until PSD2 was put into effect, OTPs were required once per session and only in monetary transactions. Since then, OTPs have become transactional, meaning that a new extra pin must be supplied for each transaction, which is no longer necessarily monetary.

There are multiple SCA methods for the user to get the one-time pin.

• The first one is via a device that generates one-time pins (OTPs), at a predetermined frequency of a specific number of seconds (CHIP_OTP). This token device was provided by the bank until recently. 
• All other SCA methods require a mobile phone, registered per Piraeusbank client/winbank user. These SCA methods include receiving the OTP via SMS messages (SMS_OTP) or push notifications (PUSH_OTP) or, alternatively, using the smartphone's fingerprint functionality for the end-user to authorize the transaction (TOUCH_OTP).

Below, there is a detailed description of the SCA methods applied in our APIs per product version: 

[PB APIs v1.1]
The group of PB API Products under version 1.1 only used CHIP_OTP and SMS_OTP, applying SCA once per session and only for monetary transactions. With this method, the third-party application must request for a pin (called extrapin) from the bank, using the API /security/{TokenType}/generate. TokenType only has the value extrapin for the time being. The sms message will be delivered in the end-user's registered mobile number.
Both pins are validated the same way through an API call, via /token/validate/{TokenValue} or /{TokenType}/validate/{TokenValue}.  TokenValue is the pin the user received either through SMS or from the token device.  We can call either the first API and let the system detect what type of pin we need, or we can call the second one, to make the selection ourselves.  In general, the API engine knows if a second pin is required, and when we initiate a monetary transaction, it will check what kind of token the user supports, and act accordingly. 
For example, if the user has no otp device, but has an extrapin mobile number declared, it will automatically send the sms to the end-user, and will expect a verification call with the received code.  Therefore, when we call /token/validate/{TokenValue}, it will assume that TokenValue is an extrapin (sms) and not otp (from token device). 
If the user has otp device or both, the otp will take precedence and the system will not send an automatic extra pin.  So, when we call /token/validate/{TokenValue}, it will assume that TokenValue is an otp (from token device) and not an extra pin (sms). 
Finally, if the user has no means of second factor authentication, the monetary transaction call will return a 403 error (Forbidden) and will not proceed further.
This procedure is used once per session (login).  When the token gets validated, the session goes into elevated security mode.  After that, monetary APIs can be called and no second pin is going to be requested again, until logout.
Upon logout or session expiration, the elevation is revoked.  In order to call monetary APIs again, the same process of second factor authentication must be repeated.

[PB APIs v1.2]
The group of PB API Products under version 1.2 implement and support all the SCA methods mentioned previously, except for TOUCH_OTP. OTPs are transactional, i.e. required per transaction (currently only monetary, but could include non-monetary transactions in the future).
Third-party applications do not need to request for extrapin generation. Instead, in all cases when an OTP is needed, the API will return an appropriate message or error. If the preselected SCA method is not CHIP_OTP, then the system will automatically send an extra pin to the end-user's registered mobile phone (either via SMS or via push notification), during the transaction's validate step and will expect that extra pin as input for the transaction's execute step.
There is also the possibility to select a SCA method different from the end-user's preselected, by calling the endpoint /security/token/select/{TokenType}/for/{SessionKey}.
More details are provided in the products' technical documentation.

[PSD2 APIs]
The group of PSD2 APIs (both v1 and v3) implement and support all the SCA methods mentioned previously, including TOUCH_OTP. OTPs are transactional, i.e. required per transaction, both monetary and non-monetary.
Third-party applications do not need to request for extrapin generation. Instead, in all cases when an OTP is needed, the API will return an appropriate message or error. If the preselected SCA method is neither CHIP_OTP nor TOUCH_OTP, then the system will automatically send an extra pin to the end-user's registered mobile phone (either via SMS or via push notification), during the transaction's validate step and will expect that extra pin as input for the transaction's execute step. In the case of TOUCH_OTP, the system will require the end-user to authorize the transaction using their smartphone's fingerprint functionality, so the third-party application will not have to provide an extra pin during the transaction's execute step.
There is also the possibility to select a SCA method different from the end-user's preselected, by calling a particular endpoint depending on the API. 
More details are provided in the products' technical documentation.