Strong Customer Authentication
To be PSD2 compliant Qonto has implemented Strong Customer Authentication (from this point onwards, SCA) on a number of sensitive actions that our API is offering.
A sensitive action is an action that requires the user’s authentication to reduce the risk of fraud.
To be able to execute sensitive actions using SCA, users should have granted access to your application from their account via OAuth2 (more information on OAuth overview). There are currently two methods that can be used:
- The user has enrolled a trusted mobile device. For more information they can visit How to pair my phone with my Qonto account?.
- Using passkeys.
- One-time passcode sent via SMS (Only available to Embed Partners).
Both options are available to all partners and the method can be changed on a request basis.
Step by step guide
Paired device flow
Passkey flow
POST /v2/my-sca-action
only for illustrative purposes.Initiate the sensitive action
You can specify which method to use via the X-Qonto-2fa-Preference
header. The possible values are paired-device
, passkey
, and sms-otp
. If no header is present, the default becomes paired-device
.
If paired-device
is selected and the user has not paired a device yet, you’ll get a 428 Precondition Required
response with a message
encouraging you to its enablement.
- With
paired-device
, the user will get a push notification on his device to authorise the action, and you’ll receive a428 Precondition Required
response containing, among other fields, a “SCA required”message
and asca_session_token
that you will need to reuse after. You have 15 minutes to use this token before it expires. - If
passkey
is used as a method, the user will receive a text message with a link to setup or use an existing passkey, and you’ll receive a428 Precondition Required
response containing, among other fields, a “Passkey verification required”message
and asca_session_token
that you will need to reuse after. You have 15 minutes to use this token before it expires.
Poll the SCA session
At this point, you can poll GET thirdparty.qonto.com/v2/sca_sessions/<sca-session-token>"
each second (at most) which will generate three possible outcomes:
waiting
: if the user has not authorized the action yet;deny
: if the user refused the action (or more than 15 minutes passed);allow
: if the user has authorised the action.
Perform the sensitive action
Once the user has authorized the action, you can use the sca_session_token
value from the previous response to set the X-Qonto-Sca-Session-Token
header and repeat the original sensitive action request with no other change than the new header. Note: It’s important that you replay the same request including the X-Qonto-2fa-Preference
header if it was added to the original request.
- If the token has expired or is invalid, you will receive a
412 Precondition Failed
with amessage
providing more information. - If the token is valid, the action will be effectively processed by the API.
SMS OTP Flow
Initiate the sensitive action
If sms-otp
is used as a method, you’ll receive a 428 Precondition Required
response with the following payload:
At this point, the user will receive an SMS containing a one-time passcode (OTP).
Capture and submit the OTP
You should implement a form to capture this OTP from the user, as shown in the image below. The recommended approach is to build a simple form where the user can enter the code they received via SMS.
You might also want to include an option for users to request a new OTP if they haven’t received the first one. To resend an OTP, simply repeat the original sensitive action request with the same parameters. There’s no separate API endpoint for resending - the same request will trigger a new SMS to be sent.
Call your action with the OTP
Once you have the OTP from the user, include it in the X-Qonto-MFA
header and repeat the original request with no other changes. Make sure to include the X-Qonto-2fa-Preference
header with the value sms-otp
.
Note: The SMS OTP option is only available to Embed Partners. SMS OTP should be considered a fallback option and not one of the primary authentication methods as it’s less secure than paired devices or passkeys. Qonto may review usage patterns and could apply limitations if SMS OTP is consistently used as the primary SCA method.
Testing a sensitive action in the Sandbox environment
In the Sandbox environment, testing sensitive actions can be challenging due to the need for a paired device or SMS authentication. To streamline this process, Qonto provides a mock
option for the X-Qonto-2fa-Preference
header, allowing you to simulate these actions without the need for physical devices or messages.
Using the Mock option
Here’s how you can effectively test sensitive actions in Sandbox:
Initiate the sensitive action
When you initiate a sensitive action, set the X-Qonto-2fa-Preference
header to mock
. This tells the system to simulate the authentication process.
Poll the SCA session
Use the following endpoint to check the status of your mocked SCA session:
GET https://thirdparty-sandbox.staging.qonto.co/v2/mocked_sca_sessions/<sca-session-token>
.
This endpoint functions similarly to the production polling endpoint, providing real-time updates on the session status.
Simulate user decision
You can simulate the approval or denial of the action using these endpoints:
- To approve the action:
POST https://thirdparty-sandbox.staging.qonto.co/v2/mocked_sca_sessions/<sca-session-token>/allow
- To deny the action:
POST https://thirdparty-sandbox.staging.qonto.co/v2/mocked_sca_sessions/<sca-session-token>/deny
Perform the sensitive action
Set the X-Qonto-2fa-Preference
header to mock
Benefits of Mock testing
By using the mock
option and these endpoints, you can efficiently test and QA sensitive actions in a controlled environment. This approach ensures that your application is well-prepared to handle sensitive actions securely and reliably when deployed to production.
This method not only simplifies the testing process but also enhances the reliability of your application, providing a seamless experience for users.
SMS OTP
With X-Qonto-2fa-Preference
set to sms-otp
, any 6-character code will be accepted as a valid OTP since no actual SMS messages are sent. This allows for easy testing of the SMS OTP flow without needing to wait for or simulate actual SMS delivery.