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>"
    }
  }
}

 

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:

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

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.

{
    "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"
        }
    ]
}

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:

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