Transactions authentication (SCA)

Most 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 by calling the following request:

CURL

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 2 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 successful
• KO_AUTH_FAILED if the SCA was unsuccessful (the end user failed to authenticate themselves)
• KO_TECHNICAL if a technical error prevented the authentication
• FALLBACK 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

CURL

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 (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.