Fraud confirmation

Yes, after a later review confirms that a specific transaction corresponded to a fraud attempt, the consumer can report it to the service. This information strengthens future detections on the same document or identity. This step is optional.

Endpoint

POST /document/validate/fraud-report

Headers

Name	Type	Required	Description
Authorization	string	Yes	Consumer Token in Bearer format Bearer <token> (see Authentication).
consumer-id	string	Yes	Consumer identifier.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
transactionId	string	Yes	Identifier of the validation transaction that is confirmed as fraud.
categories	array	Yes	One or more categories of the detected fraud. Each value must belong to the catalog of valid categories (see below).
comment	string	No	Free-text comment, max. 500 characters.

Valid categories

The field categories only accepts the following codes:

Code	Description
document_is_manipulated	The document is manipulated.
document_shown_from_screen	The document is shown from a screen.
document_is_printed_copy	The document is a printed copy.
selfie_shown_from_screen	The selfie is shown from a screen.
selfie_is_manipulated	The selfie is manipulated.
selfie_document_portrait_mismatch	The selfie does not match the document portrait.
injected_media	The content (image/video) was injected.

This list reflects the current catalog at the time this guide was published. The service validates the categories against the updated catalog; send only the codes in this table.

Request example

{
  "transactionId": "1c7d...e9",
  "categories": ["document_is_manipulated", "selfie_is_manipulated"],
  "comment": "Confirmed as fraud after internal review"
}

Responses

200 Success

{
  "accepted": true
}

All applicable confirmation actions were recorded correctly. This includes enrolling the face in the applicable blocklists (see below). The operation is idempotent: if the face was already in a blocklist, or if the transaction had already been reported previously, the retry is still considered a success and returns 200.

400 Bad Request

Some of the categories sent does not belong to the catalog of valid categories. No action is recorded; correct the categories and try again.

401 Unauthorized

Missing, invalid, or expired Token.

403 Forbidden

The consumer is not provisioned with the service DOCUMENT_ANTIFRAUD.

404 Not Found

The specified transaction does not exist.

422 Unprocessable Entity

The transaction does not support reporting: only completed transactions in state COMPLETED.

429 Too Many Requests

The consumer has exceeded its request rate limit. The response includes Retry-After with the wait seconds, and X-RateLimit-Limit and X-RateLimit-Burst within the current thresholds. No action is recorded.

503 Service Unavailable

Some of the applicable confirmation actions could not be completed. The confirmation is not considered fully recorded; the consumer must retry later or, if the problem persists, report it to support indicating the transactionId. The operation is idempotent, so retrying is safe.

Face blocklists

When the fraud-confirmed transaction includes a selfie, the face is enrolled in the applicable blocklists so that future validations detect it (codes 200/201, see result response):

• Platform blocklist: the face is always enrolled in the platform's own blocklist.

• Global blocklist: additionally, if the platform participates in the shared global blocklist, the face is also enrolled in it.

Participation in the global blocklist is agreed with Facephi during service onboarding and is not controlled through the API. Its scope is symmetrical: it applies both to the search during validation as well as to the enrollment in this fraud confirmation. If the transaction was processed without a selfie (without TOKEN_FACE_IMAGE), no face is enrolled in any blocklist.

It is recommended to send a single fraud report per transaction. However, retrying is safe: the operation is idempotent and a report already registered returns 200 without duplicating effects.