SDK response update 3.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.

{
  "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": "<BASE64>"
    }
  }
}

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

{
 
  "NONE": {
 
    "name": "NOT_ALERT",
 
    "description": "The transaction was approved with no alerts detected."
 
  },
 
  "NOT_ALIVE": {
 
    "name": "Not alive detected",
 
    "description": "The liveness check indicates the subject is not alive."
 
  },
 
  "CLOSED_EYES": {
 
    "name": "Eyes closed detected",
 
    "description": "The subject's eyes were detected as closed during the capture."
 
  },
 
  "SPOOFING": {
 
    "name": "Spoofing detected",
 
    "description": "A potential spoofing attempt was detected during the liveness process."
 
  },
 
  "PAD": {
 
    "name": "Presentation attack detected (PAD)",
 
    "description": "A potential presentation attack was detected (PAD confidence triggered)."
 
  },
 
  "PERMISSION_DENIED": {
 
    "name": "Camera permission denied",
 
    "description": "Camera access was denied by the user or the operating system."
 
  },
 
  "CAMERA_NOT_FOUND": {
 
    "name": "Camera not found",
 
    "description": "No camera was detected on the device, or it is unavailable."
 
  },
 
  "FACE_NOT_DETECTED": {
 
    "name": "Face not detected",
 
    "description": "No face was detected in the camera frame."
 
  },
 
  "NETWORK_ERROR": {
 
    "name": "Network error",
 
    "description": "A network issue prevented the process from completing."
 
  },
 
  "SDK_ERROR": {
 
    "name": "SDK error",
 
    "description": "An internal SDK error occurred during the process."
 
  },
 
  "USER_CANCELED": {
 
    "name": "User canceled",
 
    "description": "The user canceled the process before completion."
 
  },
 
  "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

{ "processType": "liveness", "statusCode": 2, "detail": { "status": "approved", "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": "<BASE64>" } } }

CardCapture

{ "NONE": { "name": "NOT_ALERT", "description": "The transaction was approved with no alerts detected." }, "PERMISSION_DENIED": { "name": "Camera permission denied", "description": "Camera access was denied by the user or the operating system." }, "CAMERA_NOT_FOUND": { "name": "Camera not found", "description": "No camera was detected on the device, or it is unavailable." }, "CAMERA_IN_USE": { "name": "Camera in use", "description": "The camera is currently being used by another application." }, "NOT_SUPPORTED": { "name": "Device not supported", "description": "The device does not meet the requirements for this capture process." }, "DOCUMENT_NOT_DETECTED": { "name": "Document not detected", "description": "No document was detected in the camera frame." }, "NETWORK_ERROR": { "name": "Network error", "description": "A network issue prevented the process from completing." }, "SDK_ERROR": { "name": "SDK error", "description": "An internal SDK error occurred during the process." }, "USER_CANCELED": { "name": "User canceled", "description": "The user canceled the process before completion." }, "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:

{ "processType": "cardcapture", "statusCode": 3, "detail": { "status": "approved", "reason": { "name": "USER_CANCELED", "description": "The user canceled the process before completion." }, "uidDevice": "1da62007d8974a9fa71e18cba76f6fc1", "keyProcessLiveness": "69c265aeca9d4863b61b1fc6a8099f52", "processId": "3f2b9c1e-7a4d-4f2a-9c0c-6c4c2e9b8d12", "image": { "encoding": "base64", "mimeType": "image/jpeg", "data": "<BASE64>" } } }