Modular Onboarding¶
Happy Path¶
1. Previous steps to the ID proofing process
Terms acceptance (data treatment), Validate user contact details: email and/or telephone (useful as a reference for contacting customers and as a way to control and limit the number of attempts from a customer) Security Measures:
- Avoid DDoS using: Tokenized URLs & Captchas
- Rate limit to block multiple requests from the same IP
Process description and user recommendations If HTML, check that the browser used is supported by Veridas. If it's not supported, advise the user to use a compatible one.(providing a list of them)
Be sure you are using Latest versions of SDKs.
2. Get info about available countries document types, geographical_area and required_document_sides
GET /available-types (filter_key=filter_value1,filter_value2) (set Version=2 in filter options)
3. Issuing country and document type selection
If applicable in your use case, that is:
- Accepting documents from different issuing countries and/or
- Accepting different document types
4. if HTML desktop, Redirect to mobile. Build a QR functionality (recommended).
The quality of cameras in desktop devices is lower than mobile ones. As a result, the quality of the images captured are worse, and the performance of our solution too. Additionally, some of the anti-fraud verifications that Veridas performs are not available for desktop captures. Redirecting desktop users to mobile would be the best option to ensure an optimal performance.
5. Start Document SDK (android, iOS, HTML)
- Launch the SDK in full screen mode (recommended)
- Make use of auto classification when applicable.
- "showdocument" (for IOS), "SHOW_DOCUMENT" (for Android) and "documentReviewImageActive" (for HTML) to "YES" recommended
- Keep "SECONDS_WITHOUT_SHUTTER_BUTTON_[obverse|reverse]" (for Android), "secondswithoutshutterbutton[obverse|reverse]" and "manualCaptureButtonDelay" (Html) with the default time value for manual capture trigger.
6. Once the Obverse has been captured, SDK delegates image's captures to the customer's middleware.
7.Start validation
- POST /validation (Returns: validationID. Recommended: store it.Don't reuse it!)
8. Add important additional information to the validation:
- if previous PUT has returned a 2xx (not parallelize) PUT /contextual_data a (stats_userid: "anonymous_value", stats_usecase: "usecase_value", stats_tenant: "anonymous_value")
9. Send the obverse:
- if previous PUT returned a 2xx (not parallelize) PUT /document (analysisType: obverse, serviceMode: validation/OCR, documentType: check_documentation)
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
10.SDK delegates images capture (reverse)
11. Send the reverse:
- if the previous PUT returned 2xx (not parallelize). PUT /document (analysisType: reverse)
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
12. (Recommended requests) Get validation data (OCR and scores):
- if the previous PUT returned 2xx (not parallelize). GET /validation
13. Get the challenge token for selfie alive pro with number of movements (length)
- if previous PUT returned 2xx (not parallelize). PUT /challenges/generation (by default length=2, recommended keeping this value for standard security)
- A token is returned, you will have to use it to start SAP SDK
14. Start SAP SDK (android, iOS, HTML)
- "livephoto" key (for native ) to "YES" and "aliveChallenge" when initializing the SDK (in HTML)
- "jws_token" (for IOS) or "jwstoken" (for Android) with a challenge token obtained from the previous call to API
- "showtutorial" (for native) to "YES" recommended or "selfieInstructionsActive" to true (for HTML)
15. If the user repeats the SAP process, a new challenge token must be requested to API
- PUT /challenges/generation (by default, length=2, recommended keeping this value)
- A token is returned, you will have to use it to update the required challenge with the public method: "VDPhotoSelfieCapture.updateChallenge" (in Android),"VDPhotoSelfieCapture.setChallenge" (in IOS), "VDSelfie.restartChallenge" (in HTML)
17.SDK delegates images captured
- Selfie , Video and webVTT files
18. Send the selfie alive pro:
- if the previous PUT returned 2xx (not parallelize).
PUT /challenges/video-photo (selfie, video, annotations and challenge token)
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
19. Start Video SDK (android, iOS, HTML)
- "showtutorial" (native) or "sdkVideo.views.instructions.active" (HTML) to "YES" (Recommended)
20. SDK delegates images capture (Video)
21. Send the video:
- if the previous PUT returned 2xx (not parallelize). PUT /validation/{validation_id}/video
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
22. Get validation data (OCR and scores): GET /validation
23. Add important additional information (optional - if new information to be sent depends on score results)
-
if the previous PUT has returned a 2xx (not parallelize) PUT /contextual_data:
- stats_userid:"anonymous_value"
- stats_usecase: "usecase_value"
- stats_tenant: "anonymous_value"
- stats_onboarding_state:"approved, rejected.."
24. Confirm validation. PUT /confirmation
25. If boi-das is not included: Get validation evidences. (obverse, reverse, cuts, selfie, selfie-Alive, video...) Including those that have been canceled, abandoned by the user or throw a 4xx error (for troubleshooting purposes). Remember that Veridas does not keep them.
26. If boi-das is included: Polling from boi-das will download all the confirmed validations and delete them. This step can replace step 25.
27. Define your business rules to accept, reject o review validations.
Alternative Path¶
0. For any call to Validas API (points 7,8,9,11,12,13,15,18,21,22,23,24,25):
- If API returns a 5xx error, the middleware should retray the call again after a few seconds.
9. Obverse error:
- PUT /document (analysisType: obverse, serviceMode: validation/OCR, documentType: check_documentation)
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
- if API returns 4xx then:
- Store the captures and validation information (for troubleshooting purposes) Cancel and Delete the validation.
- Let the user repeat up to a limited number of attempts, for instance three, starting a new process (Go to Step 4) and reminding again the recommendations.
- After the last try, provide the user an alternative method.
11. Reverse error:
- PUT /document (analysisType: reverse)
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
- if API returns 4xx then:
- Store the captures and validation information (for troubleshooting purposes) Cancel and Delete the validation.
- Let the user repeat up to a limited number of attempts, for instance three,, resuming the process (Step 4) and reminding again the recommendations.
- After the last try, provide the user an alternative method.
12. Low document scores (Score-DocumentGlobal value or ValidationGlobalScore value is below recommended threshold ):
- Store the captures and validation information (for troubleshooting purposes) Cancel and Delete the validation.
- Let the user repeat up a limited number of attempts, for instance three, starting a new process (Step 4) and reminding again the recommendations.
- After the last try, provide the user an alternative method.
18. Selfie Alive Pro error:
- PUT /challenges/video-photo
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
- if API returns 4xx then:
- Let the user repeat up a limited number of attempts, for instance three, resuming the process (Step 13) and reminding again the recommendations.
- After the last try, store the captures and validation information (for troubleshooting purposes), Cancel and Delete the validation and provide the user an alternative method.
21. Video error:
- PUT /validation/{validation_id}/video
- Once the capture has been processed by Veridas, several seconds later, you will get a response.
- if API returns 4xx then:
- Let the user repeat up to a limited number of attempts, for instance three, resuming the process (Step 19) and reminding again the recommendations.
- After the last try, store the captures and validation information (for troubleshooting purposes), Cancel and Delete the validation and provide the user an alternative method.
22. Final check. Validation scores below threshold:
- if ValidationGlobalScore value is below recommended threshold, check particular scores according to your use case.
- if Score-DocumentGlobal value is below recommended threshold:
- Cancel, store the captures and validation information (for troubleshooting purposes) and Delete validation.
- Let the user repeat up to a limited number of attempts, for instance three, starting a new process (Step 4) and reminding again therecommendations.
- After the last try, store the captures and validation information (for troubleshooting purposes), Cancel and Delete the validation and provide the user an alternative method.
- if any of ValidasScoreSelfie or ValidasScoreLifeProof value is below recommended threshold:.
- Let the user repeat up to a limited number of attempts, for instance three, starting a new process (Step 12) and reminding again the recommendations.
- After the last try, store the captures and validation information (for troubleshooting purposes), Cancel and Delete the validation and provide the user an alternative method.
- if ValidasScoreVideo value is below recommended threshold:.
- Let the user repeat up to a limited number of attempts, for instance three, starting a new process (Step 18) and reminding again the recommendations.
- After the last try, store the captures and validation information (for troubleshooting purposes), Cancel and Delete the validation and provide the user an alternative method.
(Only applicable if SDKs are used) if Validas ScoreIntegrity is different to 1 , consider that the images sent to validas could have been modified. An agent should review them.
Remember that the images given by SDKS must not be modified to be sent to our cloud, otherwise this score will be 0.
Other alternative paths (Cancellations or abandons)¶
a) If the process is explicitly cancelled by the end user the middleware must:
- Cancel the validation PUT /validation/{id}/cancellation
- Delete the validation DELETE /validation/{id}
b) If the process is not explicitly cancelled by the end user (time out, abandons...), the middleware must:
- Cancel the validation PUT /validation/{id}/cancellation
- Delete the validation DELETE /validation/{id}
c) If the user abandons the journey in a step after the validation process, there is a rescue process in place which offers the user to resume it from the point where it was left instead of starting over and repeating the validation process
Autoclassification¶
-
In native, it is necessary to give to the SDK an array with a list of specific document types (all the documents in this array must belong to the same country). The format for the elements in the array is similar to the field "id" obtained in GET /available-types (Version=2) (point 2 in previous diagram) call. For instance, for spanish ID documents this array can include:"ES_ResidencePermit_2010", "ES_ResidencePermit_2011", "ES_ResidencePermit_2020", "ES_IDCard_2006", "ES_IDCard_2015" and "ES_IDCard_2021"
- If the SDK is able to auto classify the document, it will return an array with a single value. This single value is the specific type to be sent in the "Document Type" parameter in PUT /Document call to the API (point 9 in diagram)
- If the SDK cannot auto classify the document (for example, when doing a manual capture with the button), it will return an array with more than one value. In this case, the string to be sent in the "Document type" parameter in PUT /Document call must be the one of the field "group_id" obtained in the response to GET /available-types (Version=2) (point 2 in previous diagram) in order to indicate to the API to do the auto classification of the document by Veridas cloud. For instance, for the spanish ID documents, you can send "ES2_ID" so that our cloud will try to auto classify the document among all the ID documents supported for Spain.
See list of documents with auto classification in the SDK for android and iOS.
- In HTML, it is necessary to give to the SDK a string with the "group_id" format according to GET /available-types (Version=2). For instance "ES2_ID" for the spanish ID documents. The value returned by the SDK is the one to be sent in the "Document type" parameter in PUT /Document call.
See list of documents with auto classification for html.
User Recommendations¶
- Describe the process that the user is going to complete. It’s a one single time process that the user must understand in order to do it correctly.
- This process makes use of a camera, ensure the user knows it and provide access to it when requested.
- The light conditions should be good enough, recommended indoor places and no brightness.
- Recommend the use of mobile devices over desktop. Redirect to mobile if possible.
- If the process is in HTML, make sure that the user is using a compatible browser, and advise him which ones are.
- Ensure the document is ready to be used in the process.
- The document used must be a valid one for the process. Displaying a list of valid documents for the process could help (specimens can be found here)
- The document used must be the original, no copies allowed. (General recommendation, maybe for particular situations can be allowed)
- The document used must be owned by the person doing the process.
- The document should not be expired and the person above the age required for the process. (General recommendation, maybe for particular situations can be different)
- When doing the face capture, verify that there is only one person behind the camera.
- When doing the selfie capture, verify that there are no objects covering the face.
Integration Review¶
The below document summarizes general recommendations/improvements, mandatory checks and several weak points an integration may have, so we strongly suggest paying special attention to them before moving forward as not doing so might cause issues in production.
Veridas Integration Review Document: Download