Transactions authentication (SCA)
Most Card Transactions require an SCA.
When such a transaction occurs:
- Treezor notifies you by sending a
card3DSv2Authentication.create
webhook. - You authenticate your end user using the SDK and an SCA method
- You inform Treezor of the authentication result using a dedicated endpoint
- Treezor notifies you of the final transaction status by sending a
card3DSv2Authentication.update
webhook.
Authentication of the End User
Upon reception of the card3DSv2Authentication.create
webhook, you must authenticate your End User using the SDK and a strong authentication method such as Pin Authentication
or Device Biometric Authentication
.
Notification of Authentication Result
Upon authentication of the End User, you must inform Treezor of the authentication result by calling the following request:
bash
curl -X PUT '{baseUrl}/v1/auth-requests/{authenticationRequestID}/result`' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{payload}'
The authenticationRequestID
is provided in the card3DSv2Authentication.create
webhook.
Payload
The expected {payload
} contains two attributes.
json
{
"authenticationResult": "{string}", # End user authentication result (see below)
"authenticationSignature": "{string}" # SCA Proof (optional if the result is not 'OK')
}
The authenticationResult
can be:
OK
if the SCA was successfulKO_AUTH_FAILED
if the SCA was unsuccessful (the end user failed to authenticate themselves)KO_TECHNICAL
if a technical error prevented the authenticationFALLBACK
to request the sending of a One Time Password by SMS instead
The authenticationSignature
is the SCA proof, as generated by the SDK on the end user's device.
Example
bash
curl -X PUT '{baseUrl}/v1/auth-requests/b08ab5ac-56c4-40b8-9649-b10ce235ddeb/result`' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{
"authenticationResult": "OK", # Successful SCA
"authenticationSignature": "dnptZ3V...m9hZWc=" # SCA Proof (optional if result is not 'OK')
}'
Note – The authentication result must be provided to Treezor within 5 minutes of the webhook emission.
This delay can be modified to suit your specific needs by contacting your Treezor Account Manager.
Treezor may answer with:
200
HTTP Status Code
If your answer has been received and accepted by Treezor.
400
HTTP Status Code
If the provided attributes are invalid or missing.
json
{
"errors": [
{
"type": "invalid_request",
"code": "input_validation_error",
"message": "Invalid request data : The authenticationResult field is required|invalid.",
"requestId": "request-id",
"docUrl": "https://developers.treezor.co",
}
]
}
json
{
"authenticationResult": ["The authenticationResult field is required|invalid."],
"authenticationSignature": ["The authenticationResult field is invalid."]
}
If the authentication request has already been processed by Treezor.
json
{
"errors": [
{
"type": "invalid_grant",
"code": "authentication_error",
"message": "Authentication result already received",
"requestId": "request-id",
"docUrl": "https://developers.treezor.co",
}
]
}
json
{
"error": "Authentication Request Already Processed"
}
If the authentication request cannot be found on Treezor's side.
json
{
"errors": [
{
"type": "invalid_request",
"code": "resource_not_found_error",
"message": "Unable to find the authenticationRequestID in our system",
"requestId": "request-id",
"docUrl": "https://developers.treezor.co",
}
]
}
json
{
"error": "Unable to find the authenticationRequestID in our system"
}
500
HTTP Status Code
If an internal error on our side prevented us from accepting your answer
json
{
"errors": [
{
"type": "unexpected_internal_server_error",
"code": "unexpected_error",
"message": "Internal server error",
"requestId": "request-id",
"docUrl": "https://developers.treezor.co",
}
]
}
json
{
"error": "Internal server error"
}
Final authentication request status
Depending on the authentication result you sent to Treezor and Treezor's final processing, you're notified of the Card Transaction authentication status through the card3DSv2Authentication.update
webhook.
The authenticationFinalResult
value can be one of the following.
Final result | Description |
---|---|
SUCCESS | Authentication is successful and the card transaction proceeds. |
UNAUTHENTICATED | Treezor took into account that the authentication has failed. The card transaction fails. |
ERROR | An error occurred during the authentication process. The card transaction fails. This may occur regardless of your response, due to an error on the card processor's side. |
FALLBACK | You sent a FALLBACK response. Authentication switches to SMS_OTP mode. |
TIMEOUT | Authentication failed due to a timeout. The card transaction fails. This may occur regardless of your response, due to an error on the card processor's side. |