Recovery strategies

For those transactions where a verdict cannot be determined, the client may choose to use recovery strategies. A transaction that requires a strategy will continue in progress until the response from the strategy is received or the sla time expires. At that time the transaction can be accepted or rejected automatically.

Strategies types

Token by Whatsapp or SMS

The phone number of the transaction is validated by sending a 6-digit token to that number. Here is an example of an evaluation response with this strategy:

{
    "id": "12345678",
    "analysis_type": "AUTOMATIC",
    "evaluation_id": "1b943df8-e4fa-4a50-a254-67186911d66e",
    "score": 50,
    "status": "received",
    "strategies": {
        "type": "VerificationCode",
        "link": "https://antifraud.koin.com.br/recovery/1b943df8-e4fa-4a50-a254-67186911d66e?language=pt"
    }
}

The flow is shown below:

Token by email

The email of the transaction is validated by sending a 6-digit token to that email. Here is an example of an evaluation response with this strategy:

{
    "id": "12345678",
    "analysis_type": "AUTOMATIC",
    "evaluation_id": "1b943df8-e4fa-4a50-a254-67186911d66e",
    "score": 50,
    "status": "received",
    "strategies": {
        "type": "VerificationCode",
        "link": "https://antifraud.koin.com.br/recovery/1b943df8-e4fa-4a50-a254-67186911d66e?language=pt"
    }
}

The flow is shown below:

Document Scan

Validates the identity of the buyer, who must upload the front and back of his identity document in the url provided. Here is an example of an evaluation response with this strategy:

{
    "id": "12345678",
    "analysis_type": "AUTOMATIC",
    "evaluation_id": "1b943df8-e4fa-4a50-a254-67186911d66e",
    "score": 50,
    "status": "received",
    "strategies": {
        "type": "DocumentScan",
        "link": "https://antifraud.koin.com.br/recovery/1b943df8-e4fa-4a50-a254-67186911d66e?language=pt"
    }
}

The flow is shown below:

Magic Link

The email or the phone of the transaction is validated by sending a magic link to the client. Here is an example of an evaluation response with this strategy:

{
    "id": "12345678",
    "analysis_type": "AUTOMATIC",
    "evaluation_id": "1b943df8-e4fa-4a50-a254-67186911d66e",
    "score": 50,
    "status": "received",
    "strategies": {
        "type": "VerificationCode",
        "link": "https://antifraud.koin.com.br/recovery/1b943df8-e4fa-4a50-a254-67186911d66e?language=pt"
    }
}

The flow is shown below:

CollectAuthRecovery

The collect must be authenticated with the indicated provider and mode. By the moment, only provider 3DS2 would be used (3D Secure version 2), and the options for field "mode" are "CHALLENGE" or "FRICTIONLESS".

Note: the 3DS2 provider is not supporting the mode forcing correctly, so we know that this is just a suggestion until this issue is fully resolved in the provider.

Here is an example of an evaluation response with this strategy:

{
	"id": "12345678",
	"analysis_type": "AUTOMATIC",
	"evaluation_id": "1b943df8-e4fa-4a50-a254-67186911d66e",
	"score": 50,
	"status": "received",
	"strategies": {
		"type": "CollectAuthRecovery",
		"provider": "3DS2",
		"mode": "CHALLENGE"
		}
}

After the collect is done, the client must send a recovering notification. There are two options available to continue with the case evaluation, using the notification synchronously or asynchronously.

Asynchronously notification

PATCH /notifications/{evaluation_id} with usual JWT authentication.

{
	"notification_date": "2024-09-12T20:56:23.164Z",
	"sub_type": "RECOVERING",
	"type": "STATUS",
	"strategies": {
		"type": "CollectAuthRecovery",
		"results": [
			{
			"status": "AUTHENTICATED", //ERROR
			"mode": "CHALLENGE", //or FRICTIONLESS
			"provider": "3DS2",
			"reason": "additional information is here"
			}
		]
	}
}

The complete asynchronous flow is shown below:

Synchronously notification

PATCH /v1/antifraud/recovery/{evaluation_id} with usual JWT authentication.

{
  "type": "COLLECT_AUTH_RECOVERY",
	"results": [
			{
			"status": "AUTHENTICATED", //ERROR
			"mode": "CHALLENGE", //or FRICTIONLESS
			"provider": "3DS2",
			"reason": "additional information is here"
			}
		]
}

The complete synchronous flow is shown below