Second Factor Authentication

In all API calls that transfer money out of the user's own accounts, there is an extra step of security called Second Factor Authentication.  With this additional step, the first time that a monetery transaction needs to take place after a successfull login, a second one-time pin must be provided by the end-user.

Second Factor Authentication

There are two methods for the user to get the second pin.

  • The first one is via a device that generates pins, at a predetermined frequency of a specific number of seconds. This token device, is provided by the bank, and the pin it produces is called OTP (one-time pin). 
  • The second one is via SMS messages. With this method, you have to 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 predeclared user 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 we need a second pin, 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 for us, and will expect a verification call from 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, you can call monetary APIs and no second pin is going to be requested again, until logout.

When you logout, or the session expires, the elevation is revoked.  In order to call monetary APIs again, the same process of second factor authentication must be repeated.



This is the currently defined process.  However, when the European Commission directive PSD2 comes into effect, this will change.  Then, you will have to provide a new second pin, for each monetary transaction.  When this directive is activated, the bank will alter the above procedure as required.