W2 Data Document Check 026 Service

 

W2 Data Document Check 026 Service

Contents

 

 

Overview

This service provides automatic and manual document verification for international documents. You upload a document to W2 Global data using our DocumentUpload method and then call the service using the document UID we supply.

This service acts a little differently to most of our other services in that all responses are sent asynchronously. We send all results via email or via HTTP POST depending on your configuration settings.

The Service will attempt to automatically verify the document and return the result. You can override this specifying the ManualVerification query option which will skip automatic verification and proceed with manual verification.

If it can't automatically verify, the document will be passed on for manual verification. This can take up to 24 hours to complete.

W2 Global Data will notify you when the manual verification is complete.

 

Before calling this service you will need to let W2 know the following:

  1. Your preference for notifications (email or http POST).
  2. An email address to send notifications to (if requested).
  3. A URL to post notifications to (if requested).
  4. Whether you prefer the http POST in JSON (the default) or XML.

More information on notifications can be found below

To begin the verification you will need to upload a document to W2 Global Data. This can be done using the DocumentUpload method. Simply send a call to the API using the following request.

<Envelope>
   <Header/>
   <Body>
      <UploadDocument>
         <documentUploadRequest>
            <DocumentData>{ The image encoded to a base 64 string }</DocumentData>
            <DocumentExpiry>{ The date the document expires }</DocumentExpiry>
            <DocumentReference>{ A client specific tracking reference }</DocumentReference>
            <DocumentType>{ JPEG | PNG | None }</DocumentType>
            <ServiceAuthorisation>
               <APIKey>{ Your API key goes here}</APIKey>
               <ClientReference>{ Optional reference }</ClientReference>
            </ServiceAuthorisation>
         </documentUploadRequest>
      </UploadDocument>
   </Body>
</Envelope>

The DocumentData field must contain a Base64 Encoded representation of the document to upload. The recommended method for creating this representation is to use OpenSSL and issuing the following command;

openssl enc -Base64 -in {inputFilePath} -out {outputFilePath} 

The output from the above will be a text string similar to;

/9j/4TmVRXhpZgAASUkqAAgAAAANAAABBAABAAAAwBQAAAEBBAABAAAArAsAAA8B
AgAIAAAAqgAAABABAgAJAAAAsgAAABIBAwABAAAAAQAAABoBBQABAAAAvAAAABsB
BQABAAAAxAAAACgBAwABAAAAAgAAADEBAgAOAAAAzAAAADIBAgAUAAAA2gAAABMC
AwABAAAAAQAAAGmHBAABAAAA7gAAACWIBAABAAAAVAwAAGYMAABzYW1zdW5nAFNN
LU45MTBGAABIAAAAAQAAAEgAAAABAAAATjkxMEZYWFUxQk9DMwAyMDE1OjA4OjAz
IDExOjIwOjM5AB8AmoIFAAEAAABoAgAAnYIFAAEAAABwAgAAIogDAAEAAAACAAAA
J4gDAAEAAAAoAAAAAJAHAAQAAAAwMjIwA5ACABQAAAB4AgAABJACABQAAACMAgAA
......(Output truncated)

You should get a response something like this:

<Envelope>
   <Body>
      <UploadDocumentResponse>
         <UploadDocumentResult>
            <BytesUploaded>{size of uploaded object e.g. 209668}</BytesUploaded>
            <DocumentReference>{ the document reference }</DocumentReference>
            <DocumentTypeValidationSucceeded>{ true | false }</DocumentTypeValidationSucceeded>
            <DocumentUID>{ a unique reference i.e. f47eb392-4067-4105-95dc-3ce98555ffb2}</DocumentUID>
            <ResolvedDocumentType>{ the document type i.e. JPEG}</ResolvedDocumentType>
         </UploadDocumentResult>
      </UploadDocumentResponse>
   <Body>
<Envelope>

You will need the DocumentUID to call the service.

A request to the W2 Data Document Check 026 Service uses the UploadedFiles, BundleData and ServiceAuthorisation elements of the API request.

The QueryData can be empty and the service will attempt to read the relevant information from the document, however this will have nothing to check against. So It is advised to supply the following in alphabetical order:

 

Value Description Optional / Mandatory
Forename The Identity's first name Mandatory
Surname The Identity's second name Mandatory
DayOfBirth The day from the Identity's date of birth Mandatory
MonthOfBirth The month from the Identity's date of birth Mandatory
YearOfBirth The year from the identity's date of birth Mandatory
HouseNameNumber The name or number of the address (i.e. 3 or Flat 3) - does not need to be provided if HouseName or HouseNumber is given Mandatory*
HouseName The name of the address Mandatory*
HouseNumber The number of the address Mandatory*
Street The first line of the Address (i.e. South Street) Optional
City The city in the address (i.e. Bristol) Optional
PostCode The Post or ZipCode of the address Mandatory
Country The 3 character ISO Country Code Mandatory

* Either HouseNameNumber, HouseName or HouseNumber must be provided, if you use HouseName and/or HouseNumber, then HouseNameNumber is not also required.

Query Options

The QueryOptions element is optional and is used for optional configuration options. This service uses two possible query options.

Name Possible Values Description
VerificationType

Auto

Manual

Both

Controls which sort of verification type you want to perform. Auto will only attempt to automatically verify the document, Manual will skip automatic verification and proceed to manual verification and Both will attempt to verify automatically and proceed to manual if that doesn't work. If this setting is left out the default is both. 
DocumentCategory

ID

Address

ID indicates that the document is used for proof of identity (for example a passport) and the service will attempt to verify as such. Address indicates that this is used for proof of address (for example a utility bill) and will attempt to verify as such.If this field is left out then we will assume this is and ID document.

ID documents are Passports, National ID cards, Driving license, Residence Permits. Any other document is not a proof of Identity.

Proof of Address is usually utilities or phone bills or tax statements. Other kinds of bills may also be accepted.

A full request should look like the following, note the bundle name will be supplied by W2 Support:

<Envelope>
   <Header />
   <Body>
      <KYCCheck>
         <serviceRequest>
            <BundleData>
               <BundleName>{ The name of a bundle including the service }</BundleName>
            </BundleData>
            <QueryData>
<DayOfBirth>{ e.g. 01 }</DayOfBirth>
<Forename>{ e.g. John }</Forename>
<MonthOfBirth>{ e.g. 01 }</MonthOfBirth>
<Surname>{ e.g. Smith }</Surname>
<YearOfBirth>{ e.g. 1900 }</YearOfBirth>
</QueryData> <QueryOptions> <KeyValueOfstringstring> <Key>VerificationType</Key> <Value>both</Value> </KeyValueOfstringstring>
<KeyValueOfstringstring>
<Key>DocumentCategory</Key>
<Value>ID</Value>
</KeyValueOfstringstring> </QueryOptions>
<ServiceAuthorisation> <APIKey>{ Your API key goes here }</APIKey> </ServiceAuthorisation> <UploadedFiles> <UploadedFile> <DocumentReference>{ The document reference }</DocumentReference> <DocumentUID>{ The DocumentUID you got from the DocumentUpload method }</DocumentUID> <Service>W2_DATA_MDV_026</Service> </UploadedFile> </UploadedFiles> </serviceRequest> </KYCCheck> </Body> </Envelope>

The DocumentUID, in the UploadedFiles element is the same that you would have got returned from the document upload.

The service name is W2_DATA_MDV_026.

The VerificationType query option is only used if you want to skip automatic verification and go straight to manual verification. The entire QueryOptions should be removed if this is not the desired behaviour.

Automatic Verification

The service will first attempt an automatic verification. If this is successful the process stops here. The response will contain the following object.

<W2DataMdv026Result>
    <DocumentId>{ a unique id number e.g. MDV025F07D11CD61C142B6903024D24C913589 }</DocumentId>
<ResultMessage>
{ e.g. Results will be sent http://myendpoint.com }
</ResultMessage>
<ResultType>{ Manual | Automatic | Error }</ResultType> </W2DataMdv026Result>

The ResultCategory can have the following values:

 

Value Description Service Interpret Result
None Not checked. Manual check required. Not Applicable
OtherDocument Document is not an identity document as expected. Fail
Falsified Document has been identified as fake. Fail
Unreadable Document can't be read. Fail
Unacceptable The wrong part of the document is shown, for example, back only, or missing front. Fail
InconsistentName The first and last name appear in different order on different places in the document. Fail
InconsistentData There is an inconsistency elsewhere in the data where it appears at different places in the document. Fail
Expired Document is shown to be expired. Fail
Verified The document has been verified. Pass
VerifiedApproved The document has been verified + approved. Pass

Manual Verification

If the service cannot automatically verify the ID, or you have requested manual verification, then the ID will be passed on for manual checking. This can take up to 24 hours and W2 will notify you when this is complete.

When the ID document has been verified W2 will notify you with the results of the verification process. We can do this with an email, an HTTP POST or both. W2 Support will configure this for you as part of the on boarding process.

Email

If you have requested an email notification you will recieve an email when the verification is complete. The email will look something like this:

Result Email

Subject: {Pending/Final} result for W2_DATA_MDV_026, application ID [Application ID]

***

Dear [Company Name],

This is the result of a call to W2_DATA_MDV_026 that you made on [Date Of Request],

Application ID: [Application ID]

Call Reference: [Call Reference from initial request]

Client Reference: [Client Reference] (if supplied)

Client Sub Account: [Client Sub Account] (if supplied) 

Result: [Result] from ResultCategory table above

Additional Info: Corresponding comment from result table above

Kind regards

W2 Global Data 

We will also email you if any errors occur.

HTTP POST

We can also post to a web hook. You will need to give W2 Support the address for this web hook.

The post will be over HTTPS and be a json (or optionally an XML) object containing the verification information along with the ServiceTransactionInformation object that all our services return.

The following is an example with some typical values.

  • Authorization: "Basic {CompanyName}:{ApiKey}" (Encoded as Base 64 string)
  • Content-Type: "application/json"
  • Content-Length: { The byte length of the content }
{  
   "EventType": "ApiV3ServiceResponse" | "Error", (string)
   "ClientReference": "The client reference from the original call", (string)
   "CallReference":"The call reference from the original call", (string)
   "ClientSubaccount":"The client subaccount from the original call", (string)
   "ServiceResults":{
      "W2DataMdv026":{
         "DocumentId":"a unique identifier", (string)
         "IsFinalResult":true, (bool)
         "ResultCategory":"The result category", (enum: see the result category table above)
         "ResultCategoryExplained":"An explanation of the result", (string)
         "ResultMessage":"A message about the response", (string)
         "Details":{
            "Surname":"SMITH", (string)
            "Forenames":"JOHN", (string)
            "DateOfBirth":"01/01/1900", (string: of the format DD/MM/YYYY)
            "PlaceOfBirth":"", (string)
            "Mrz1":"", (string)
            "Mrz2":"", (string)
            "Mrz3":null, (string)
            "Nationality":"", (string)
            "IssuingCountry":"", (string)
            "IssuingAuthority":"", (string)
            "Type": "Passport | ID Card | Visa | Drivers License | Residence Permit", (string)
            "Gender": "M | F | X", (string: X = Unspecified)
            "IdNumber":"", (string)
            "ExpirationDate":"01/01/2021", (string: of the format DD/MM/YYYY)
            "Address":null, (string)
            "City":null, (string)
            "Country":null, (string)
            "PostCode":null (string)
         }
      }
   },
   "TransactionInformation":{
      "ServiceTransactions":[
         {
            "Service":"W2_DATA_MDV_026", (string)
            "ServiceInterpretResult":"Pass | Fail | Refer ", (string)
            "ServiceTransactionResult":"Success | Fail" (string)
         }
      ]
   }
}