# SDK response update 3.1.0.0 As part of the SDK update, starting now we will generate standardized response objects, including the full detail of fields and their possible values. Additionally, we improved the tagging logic to correctly detect icons and related events. With these improvements, when a spoofing-related event is detected, a transaction will be generated and the event will be recorded with its corresponding details. If spoofing is detected, an evidence image will also be sent to the customer-provided **webhook**. Moreover, from now on the transaction details (including the transaction number) will be delivered through the webhook to ensure an auditable record of the event.

**Expected response:** Transaction details sent to the webhook.

**SDK response level (PSA):** This information will be returned by the SDK as part of the standardized response object.

```json { "processType": "liveness", "statusCode": 1, "detail": { "status": "approved", "reason": { "name": "NOT_ALERT", "description": "The transaction was approved." }, "uidDevice": "1da62007d8974a9fa71e18cba76f6fc1", "keyProcessLiveness": "69c265aeca9d4863b61b1fc6a8099f52", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12", "image": { "encoding": "base64", "mimeType": "image/jpeg", "data": "" } } } ```
### Field description
- **processType**: Type of process executed. - Possible values: `"liveness" | "cardcapture"` - Notes: - If `processType = "liveness"`, the field `keyProcessLiveness` **may be present**. - If `processType = "cardcapture"`, `keyProcessLiveness` **must NOT be returned**. - **Side**: Indicates which side of the document was captured**. - Possible values: `"front" | "back"` - Notes: - If `processType = "liveness"`, the field **Side** **must NOT be returned**. - If `processType = "cardcapture"`, **Side** **may be present**. - **statusCode**: Numeric result code of the process. - `1` = approved - `2` = rejected - `3` = failed - **detail**: Object containing the detailed outcome. - **status**: Text status of the result. - Possible values: `"approved" | "rejected" | "failed"` - **reason**: Human-readable reason for the result. - **name**: Short label describing the reason (e.g., `"No alerts"`). - **description**: Longer explanation of the reason (e.g., `"The transaction was approved."`). - **uidDevice**: Unique device identifier (string). - **keyProcessLiveness** *(only for liveness)*: Unique identifier for the liveness process (string). - Returned **only** when `processType = "liveness"`. - **processId**: Unique process identifier (GUID/UUID) generated per execution to correlate SDK responses and webhook events. - **image**: Image object associated with the process. - **encoding**: Encoding type used for the image payload. - Typical value: `"base64"` - **mimeType**: MIME type of the image data. - Examples: `"image/jpeg"`, `"image/png"` - **data**: Base64-encoded image content (string). - Usually provided **without** the `data:image/...;base64,` prefix.
**The component’s possible responses are split by functionality:** **CardCapture** (document capture) or **Liveness** (proof of life). Below is a practical, complete list of outcomes you should handle (success, pending, failures, cancellations, and technical errors).
***Liveness***
Status (code)Nombre (name)Descripción (description)Objeto (reason)
`NONE``NOT_ALERT`The transaction was approved with no alerts detected.`{"code":"NONE","name":"NOT_ALERT","description":"The transaction was approved with no alerts detected."}`
`NOT_ALIVE``Not alive detected`The liveness check indicates the subject is not alive.`{"code":"NOT_ALIVE","name":"Not alive detected","description":"The liveness check indicates the subject is not alive."}`
`CLOSED_EYES``Eyes closed detected`The subject's eyes were detected as closed during the capture.`{"code":"CLOSED_EYES","name":"Eyes closed detected","description":"The subject's eyes were detected as closed during the capture."}`
`SPOOFING``Spoofing detected`A potential spoofing attempt was detected during the liveness process.`{"code":"SPOOFING","name":"Spoofing detected","description":"A potential spoofing attempt was detected during the liveness process."}`
`PAD``Presentation attack detected (PAD)`A potential presentation attack was detected (PAD confidence triggered).`{"code":"PAD","name":"Presentation attack detected (PAD)","description":"A potential presentation attack was detected (PAD confidence triggered)."}`
`PERMISSION_DENIED``Camera permission denied`Camera access was denied by the user or the operating system.`{"code":"PERMISSION_DENIED","name":"Camera permission denied","description":"Camera access was denied by the user or the operating system."}`
`CAMERA_NOT_FOUND``Camera not found`No camera was detected on the device, or it is unavailable.`{"code":"CAMERA_NOT_FOUND","name":"Camera not found","description":"No camera was detected on the device, or it is unavailable."}`
`FACE_NOT_DETECTED``Face not detected`No face was detected in the camera frame.`{"code":"FACE_NOT_DETECTED","name":"Face not detected","description":"No face was detected in the camera frame."}`
`NETWORK_ERROR``Network error`A network issue prevented the process from completing.`{"code":"NETWORK_ERROR","name":"Network error","description":"A network issue prevented the process from completing."}`
`SDK_ERROR``SDK error`An internal SDK error occurred during the process.`{"code":"SDK_ERROR","name":"SDK error","description":"An internal SDK error occurred during the process."}`
`USER_CANCELED``User canceled`The user canceled the process before completion.`{"code":"USER_CANCELED","name":"User canceled","description":"The user canceled the process before completion."}`
***Example:*** *As an example response, the JSON below represents a **rejected transaction (Status 2)**. The **`reason`** field may come as an **object**, including the **rejection reason details** and its **description**. It also includes identifiers such as **`uidDevice`** and **`keyProcessLiveness`**, plus **`processId`** (the unique process UID). Evidence (e.g., an image) can be returned as **Base64**, including the **encoding type**.* ``` { "processType": "liveness", "statusCode": 2, "detail": { "status": "rejected", "reason": { "name": "SPOOFING", "description": "The liveness check indicates the subject is not alive." }, "uidDevice": "1da62007d8974a9fa71e18cba76f6fc1", "keyProcessLiveness": "69c265aeca9d4863b61b1fc6a8099f52", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12", "image": { "encoding": "base64", "mimeType": "image/jpeg", "data": "" } } } ``` ***CardCapture***
Status (code)Nombre (name)Descripción (description)Objeto (reason)
`NONE``NOT_ALERT`The transaction was approved with no alerts detected.`{"code":"NONE","name":"NOT_ALERT","description":"The transaction was approved with no alerts detected."}`
`PERMISSION_DENIED``Camera permission denied`Camera access was denied by the user or the operating system.`{"code":"PERMISSION_DENIED","name":"Camera permission denied","description":"Camera access was denied by the user or the operating system."}`
`CAMERA_NOT_FOUND``Camera not found`No camera was detected on the device, or it is unavailable.`{"code":"CAMERA_NOT_FOUND","name":"Camera not found","description":"No camera was detected on the device, or it is unavailable."}`
`CAMERA_IN_USE``Camera in use`The camera is currently being used by another application.`{"code":"CAMERA_IN_USE","name":"Camera in use","description":"The camera is currently being used by another application."}`
`NOT_SUPPORTED``Device not supported`The device does not meet the requirements for this capture process.`{"code":"NOT_SUPPORTED","name":"Device not supported","description":"The device does not meet the requirements for this capture process."}`
`DOCUMENT_NOT_DETECTED``Document not detected`No document was detected in the camera frame.`{"code":"DOCUMENT_NOT_DETECTED","name":"Document not detected","description":"No document was detected in the camera frame."}`
`NETWORK_ERROR``Network error`A network issue prevented the process from completing.`{"code":"NETWORK_ERROR","name":"Network error","description":"A network issue prevented the process from completing."}`
`SDK_ERROR``SDK error`An internal SDK error occurred during the process.`{"code":"SDK_ERROR","name":"SDK error","description":"An internal SDK error occurred during the process."}`
`USER_CANCELED``User canceled`The user canceled the process before completion.`{"code":"USER_CANCELED","name":"User canceled","description":"The user canceled the process before completion."}`
`FOCUS_LOST``Focus lost / component interrupted`The process was interrupted because the app lost focus or the component was closed, minimized, or moved to the background.`{"code":"FOCUS_LOST","name":"Focus lost / component interrupted","description":"The process was interrupted because the app lost focus or the component was closed, minimized, or moved to the background."}`
**Example**: For the **document capture** process, it will be mapped under **`processType: "cardCapture"`** and will use **`statusCode: 3`**, which groups any **cancellation scenario** that affects the execution of the flow, for example: - **Process cancelled by the user.** - **Component focus loss during the session** (e.g., the app goes to the background or the user navigates to another screen). The response will include the **`reason`** (cancellation reason) and **`status`** (state), as well as the **`processId`** (unique process identifier) and its **linked ID** (if applicable). Additionally, the **`imageDetail`** object will be returned, where the result of the processed image will be provided. ``` { "processType": "cardcapture", "side":"front", "statusCode": 3, "detail": { "status": "failed", "reason": { "name": "USER_CANCELED", "description": "The user canceled the process before completion." }, "uidDevice": "1da62007d8974a9fa71e18cba76f6fc1", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12", "image": { "encoding": "base64", "mimeType": "image/jpeg", "data": "" } } } ``` This process will trigger an **event to the webhook**, where a record will be **registered** and linked by a **UID** (for example, `processId` as the unique process identifier). The relationship between the **transaction** and the **webhook event** will be kept for traceability.

The payload sent will follow the structure below. This response **only applies to the webhook** when `reasonCode` is one of the following values: **`SPOOFING`**, **`PAD`**, **`CLOSED_EYES`**, **`NOT_ALIVE`**.

```json { "transactionId": "10743", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12", "transactionStatus": "rejected", "stages": [ { "processType": "liveness", "status": “Spoofing”, "reason": { "name": "SPOOFING", "description": "A potential spoofing attempt was detected during the liveness process." }, "uidDevice": "1da62007d8974a9fa71e18cba76f6fc1", "keyProcessLiveness": "69c265aeca9d4863b61b1fc6a8099f52", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12" } ] } ``` [webhook-risk-validation.yaml](https://docs.ado-tech.com/attachments/1)