Appearance
Transactions authentication (SCA)
Most online Card Transactions require an SCA.
When a Card Transaction goes through SCA, the following 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 the 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 with the dedicated endpoint.
Parameters
The following parameters are expected in the payload.
Attribute | Type | Description |
---|---|---|
authenticationResult | string | Whether the authentication was successful. See Authentication result for the list of values. |
authenticationSignature | string | The SCA proof, as generated by the SDK on the end user's device. Only required when the authentication result is OK . |
Authentication result
authenticationResult | Description |
---|---|
OK | The Strong Customer Authentication of your end user was successful. |
KO_AUTH_FAILED | The end user failed to strongly authenticate themselves. |
KO_TECHNICAL | A technical error prevented the authentication. |
FALLBACK | Allows you to request from the sever a one-time password (OTP SMS). |
Request example
Endpoint: /v1/auth-requests/{authRequestId}/result
You can find the value for the authRequestId
query parameter in the authenticationRequestId
of the card3DSv2Authentication.create
webhook.
bash
curl -X PUT '{baseUrl}/v1/auth-requests/{authRequestId}/result`' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{payload}'
1
2
3
4
2
3
4
Here is a {payload}
example.
json
{
"authenticationResult": "OK", // Successful SCA
"authenticationSignature": "dnptZ3V...m9hZWc=" // SCA Proof (optional if result is not 'OK')
}
1
2
3
4
2
3
4
Note – You have 5 minutes to provide the result to Treezor
You must provide the authentication result 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.
Responses
Treezor may answer with the following HTTP status codes.
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",
}
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
json
{
"authenticationResult": ["The authenticationResult field is required|invalid."],
"authenticationSignature": ["The authenticationResult field is invalid."]
}
1
2
3
4
2
3
4
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",
}
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
json
{
"error": "Authentication Request Already Processed"
}
1
2
3
2
3
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",
}
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
json
{
"error": "Unable to find the authenticationRequestID in our system"
}
1
2
3
2
3
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",
}
]
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
json
{
"error": "Internal server error"
}
1
2
3
2
3
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. |
Tip – Authentication simulation available
Treezor allows you to simulate the authentication of an online card transaction. See Simulate card transaction authentication (SCA) for more information.