Last updated

Strong customer authentication (SCA)

SCA is a two-factor authentication method used to certify the origin and content of specific API requests related to sensitive operations or data (account login, transactions, card details, etc.). This is mandatory under the PSD2 regulation.

To enforce this two-factor authentication, LinkCy relies on:

  • a trusted device
  • either a PIN or biometrics

These requirements are achieved with a mobile SDK which has to be included in the partner's mobile app.
To use this SDK, check the SDK Library page.
This SDK is provided by Wultra, a trusted and secured solution for 2-Factor Authentication

This SDK will ensure that the device is trusted and will also handle the PIN or biometrics authentication.

Once the SDK is implemented, trusted device has to be declared for each enduser : see Device onboarding.

Then, each "SCA eligible" API endpoint will require a specific flow, to ensure that SCA is performed and validated : see Secure API requests.

Device registration

To onboard a device, use the "Register a known mobile" endpoint.

You will have to provide:

Path ParamDescription
endUserIdUser whom the device is belonging to.

The endpoint will return :

{
"activationQrCodeData": "string",
"activationCode": "string",
"activationCodeSignature": "string",
"registrationId": "string"
}

Then follow the Provider instructions to use this activationCode within the Mobile SDK SCA SDK Documentation

Once done, if the Promise return is successful you can call our endpoint commit a registration with the previously provided registrationId to finalise the registration.

If successful, user's device is registered and SCA requests can now be performed for this enduser.

Only one trusted device can be onboard per enduser so far.
Update to have several ones is coming soon.

Device registration Sequence Diagram

Here is a generic sequence diagram for a SCA device registration. This sequence can be adapted if you use your own backend.

Direct connection to LinkCy API

Mobile AppMobile SDKLinkcy APICall Device Registration EndpointReturn ActivationCodeRegsitration with ActivationCodeResponseCall Registration Commit EndpointMobile AppMobile SDKLinkcy API

Operation Data Signing

API requests which require SCA will be done in 2 steps :

  • Prepare SCA operation:

You have to create a Signature using the Mobile SDK. Follow the SCA SDK Documentation and provider's official instructions.

  • Perform SCA operation:

Once the signature is generated, you can call the SCA Secured Endpoint in LinkCy API, using :

  • the generated Signature in the Linkcy-SCA-Signature header
  • DATA_SIGNING in Linkcy-SCA-Strategy

If the signature is OK, the operation will be performed and the response will be a 200, 201 or 204 code.

Operation Signing Sequence Diagram

Here are generic sequence diagrams for a SCA-protected API request :

Direct connection to LinkCy API

Mobile AppMobile SDKLinkcy APISensitive Operation - Generate SignatureReturn SignatureRequest SCA operation (type, payload) including SignatureOperation ReponseMobile AppMobile SDKLinkcy API

Or if you have your own back-end :

Mobile AppMobile SDKPartner Back-endLinkcy APISensitive Operation - Generate SignatureReturn SignatureRequest SCA operation with SignatureRequest SCA operation including SignatureOperation ReponseOperation ReponseMobile AppMobile SDKPartner Back-endLinkcy API

Out of band authentication

SCA can also be triggered with a push notification, when the operation is not initiated from the device.
The registered device will receive a Push Notification which will trigger a SCA request.

This feature is not implemented yet, but will be available soon.

Failures

Here are the errors you can receive

ErrorHeader paramCodeDescription
SCA_REQUIREDLinkcy-SCA-Strategy409 conflictThe operation requires SCA. Can be returned if you try to use BY-PASS while not allowed. Will be returned if strategy is FAIL.
SCA_DEVICE_NOT_SETLinkcy-SCA-Strategy409 conflictThe operation requires SCA and strategy allow it, but the user has no sca device set up. You need to enroll one first.
SCA_FACTOR_NOT_SETLinkcy-SCA-Factor400 Bad requestThe user has a sca device set up, but the factor requested is not enrolled yet. You must either enroll it or change the factor.
SCA_INTERACTION_NOT_FOUNDLinkcy-SCA-Id404 not foundThe specified id could not be found.
SCA_INTERACTION_NOT_COMPLETEDLinkcy-SCA-Id409 conflictThe SCA interaction is not completed (pending).
SCA_INTERACTION_DECLINEDLinkcy-SCA-Id409 conflictThe SCA interaction was declined by user or expired.
SCA_INTERACTION_ALREADY_CONSUMEDLinkcy-SCA-Id409 conflictThe SCA interaction has already been used, you need to create a new one.
SCA_INTERACTION_DOES_NOT_MATCHLinkcy-SCA-Id409 conflictThe SCA interaction does not match the one you are trying to make. Body or url is different.

If a device or a factor is not onboarded and you try an API request involving SCA, you will receive 409 - SCA_DEVICE_NOT_SET or 400 - SCA_FACTOR_NOT_SET error.

If the SCA was failed, error will be 409 - SCA_INTERACTION_DECLINED.

SCA bypass

In some specific cases, SCA can be Bypassed, using the BY_PASS option in Linkcy-SCA-Strategy.

In this case, no SCA will be required and the operation will be performed.

Check with your contacts at LinkCy to know more about this.

In Sandbox environment, SCA can be bypassed on every endpoint.