Skip to content
Last updated

This guide describes how to implement AutoIdent via IDnow for completing the Re-Know Your Customer (Re-KYC) process in your solution

Introduction

User journey

Below are the steps involved in performing customer KYC using AutoIdent via IDnow:

  1. You initiate the identification request with Solaris, and Solaris forwards the customer data to IDnow.
  2. Customer will be redirected to IDnow to complete the identification process via the IDnow SDK. Note the list of accepted documents by IDnow here.
  3. IDnow will prompt the customer to begin an AutoIdent session (either in English or in German). The customer must provide the government-issued identification document (e.g., Passport, ID-card, Driver's license)
  4. During the AutoIdent session, the following steps will occur:
    • Customer will provide the necessary details to start the identification process.
    • Customer will scan the ID document and take a liveness check.
  5. Once the process completes, the customer will be redirected to your frontend.

Eligibility

This identification method is available for customers residing in Germany. It cannot be used for first-time identification but is valid for re-KYC processes and specific authentication use cases, rather than full identification. For further details and guidance on its applicability, please consult your Partner Manager.

IDnow integration

In addition to the Solaris technical prerequisites, you must also integrate IDnow into your solution. You can achieve this either using IDnow's mobile SDKs (available for iOS and Android) or using their webview APIs (for desktop).

For instructions on how to set up IDnow in your solution, see the following IDnow documentation links:


Webhooks

You must subscribe to the following webhook events to ensure that your system receives notifications for crucial events in the identification process. For detailed instructions on implementing Solaris webhooks, see the webhooks documentation.


Create the identification resource for the customer

Initiate the Re-KYC process by creating an identification resource for the customer. This resource sets various parameters for the identification process and stores the results returned by IDnow.

API reference

For a complete list of endpoints, properties, and examples related to customer identification (KYC), visit the following link:

:::note

  • The previous link includes all endpoints for different KYC methods. This section includes the relevant endpoints required for Autoident with IDnow. :::

Related webhook events


POST Create identification

Call this endpoint to create an identification resource for the person specified in the request URL, and add the following properties to the request body:

  • method: The identification method to use. In this case, set the value to idnow_autoident.
  • language: The customer's preferred language for the identification process. Possible values are EN and DE.

:::attention Note that this endpoint does not actually trigger the identification process with the provider. Calling the PATCH Request an identification endpoint will trigger the process. :::

Request example

POST /v1/persons/{person_id}/identifications
{
  "method": "idnow_autoident",
  "language": "DE",
}

Response example

The API call will return an identification object with a unique id (i.e., identification_id) and an initial status of created.

{
    "id": "53e2e4c098045c12cd7249b2b9b2de51cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow_autoident",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null
}

Click here to view the full API reference.

PATCH Request person identification

Call this endpoint to trigger the identification flow with IDnow for the specific customer.

Request URL

PATCH /v1/persons/{person_id}/identifications/{id}/request

Response example

The API call returns the identification object with the status pending. The status will remain pending until the customer completes the identification. Additionally, the payload includes the following key properties:

  • url The URL to complete the identification process in webview.
  • reference: An internal IDnow identification token for the session (format: ABCDEFGH). Do not share this with the customer under any circumstances.
{
    "id": "53e2e4c098045c12cd7249b2b9b2de51cidt",
    "reference": "TS2-ADLSU",
    "url": "https://go.test.idnow.de/solarisbankautosandbox/identifications/53e2e4c098045c12cd7249b2b9b2de51cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow_autoident",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

Click here to view the full API reference.

GET Retrieve person identification

Once the identification completes successfully, call this endpoint to retrieve the finalized person identification. If you use the include_documents filter, the API will also return the documents submitted by the customer during the process. To download any of these documents, use the document's unique id to call the document download endpoints.

Request URL

GET /v1/persons/{person_id}/identifications/{id}

Click here to view the full API reference.

Other identification endpoints

After the customer successfully complete the AutoIdent process, you can download the documents submitted during the identification session using our document-related endpoints here.


IDnow offers test scenarios to simulate different outcomes for the identification process. To trigger a test scenario, you can create a person resource and set the first_name or last_name to one of the following prefixes and the name of the relevant test case. The format is as follows:

{{Test scenario}}-{{Test case}}

Example:

X-MANUALTEST-HAPPYPATH

Test scenarios

PrefixDescription
X-MANUALTESTPerforms a test where you can use the web or app, but the agent is automated.

The available test scenarios are as follows:

Test CaseDescription
HAPPYPATHIdent result will be Success
CANCELEDIdent result will be FRAUD_SUSPICION_CONFIRMED with the reason WARNING_FAKED_MANIPULATED_ID
FRAUDIDENTIdent result will be FAILED with the reason OTHER_ERROR

Happy path test tutorial

Complete the following steps to simulate a successful identification workflow with IDnow on Sandbox.

1. Create a person

Create a person resource using the following endpoint and set the value of the first_name field to X-MANUALTEST-HAPPYPATHto trigger the HAPPYPATH scenario and any value for the last_name in the request body.

Request

POST /v1/persons
{
   "first_name": "X-MANUALTEST-HAPPYPATH",
   "last_name": "{{random_name}}"
}

2. Create an identification resource

Create an identification resource and specify the identification method as idnow_autoident in the request body of the following endpoint. Add the person_id returned from the previous API call to the request URL.

Request example

POST /v1/persons/{person_id}/identifications
{
   "method": "idnow_autoident"
}

3. Trigger the identification

To trigger the identification flow, call the following endpoint, using the person_id and the identification id returned from the previous API call in the request URL.

Request example

PATCH /v1/persons/{person_id}/identifications/{id}/request

Response example

The API call will return the details of a test AutoIdent session, including url (for web browser) and reference (for mobile app).

{
    "id": "24e9967b0d14ac8b123e45efccbf8164cidt",
    "reference": "TS2-YDEKT",
    "url": "https://go.test.idnow.de/solarisbankautosandbox/identifications/24e9967b0d14ac8b123e45efccbf8164cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow_autoident",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "language": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

4. Complete the identification flow

Depending on whether you want to test the identification on the web browser or IDnow mobile application, you can click on the URL to go to the web browser session or enter the reference in the mobile app.

Afterwards, you'll be directed to the AutoIdent flow where you have to:

  1. Enter any mobile number that starts with 0 or you can use the static value: +15550101, check all boxes and click on Start identification. Test AutoIdent flow 1
  2. The flow will start and you'll start seeing different pop-ups with instructions, simulating what would happen in a real AutoIdent session. Test AutoIdent flow 2
  3. The flow goes to the successful stage and the verification data will be submitted. Test AutoIdent flow 3
  4. Afterward, you can call the following endpoint, which will show the identification status as successful. Additionally, the webhook event IDENTIFICATION will be triggered as well after a successful identification.

Request URL:

GET /v1/persons/{person_id}/identifications

What's next?

Congratulations! You have successfully completed the customer KYC process using IDnow AutoIdent

Check the following appendices for more information on enum values and testing data.

For an overview of other KYC methods, check the identity products overview page.

Useful resources

Check the following links for additional related guides and API reference documentation:


Appendix I: Enums

Document types

The following table includes the possible values for the field document_type and their descriptions.

EnumDescription
ANNUAL_FINANCIAL_STATEMENTA business or a company's annual financial statement.
KYC_REPORTThe KYC report generate after a successful customer identification.
ID_DOCUMENTAn person's identification document, such as passport or ID.
SIGNATUREA signature example.
PICTUREA picture or a scanned document of any other type.
QES_DOCUMENTA document related to a Qualified Electronic Signature (QES).
SIGNED_CONTRACTA signed contract of any kind.
SIGNED_QES_DOCUMENTA document signed by a Qualified Electronic Signature (QES).
REGISTER_CHECKA register check.
REGISTER_EXTRACTA business or a company's commercial register excerpt or a similar document.
FOUNDATION_DOCUMENTThe foundation document of a company or business.
SCHUFA_COMPACT_REPORTA compact SCHUFA report.
SCHUFA_GWG_REPORTA GWG SCHUFA report.
SCHUFA_FULL_REPORTA full SCHUFA report about a person.
SCHUFA_SHORT_REPORTA short SCHUFA report about a person.
CREDIT_AGENCY_REPORTA report issued by a credit agency.
SHARE_HOLDERS_AGREEMENTA business or a company's shareholders agreement.
SHAREHOLDERS_LISTA business or a company's shareholders list.
TRADING_LICENSEA business or a company's trading license.
TRANSPARENCY_REGISTER_EXTRACTAn extract of a transparency register.
INVOICEAn invoice of any kind.
OTHERAny other type of document.
VIDEOA video of any kind.
VAT_CERTIFICATEVAT registration certificate

IDow status values

The following table includes the possible values for the field status for the AutoIdent process carried out by IDnow and the related description of each status.

StatusDescription
createdThe identification resource has been created for the customer.
pendingThe identification process has been triggered and the AutoIdent URL and reference are generated. You must redirect the customer to the URL to complete the identification process with IDnow.
pending_failedThe identification is currently under review. You cannot offer banking services to the customer at this stage. The identification might eventually turn to successful, but it is unlikely.
successfulThe AutoIdent was successful. Please note that the customer's data might have been updated during the identification session.
abortedThe customer aborted the identification process. The customer can still identify using the same URL(if not expired).
canceledThe provider canceled the auto identification. The customer should identify again using the same URL (if not expired).
failedThe identification process was unsuccessful.

IDnow provides a reason whenever the identification has a canceled or aborted status. No reason can be disclosed for the final failed status.

IDnow failure codes

The following table describes the possible failure or cancellation reasons for AutoIdent.

Failure reasonDescription
ABORTED
USER_CANCELLATION_DOCUMENT_NOT_ACCEPTEDUser’s ID document is not accepted for the verification process
USER_CANCELLATION_DOCUMENT_EXPIREDUser cannot continue the verification process due to an expired ID document
USER_CANCELLATION_UNDERAGEUser is underage and is not allowed to continue the verification process
USER_CANCELLATION_CAMERA_ACCESS_DENIEDUser does not allow camera permission in the app
USER_CANCELLATION_TERMS_DENIEDUser does not accept the terms and conditions
USER_CANCELLATION_SELFIE_NOT_READYUser is not ready for a selfie
USER_CANCELLATION_APP_NOT_SCANNINGUser aborts as the app is not scanning the document
USER_CANCELLATION_ESIGNING_REJECTEDUser does not accept the esigning request
USER_CANCELLATION_ESIGNING_NAME_CONFIRMATION_REJECTEDUser’s name is specified incorrectly (This applies only to the QES/Signing flow)
USER_CANCELLATION_INCORRECT_PHONE_NUMBERUser aborts as the phone number is specified incorrectly
USER_CANCELLATION_IDENTIFY_LATERUser wants to identify later
USER_CANCELLATION_USER_NOT_INTERESTEDUser is not interested in performing the identity verification
USER_CANCELLATION_APP_NOT_RESPONDINGUser aborts because the app is not responding
USER_CANCELLATION_PRIVACY_CONCERNSUser aborts due to privacy concerns
USER_CANCELLATION_DOCUMENT_NOT_AVAILABLEUser does not have the ID document available and aborts
APP_CANCELLATION_APPROVAL_PHRASE_RETRY_LIMIT_REACHEDThis is used in the QES/esign flow when the app is unable to retrieve the approval phrases from the backend after multiple retries
APP_CANCELLATION_APPROVAL_PHRASE_NO_CONTRACTApp encounters a technical error in the Approval Phrases step in QES/esign
APP_CANCELLATION_APPROVAL_PHRASE_INSUFFICIENT_DOCUMENT_COUNTIn the Approval Phrases step for QES/esign, the required number of documents to be signed are not received from backend
APP_CANCELLATION_OTP_MATCH_LIMIT_REACHEDIn the OTP Authentication step, the user has reached the allowed limit for number of OTP entries and cannot try again
APP_CANCELLATION_TSP_TECHNICAL_EXCEPTIONApp encounters a technical error from the TSP side. If this error state does not resolve after multiple automatic retries, the user cannot proceed further and the ident is aborted with this reason
CANCELLED
ID_BLURRYDocument is blurry and mandatory data cannot be read due to the blur.
ID_GLAREDocument has glare and mandatory data cannot be read due to the glare.
ID_DARKNESSPictures of the document are dark and it is not possible to read the mandatory data or verify the authenticity of the document.
ID_DATA_COVEREDMandatory data is covered by the user while taking the picture
ID_PERSPECTIVEDocument is positioned at such an angle that mandatory data cannot be read or document cannot be verified
ID_DATAMandatory data cannot be read on the document
ID_DATA_OTHERAny other reason due to which mandatory data cannot be read
ID_NOT_SUPPORTEDDocument used during the identification is not supported for the customer’s use case
ID_EXPIREDDocument used during the identification is expired
ID_WRONG_SIDEWrong side of the document is scanned during the process
ID_OUTWORNDocument is worn out. Either data cannot be read or the document cannot be verified
ID_HAS_STICKERDocument has such stickers which are not acceptable and the document is considered as damaged document
ID_WRITTEN_ONDocument has text written over it which makes the document not readable or not verifiable. If the sticker is legit one and added by the authorities while issuing the document then the document will be acceptable and not cancelled due to this reason
ID_BROKENDocument used during the identification is broken
ID_DAMAGEDDocument used during identification is a damaged document
ID_DAMAGED_OTHERAny other reason for a damaged document
ID_SECURITY_FEATURE_NOT_VISIBLE_NOT_FRAUDSecurity features of the document are not visible because user did not move the document correctly
ID_SECURITY_FEATURE_VIDEO_SHORTSecurity feature video is too short to detect if there are holograms in the document
ID_SECURITY_FEATURE_VIDEO_CANNOT_BE_PLAYEDSecurity feature video cannot be played for the agent to review holograms
ID_SECURITY_FEATURE_OTHERAny other issues with the security feature video
ID_SECOND_DOCUMENTIf two documents are required for the identification process, the user needs to photograph two different documents (i.e. ID + Driver’s license) - If the second required ID document is not available, the ident will be cancelled
ID_SECOND_DOCUMENT_BAD_PHOTO_QUALITYPhoto quality of the additional document in the process is not acceptable
ID_SECOND_DOCUMENT_DAMAGEDAdditional document used in the identification process is severely outworn, written or drawn on, ripped or broken
ID_SECOND_DOCUMENT_EXPIREDAdditional document used in the identification process is an expired document
ID_SECOND_DOCUMENT_OTHERAny other issues with the additional document used in the identification process
ID_NEED_ADDITIONAL_DOCUMENTAdditional document like Driver’s License is missing in the identification process but it was required
ID_OTHERAny other issues with the document used in the identification process
USER_INVOICE_MISSINGCustomer needs proof of address from the user as the additional document but user did not provide it in the identification process
USER_OBSCUREDUser has covered the face during the face comparison process unintentionally like wearing the face mask
SELFIE_BLURRYSelfie taken by the user is blurry and cannot be used to compare the face with the identification document
SELFIE_GLAREPhoto of the user on the ID document has glares and selfie cannot be compared with it
SELFIE_DARKNESSSelfie taken by the user is too dark to compare the face of the person with the photo on the identification document
SELFIE_PERSPECTIVESelfie taken by the user is on such an angle that it is not possible to compare it with the photo on the identification document
SELFIE_OTHERAny other issues with the selfie which restrict ident specialist to compare the selfie of the user with the photo on the identification document
IDENT_CANNOT_BE_COMPLETEDDue to a technical reason, ident specialist cannot finish the identity verification process.
IDENT_DISPLAY_ERRORDue to a technical reason, ident specialist cannot see the data submitted by the user in the identification process.
IDENT_OTHERAny other reason due to which the identification process cannot be completed by the ident specialist.
TSP_WRONG_CONFIRMATION_TOKENA wrong signing code was entered by the user during the signing step. (Only when using Autodent with QES / eSign)
TSP_SIGNING_FAILEDThe signing process failed due to any technical error. (Only when using Autodent with QES / eSign)
TSP_CERTIFICATE_EXPIREDSigning certificates are valid for an hour. The final signing step took more than an hour from the time of certificate generation. (Only when using Autodent with QES / eSign)
ID_SECURITY_FEATURE_VIDEO_FILE_MISSINGIf enabled, the system automatically cancels an ident when the 'Security Features' (Hologram) video is not saved due to any technical error, and is hence missing from the final result (zip) file.
FRAUD_SUSPICION_CONFIRMED
WARNING_SELFIE_REAL_PERSONUser that performed the identification is a real person but the selfie does not match with the face on the document.
WARNING_SELFIE_NO_REAL_PERSONSelfie taken in the identification process is not of a real person. For example, the selfie taken is a photo of a picture.
WARNING_SELFIE_DISGUISEDUser intentionally disguised the face by wearing a mask or in some other way.
WARNING_MANIPULATED_DATAData is manipulated on the Identification document.
WARNING_MANIPULATED_PHOTOPhoto of the person is manipulated on the Identification document.
WARNING_FAKED_SECURITY_FEATURESSecurity features like holograms on the Identification document are not real.
WARNING_PAPER_PRINTThe Identification document is not real but a printout taken on a paper.
WARNING_DIGITAL_DOCUMENTIdentification document image is taken from a digital screen (from laptop, from mobile or from any other screen).
WARNING_FAKED_SPECIMENIdentification document is a specimen document and not a real document.
WARNING_USER_UNDERAGEUser is below the age required to access the customer’s service.
WARNING_DIGITAL_SELFIESelfie is taken from a digital screen (from laptop, from mobile or from any other screen).
WARNING_MONEY_MULEUser is duped by fraudster to perform identification on fraudster’s behalf.
WARNING_NAME_COMPARISONConsiderable inconsistency between user’s name and document.
WARNING_SCANIdentification document is a facsimile.
WARNING_FRAUD_OTHERAny other type of fraud identified during the verification process by Ident specialist.

Identification documents

  1. List of accepted ID documents for AutoIdent via IDnow: here

The following table lists all ID types that include the bearer's address, which you can use to perform identification without having to provide a proof of address document.

DocumentIssuer CountryType (ID/PP)
BGR-AO-01005BulgariaPassport
CHN-AO-04003ChinaPassport
HRV-BO-02001CroatiaID
HRV-AO-02001CroatiaPassport
CZE-BO-04001Czech RepublicID
CZE-BO-04002Czech RepublicID
FRA-BO-02002FranceID
FRA-AO-03001-03003FrancePassport
DEU-BO-01003GermanyID
DEU-BO-02001GermanyID
IND-AO-01001IndiaPassport
ITA-BO-04003ItalyID
ITA-BO-03004ItalyID
ITA-BO-03002ItalyID
ITA-BO-03001ItalyID
ITA-BO-03003ItalyID
MLT-BO-02001MaltaID
MLT-BO-03001MaltaID
MAR-AO-02001MoroccoPassport
POL-BO-02001-02003PolandID
SGP-BO-01001-ASingaporeID
SGP-BO-01001SingaporeID
SVK-BO-02001SlovakiaID
SVK-BO-05001SlovakiaID
SVK-BO-04001SlovakiaID
SVN-AO-02001-02003SloveniaPassport
SVN-AO-02004SloveniaPassport
SVN-BO-02001SloveniaID
SVN-AO-01004SloveniaPassport
ESP-BO-03001SpainID
ESP-BO-05001SpainID

Appendix II: IDnow status transitions

Only the following transitions can occur during an IDnow identification session:

Case 1: Happy path

createdpendingsuccessful

Case 2: Suspicion of fraudulent behavior by IDnow that was not confirmed. Identification was marked as successful after review.

createdpendingcanceledsuccessful

Case 3: Fraudulent behavior was detected during a review of an identification that was previously marked as successful.

createdpendingsuccessfulcanceled