Transactions authentication (SCA)

Most online Card Transactions require an SCA.

When a Card Transaction goes through SCA, the following occurs:

1. Treezor notifies you by sending a card3DSv2Authentication.create webhook.
2. You authenticate your end user using the SDK and an SCA method.
3. You inform Treezor of the authentication result using the dedicated endpoint.
4. 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.

CURL

curl -X PUT '{baseUrl}/v1/auth-requests/{authRequestId}/result`' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{payload}'

Here is a {payload} example.

JSON

{
	"authenticationResult": "OK",					// Successful SCA
	"authenticationSignature": "dnptZ3V...m9hZWc=" 	// SCA Proof (optional if result is not 'OK')
}

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",
        }
    ]
}

JSON (legacy)

{
	"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 (legacy)

{
	"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 (legacy)

{
	"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 (legacy)

{
	"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.

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.