SDK Response

Purpose Of This Page

Explains the structure of the SDK JSON payload, what each field means, and which values to extract before making backend API calls.

Step 1 - Parse the SDK Response

When the KYC SDK finishes on the mobile device, it delivers a single JSON payload to the host app. Your app must forward this to your backend. This payload contains all the identifiers you need to call VIDA's backend APIs.

Response Structure

{
  "verificationId"                ← Master ID for this KYC session
  "failedOperation"               ← Which operation failed; null on success

  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId"             ← Pass to GET /api/v2/transaction?transactionId=UUID
      "partnerTrxId"              ← Your own reference for this operation
      "groupId"                   ← Same as verificationId
      "card"                      ← Document country and type
      "ocrResult"                 ← Extracted text (name, ID number, DOB...)
      "idVerificationResult"      ← Spoofing, landmark, forgery scores
      "imageQualityResult"        ← Blur and low-light scores
      "warnings"                  ← Non-blocking alerts (e.g. occlusion)
      "duplicateCheckResult"      ← Matches against previous submissions
      "attemptedTransactionIds"   ← All attempt IDs for this operation
    },
    "backCardVerificationDetails": { ... }   ← Same structure as front
  },

  "faceMatchDetails": {
    "transactionId"               ← Pass to GET /api/v2/transaction?transactionId=UUID
    "partnerTrxId"                ← Your own reference for this operation
    "groupId"                     ← Same as verificationId
    "imageFaceMatchVerificationResult"
    "attemptedTransactionIds"
  },

  "livenessDetails": {
    "transactionId"               ← Use with Liveness Service API ONLY
    "sessionId"                   ← Same as verificationId
    "livenessScore"
    "manipulationScore"
    "imageData"                   ← Selfie image, base64
    "attemptedTransactionIds"
  }
}

Fields are erased when they do not apply. For example, warnings only appears when there is something to report, and backCardVerificationDetails is absent for single-sided documents.

Understanding the Identifiers

The response contains four different IDs.

ID	Scope	Use it for
verificationId	The whole KYC session	All session-level backend calls. This is your main identifier.
groupId	The whole KYC session	Same value as verificationId. Returned inside each operation for convenience.
sessionId	The whole KYC session	Same value as verificationId. Returned inside livenessDetails.
transactionId	One operation	Fetching the result of that one operation from VIDA.
partnerTrxId	One operation	Your own tracing and reconciliation. Not used to call VIDA APIs.

What to Extract and Store

Field	Where to Find It	Used For
verificationId	Top level	All backend API calls ( GET/api/v2/verify/status?verificationId=UUID)
failedOperation	Top level	Identifies which operation triggered onError. When this field is NOT null, the SDK session is considered terminal for this verificationId - no further retries or resume are possible. Use this as your primary signal for real-time failure detection. There is no need to poll the GET KYC Status API for failure cases; the API may continue to show IN_PROGRESS until the backend timeout expires. Null when the flow succeeded.
partnerTrxId	Per operation	Your own reference for tracing a single operation or attempt. Not returned at top level - use verificationId for session-level API calls.
frontCardVerificationDetails.transactionId	idCardVerificationDetails	GET /api/v2/transaction?transactionId=UUID - OCR/IDV front
backCardVerificationDetails.transactionId	idCardVerificationDetails	GET /api/v2/transaction?transactionId=UUID - OCR/IDV back
faceMatchDetails.transactionId	Top level	GET /api/v2/transaction?transactionId=UUID - Face Match
livenessDetails.transactionId	Top level	Liveness Service GET transaction (NOT My-Verify)
warnings[].code	Per card side	Alert logging - non-blocking.

Portrait image in ocrResult vs. documents API

The portraitImage field inside ocrResult is populated on-device by the SDK only - it is not returned in API responses.

The actual portrait image (extracted from the ID card) is available via GET /api/v2/transaction/{transactionId}?includeDocuments=true as a presigned URL in documents.portrait. See the Transaction Details API page for details.

Using SDK Response for KYC Decision-Making

The SDK callback response is your primary signal for real-time decision-making:

Success callback (failedOperation is null):

• The SDK flow completed successfully.

• Call GET /api/v2/verify/status?verificationId=UUID to confirm the VERIFIED status.

• The API should return overallStatus: VERIFIED.

Error callback (failedOperation is NOT null):

• The SDK session is terminal for this verificationId.

• You may treat this as a failed verification immediately.

• There is no need to wait for the GET KYC Status API to update.

• The IN_PROGRESS status on this verificationId will auto-expire to FAILED after the configured timeout, but you should not wait for this transition to make your decision.

partnerTrxId in detail

It is per operation, not per session.

verificationId is the ID for the whole KYC session. partnerTrxId is the ID for one operation inside that session.

You will find partnerTrxId in three places:

• frontCardVerificationDetails

• backCardVerificationDetails

• faceMatchDetails

It is not returned in livenessDetails.

How the value is created

The VIDA API does not accept the same partner transaction ID twice. Every operation must therefore receive a different value. How that value is built depends on whether you send one.

If you send partnerTransactionId when you start the SDK

The SDK uses your value as the base and adds a suffix (extra text added to the end of something. So id_f_1 added to the end of your value) for the operation and the attempt. There is no separator between your value and the suffix.

Operation	Suffix	Example
ID card front	id_f_1	YOUR-REF-001id_f_1
ID card back	id_b_1	YOUR-REF-001id_b_1
Face match	fm_0	YOUR-REF-001fm_0

The value in the response is not the same as the value you sent. Do not match on it directly. Store your base value on your side when you start the flow, or strip the suffix before matching.

If you do not send partnerTransactionId

The SDK generates a UUID for each operation, because the field is required by the VIDA API and can never be empty. In this case the three values are separate, unrelated UUIDs. They do not share a base and they have no suffix, so you cannot use them to group a session.

How to set it

Set partnerTransactionId when you build the SDK request.

How to use it

• To find all data for one session, use verificationId.

• To find one operation or one attempt, use partnerTrxId together with attemptedTransactionIds.

clientTransactionId is not an SDK Response field

clientTransactionId is a query parameter for the ID Fraud Shield (IDFS) GET API. It does not appear in the SDK response. When you call the IDFS API, use one of these values from the SDK response as your clientTransactionId:

SDK	Use this value
KYC SDK	groupId or verificationId
Liveness SDK	sessionId, partnerTrxId, or verificationId

Understanding Scores

Each OCR field, verification check, and image quality check includes a score and a threshold. Use the table below to determine what constitutes a passing result.

Check Type	Field	Passes When
OCR extraction	name, idNumber, dob, address, etc.	score >= threshold (confidence in extracted value)
Anti-spoofing	spoofingResult.recapScore, colorPrint, etc.	score < threshold (lower = less spoof-like)
Forgery detection	forgeryResult.summary	score < threshold (lower = less forgery-like)
Image quality	imageQualityResult.blurriness, lowLight	score < threshold (lower = better quality)
Landmark detection	landmarkResult.containerResult items	score > 0 (0 = not detected / occluded)

Sample SDK Responses

Sample 1 - partnerTransactionId passed (Malaysia MyKas)

The partner sent "Transaction ID". Note the suffix on each partnerTrxId, and the two failed liveness attempts.

Sample Response

{
  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "card": {
        "country": "MALAYSIA",
        "type": "MyKas",
        "isoAlpha3CountryCode": "MYS",
        "isoAlpha2CountryCode": "MY"
      },
      "ocrResult": {
        "front": {
          "data": {
            "portraitImage": "/9j/4AAQSkZJRgABAQAA",
            "idNumber": { "value": "960124-12-0015", "score": 0.998675, "threshold": 0.95 },
            "name": { "value": "SAGAR CHANDRAKANT", "score": 0.993971, "threshold": 0.95 },
            "dob": { "value": "19960124", "score": 0.998675, "threshold": 0.95 },
            "gender": { "value": "M", "score": 1, "threshold": 0.95 },
            "dateOfExpiry": { "value": "Tarikh Luput 06 Jun 2027", "score": 0.979896, "threshold": 0.95 },
            "citizenship": { "value": "BUKAN WARGANEGARA", "score": 1, "threshold": 0.95 },
            "address": { "value": "KAMPUNG TERUSAN BARU 90002 SEMPORNA SABAH", "score": 0.99412, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "front": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.102359, "threshold": 0.95 },
            "blackWhite": { "score": 0.005039, "threshold": 0.95 },
            "colorPrint": { "score": 0.450691, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "malaysia_flag", "score": 0.9984 },
              { "name": "card_logo", "score": 0.9975 },
              { "name": "chip", "score": 0.9967 },
              { "name": "portrait", "score": 0.9966 },
              { "name": "id_number", "score": 0.9954 },
              { "name": "kad_pengenalan_header", "score": 0.9911 },
              { "name": "name", "score": 0.9894 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "front": {
          "blurriness": { "score": 0.000751, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["325d8923-8d99-4800-8c43-04faccd4d28e"]
      }
    },
    "backCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "ocrResult": {
        "back": {
          "data": {
            "extendedIdNumber": { "value": "960124-12-0015-01", "score": 0.999561, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "back": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.108842, "threshold": 0.95 },
            "blackWhite": { "score": 0.024161, "threshold": 0.95 },
            "colorPrint": { "score": 0.297198, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "my_logo", "score": 0.9933 },
              { "name": "coat_of_arm", "score": 0.9923 },
              { "name": "id_number", "score": 0.9835 },
              { "name": "state_registrar", "score": 0.9532 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "back": {
          "blurriness": { "score": 0.000034, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["5fad1038-f06a-47a0-9001-ef85f2ea084e"]
      }
    }
  },
  "faceMatchDetails": {
    "transactionId": "Transaction ID",
    "partnerTrxId": "Partner Trx ID",
    "groupId": "Group ID",
    "imageFaceMatchVerificationResult": {
      "data": {
        "code": 1042,
        "message": "Selfie photo matches with reference photo",
        "score": 0.940716
      }
    },
    "attemptedTransactionIds": {
      "success": ["1b80c9aa-2e0e-4a40-8d78-24927ff28ef4"]
    }
  },
  "livenessDetails": {
    "imageData": "/9j/4QCRRXhpZgAATU0A",
    "livenessScore": 0.5151107,
    "manipulationScore": 0.14462223,
    "transactionId": "Transaction ID",
    "sessionId": "Session ID",
    "attemptedTransactionIds": {
      "failed": [
        "abf7a355-feb1-459b-8be5-d429b00146bd",
        "ef1be206-5722-4cf0-af6b-0ac132a7fd61"
      ],
      "success": ["9a78a609-d18a-4063-b908-c4b28daef22b"]
    }
  },
  "verificationId": "Verification ID"
}

Sample 2 - partnerTransactionId not passed (Malaysia MyKas)

The partner sent nothing, so the SDK generated a UUID for each operation. The three partnerTrxId values are unrelated to each other. This sample also shows a warning on the back card.

Sample Response

{
  "idCardVerificationDetails": {
    "frontCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "card": {
        "country": "MALAYSIA",
        "type": "MyKas",
        "isoAlpha3CountryCode": "MYS",
        "isoAlpha2CountryCode": "MY"
      },
      "ocrResult": {
        "front": {
          "data": {
            "portraitImage": "/9j/4AAQSkZJRgABAQAA",
            "idNumber": { "value": "960124-12-0015", "score": 0.981462, "threshold": 0.95 },
            "name": { "value": "SAGAR CHANDRAKANT", "score": 0.990929, "threshold": 0.95 },
            "dob": { "value": "19960124", "score": 0.981462, "threshold": 0.95 },
            "gender": { "value": "M", "score": 1, "threshold": 0.95 },
            "dateOfExpiry": { "value": "Tarikh Luput 06 Jun 2027", "score": 0.977433, "threshold": 0.95 },
            "citizenship": { "value": "BUKAN WARGANEGARA", "score": 1, "threshold": 0.95 },
            "address": { "value": "KAMPUNG TERUSAN BARU 80002 SEMPORNA SABAH", "score": 0.997653, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "front": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.207713, "threshold": 0.95 },
            "blackWhite": { "score": 0.004726, "threshold": 0.95 },
            "colorPrint": { "score": 0.105061, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "card_logo", "score": 0.9967 },
              { "name": "id_number", "score": 0.9952 },
              { "name": "portrait", "score": 0.9948 },
              { "name": "chip", "score": 0.9947 },
              { "name": "malaysia_flag", "score": 0.9945 },
              { "name": "kad_pengenalan_header", "score": 0.9908 },
              { "name": "name", "score": 0.9907 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "front": {
          "blurriness": { "score": 0.001599, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["9a6738d1-75f3-41db-a66f-e65ce59ce886"]
      }
    },
    "backCardVerificationDetails": {
      "transactionId": "Transaction ID",
      "partnerTrxId": "Partner Trx ID",
      "groupId": "Group ID",
      "warnings": [
        {
          "message": "Image has Occlusion, please check [state_registrar] from landmarkResult for more details",
          "code": 10429,
          "operations": ["idVerification"]
        }
      ],
      "ocrResult": {
        "back": {
          "data": {
            "extendedIdNumber": { "value": "960124-12-0015-01", "score": 0.999633, "threshold": 0.95 }
          }
        }
      },
      "idVerificationResult": {
        "back": {
          "spoofingResult": {
            "message": "Success",
            "code": 5000,
            "recapScore": { "score": 0.099637, "threshold": 0.95 },
            "blackWhite": { "score": 0.012981, "threshold": 0.95 },
            "colorPrint": { "score": 0.380484, "threshold": 0.95 }
          },
          "landmarkResult": {
            "message": "Success",
            "code": 5000,
            "containerResult": [
              { "name": "coat_of_arm", "score": 0.9948 },
              { "name": "my_logo", "score": 0.9945 },
              { "name": "id_number", "score": 0.9846 },
              { "name": "state_registrar", "score": 0 }
            ]
          }
        }
      },
      "imageQualityResult": {
        "back": {
          "blurriness": { "score": 0.000005, "threshold": 0.95 },
          "lowLight": { "score": 0, "threshold": 0.95 }
        }
      },
      "duplicateCheckResult": { "docReferences": [], "idNumberReferences": [] },
      "attemptedTransactionIds": {
        "success": ["a70b08e3-ba71-4098-b756-e6aebd38dc44"]
      }
    }
  },
  "faceMatchDetails": {
    "transactionId": "Transaction ID",
    "partnerTrxId": "Partner Trx ID",
    "groupId": "Group ID",
    "imageFaceMatchVerificationResult": {
      "data": {
        "code": 1042,
        "message": "Selfie photo matches with reference photo",
        "score": 0.914764
      }
    },
    "attemptedTransactionIds": {
      "success": ["8e155d7f-1b14-44ad-9a60-730124dc6c21"]
    }
  },
  "livenessDetails": {
    "imageData": "/9j/4QCRRXhpZgAATU0A",
    "livenessScore": 0.48649344,
    "manipulationScore": 0.08861544,
    "transactionId": "7294b7f7-296e-41ce-81d2-e64729dfe782",
    "sessionId": "75b7ee88-6e49-32f3-95f2-da04ca2670c7",
    "attemptedTransactionIds": {
      "success": ["7294b7f7-296e-41ce-81d2-e64729dfe782"]
    }
  },
  "verificationId": "Verification ID"
}