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 registration.
Then, each "SCA eligible" API endpoint will require a specific flow, to ensure that SCA is performed and validated : see Operation Data Signing.
To onboard a device, use the "Register a device" endpoint.
You will have to provide:
Path Param | Description |
---|---|
endUserId | User whom the device is belonging to. |
The endpoint will return :
{
"activationQrCodeData": "string",
"activationCode": "string",
"activationCodeSignature": "string",
"scaDeviceId": "string"
}
activationCode
cointains the code required by the SDK to activate the device.activationQrCodeData
represent this code under QR Code format.scaDeviceId
represents the id of the device which will be registered. Registered devices will be listed in the Enduser object with their status and details.
Then follow the instructions to use this activationCode within the Mobile SDK : SCA SDK Documentation
Once activation done in the mobile SDK, you have to call the Activate a device
endpoint with the previously provided scaDeviceId
to finalise the registration.
If successful, user's device is registered and SCA requests can now be performed for this enduser.
Several SCA devices can be registered per enduser.
After the first registration, SCA operation is required to registered any extra device.
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
One method to authenticate SCA protected operation is Data Signing. These requests have to be done in 2 steps :
- Prepare SCA operation:
Before you can send the API request, you have to create a Signature using the Mobile SDK.
Data to be signed are : HTTP Method, URI (including path params and query params) and body (if present).
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 :
DATA_SIGNING
inLinkcy-SCA-Strategy
- the generated Signature in the
Linkcy-SCA-Signature
header
The signature will have this format :
PowerAuth pa_activation_id=\"3c193fe9-ac04-4a2e-aa85-8b3d0ed4aeab\", pa_application_key=\"EklLXwMlpZhwMLHAXyX/XWHA==\", pa_nonce=\"C2irDMhb8VR3+QBTfIsAJg==\", pa_signature_type=\"possession_knowledge\", pa_signature=\"9Z+KT9LjNEdsXYfrW2ASEy85egP2InuSGnNgsd2K2xE=\", pa_version=\"3.3\
You have to send this full Payload in the Linkcy-SCA-Signature header field.
If the signature is OK, the operation will be performed and the response will be a 200, 201 or 204 code.
Here are generic sequence diagrams for a SCA-protected API request :
Direct connection to LinkCy API
Or if you have your own back-end :
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.
Here are the errors you can receive
Error | Code | Description |
---|---|---|
ERROR_SIGNATURE_INVALID | 400 Bad request | Indicates that the signature HTTP header is invalid. This occurs when signature verification for online approvals fails due to incorrect or malformed signature details. |
ERROR_TOKEN_INVALID | 400 Bad request | Indicates that the token HTTP header is invalid or that an unsupported protocol version was used. This occurs when token verification fails due to incorrect or malformed token details. |
ERROR_REQUEST | 400 Bad request | Indicates the request did not pass structural validation (mandatory field is null, invalid field type, etc.). |
ERROR_OTP_INVALID | 400 Bad request | Indicates a failure in OTP verification due to an invalid OTP format. |
ERROR_OPERATION_NOT_FOUND | 400 Bad request | Indicates that an operation with the provided ID was not found. |
ERROR_OPERATION_STATE_CHANGE | 400 Bad request | Indicates that the operation’s state does not allow the requested action, for example, cancelling an already expired operation. |
ERROR_INTERNAL_API | 500 not found | An internal server error occurred, potentially due to misconfiguration. Check your deployment configuration for errors. |
SCA_REGISTRATION_NOT_FOUND | 404 Not found | The SCA registration was not found for end user. |
ERROR_REGISTRATION_NOT_ALLOWED | 400 Bad request | Indicates registration is not allowed because another registration is already in progress for the user. |
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
.
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.