/validation/

POST https://shadowfax.zemris.fer.hr/validation/

Validation method is designed to be used in real-time to validate or invalidate credit card images before submitting them to extraction.

Validation procedure requires a fresh access token, check out our authenticate section.

The validation procedure checks image quality in multiple steps:

• By checking image blurriness
• By checking image resolution
• By checking image position relative to the camera (if it is centered and sufficiently close to the camera)
• By checking foreground-to-background contrast
• By checking perspective distortion (if the card is captured at a strong angle)

All image quality parameters should be checked before the card image is sent to extraction to maximize performance. A pseudo-code representation of the validation loop is as follows:

Pseudocode

var image

do while image not validated 3 times in a row

	image <- capture image from video stream
	x, y <- image.shape()
	resizing_coef <- max(x, y) / 384
	xx, yy <- x / resizing_coef, y / resizing_coef
	
	resized_image <- image.resize(xx, yy)

	check_validity(resized_image)
		
end

results <- do_extraction(image) 

Card images should be resized to a smaller size before validation. This reduces network traffic and improves validation performance. In most cases, reduced-resolution images are sufficient to determine if the original image is suitable for extraction.
Note: While image resizing is still recommended, credit card validation supports the optional setting SkipImageSizeCheck: true.

Request format

Validation is a POST method that requires a JSON body in the following format:

JSON

{
  "AcceptTermsAndConditions": true,
  "DataFields": {
    "Images": ["<Base64-encoded-resized-card-image>"],
    "BlurValues": [<BV1>, <BV2>, ...]
  },
  "Settings": {
    "SkipImageSizeCheck": true
  }
}

Response format

Service responds in a JSON format in the following manner for a response status 200:

JSON

{
  "TransactionID": "<TRANSACTION-UUID>",
  "UploadedAt": "<TIMESTAMP>",
  "ProductName": "Scan App v<VERSION>",
  "Errors":["<ERROR1>", ...],
  "Warnings":["<WARNING1>", ...],
  "Status": <STATUS-CODE>,
  "Method": "Validation",
  "InfoCode": <INFO-CODE>,
  "Keypoints": [
    [<KEYPOINT1-x>, <KEYPOINT1-y>],
    [<KEYPOINT2-x>, <KEYPOINT2-y>],
    [<KEYPOINT3-x>, <KEYPOINT3-y>],
    [<KEYPOINT4-x>, <KEYPOINT4-y>]
  ],
  "DetectedBlurValue": <BV>,
  "Validated": <true/false>,
  "Index": <IMG-INDEX>,
  "AnalysisTime": "<REQUEST-TIMING-IN-MS> ms"
}

Response keys in order are (bolded are important keys):

• TransactionID - UUID describing a transaction
• UploadedAt - timestamp of the transaction in the following format (iso format) - %Y-%m-%dT%H:%M:%S.%f
• ProductName - ScanApp version
• Errors - list of errors describing if some error occured (this is usually empty)
• Warnings - list of warnings if a warning occurred (this is usually empty)
• Status - response status code
• Method - Validation - constant
• InfoCode - see Validation info codes
• Keypoints - list of four float x, y coordinates in the range (0, 1) that point out four document corners (if detected) which you can use to create an animation where the system detects the document - keypoints are in the following order:
  1. top left
  2. top right
  3. bottom right
  4. bottom left
• Validated - if the image was successfully validated
• Index - if multiple images were submitted to the validation endpoint, returns the index of the best fit image (this can be ignored if you submit only a single image)
• AnalysisTime - request processing time in ms