W2 Data IDV Check 013

Contents


W2_DATA_IDVCHECK_013 is an identity verification service that uses physical documentation to verify an individual. 

Use of this service is a two-part process, in that before making a call to a bundle containing this service, any documents that are required must already be uploaded to our systems by using the DocumentUpload endpoint. Details on this service method can be found in the "UploadDocument" section of this page.

This service can take up to 24 hours but usually less than 2 hours to give a final response. This is because it involves a manual human intelligence task.

Because of this, details of how this response should be communicated need to be agreed with W2 during the onboarding process. The current options are: 

  • Email
  • HTTP POST request to a specified endpoint

This preference must be agreed with W2 during the on-boarding process in order to use the service. 

The following query data properties pertain to this service. 

Property Name Type Optional/Mandatory Notes
Forename
String
Mandatory  
Surname
String
Mandatory  
HouseNameNumber
String
Mandatory if no HouseName or HouseNumber given  
HouseName
String
Mandatory if no HouseNameNumber or HouseNumber given  
HouseNumber
String
Mandatory if no HouseNameNumber or HouseName given  
Postcode
String
Mandatory  
DayOfBirth
Int
Mandatory  
MonthOfBirth
Int
Mandatory  
YearOfBirth
Int
Mandatory (yyyy)
Country
IsoCountriesEnum
Mandatory Cannot be "None"
Gender
String
Optional Must be "M" or "F" if supplied
PhoneNumber
String
Optional  
MobileNumber
String
Optional  
Flat
String
Optional  
Street
String
Optional  
City
String
Optional  
County
String
Optional   

In addition, an image of the formal identification document must be sent using the UploadFile object, which sits alongside QueryData as part of the ServiceRequest object. It needs to contain the following fields: 

Property Name Type Optional/Mandatory Notes
UploadedFiles
UploadedFile[]
Mandatory  

The UploadedFile object(s) needs to contain the following: 

Property Name Type Optional/Mandatory Notes
DocumentUID
GUID
Mandatory ID of document
Service
ServiceEnum
Mandatory This must be set to W2_DATA_IDVCHECK_013 

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
DocumentCategory

ID

Address

Both

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 both.
VerificationAction

ID

POA

Either

Both

This value indicates the type of check that desired. ID indicates that a proof of identity check is required. POA indicates a proof of address check is required. Either indicates that verification of one or the other is required. Both indicates that both checks are required. This can be used when the type of document is unknown. If this is specified, any value in DocumentCategory will be ignored.

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.

 

The service will then immediately send back a W2_DATA_IDVCHECK_013 result, which is part of the ServiceResult object of the response.

The W2_DATA_IDVCHECK_013 result contains the following fields: 

Property Name Type Possible Outcomes
CallId
String
This will be a unique ID representing this request. This value is what will link this call to the final decision.
ErrorCode
String
"0000" if no errors were encountered. Otherwise it will be an error code.
ErrorDesc
String
"Successful" if the application was successfully submitted. Otherwise it will be a description of the error encountered.

More information on this object can be found in the class documentation here.

A corresponding ServiceTransaction is also sent with the following fields: 

Property Name Type Possible Outcomes
Service
ServiceEnum
Always "W2_DATA_IDVCHECK_013"
ServiceInterpretResult
ServiceTransactionResultCategoryEnum
Always "NotApplicable"
ServiceTransactionResult
ServiceTransactionResultEnum
"Success" if the application was successfully submitted. Otherwise it will be an error label, details on which can be found in Service Transaction Result Message
ServiceTransactionResultMessage
String
"Application successfully sent" if the application was successfully submitted. Otherwise it will be details of what went wrong
ServiceValidationDetails
ServiceValidationResultDetails
NULL if QueryData passed validation, otherwise will be a collection of errors explaining why the QueryData is not valid
ValidationResult
ValidationResultEnum
"Pass" if all validations conditions are met. Otherwise will be details on what needs to be changed in order to pass validation.

More information on this object can be found in the class documentation here.

Note that this is a receipt for the request and not the final result. The final result is sent as a second response.

Here is a sample SOAP request for this service followed the response:

application/xml

Request:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">
http://tempuri.org/IService/KYCCheck
</Action> </s:Header> <s:Body> <KYCCheck xmlns="http://tempuri.org/"> <serviceRequest
xmlns:d4p1="http://schemas.datacontract.org/2004/07/NeuromancerLibrary.DataContracts"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <d4p1:BundleData> <d4p1:BundleName>W2_DATA_IDVCHECK_013</d4p1:BundleName> </d4p1:BundleData> <d4p1:QueryData> <d4p1:City i:nil="true" /> <d4p1:Country>GBR</d4p1:Country> <d4p1:County i:nil="true" /> <d4p1:DateOfBirthMatchThreshold i:nil="true" /> <d4p1:DayOfBirth>1</d4p1:DayOfBirth> <d4p1:DrivingLicenceNumber i:nil="true" /> <d4p1:Flat i:nil="true" /> <d4p1:Forename>John</d4p1:Forename> <d4p1:Gender i:nil="true" /> <d4p1:HouseNameNumber>1</d4p1:HouseNameNumber> <d4p1:IdCardNumber i:nil="true" /> <d4p1:Maiden i:nil="true" /> <d4p1:MiddleNames i:nil="true" /> <d4p1:MobileNumber i:nil="true" /> <d4p1:MonthOfBirth>1</d4p1:MonthOfBirth> <d4p1:NameQuery i:nil="true" /> <d4p1:NameQueryMatchThreshold i:nil="true" /> <d4p1:NationalId i:nil="true" /> <d4p1:PassportNumber i:nil="true" /> <d4p1:PhoneNumber i:nil="true" /> <d4p1:PlaceOfBirth i:nil="true" /> <d4p1:Postcode>123 AAA</d4p1:Postcode> <d4p1:ProfileId i:nil="true" /> <d4p1:Region i:nil="true" /> <d4p1:Street i:nil="true" /> <d4p1:Surname>Smith</d4p1:Surname> <d4p1:TaxCode i:nil="true" /> <d4p1:TravelVisaNumber i:nil="true" /> <d4p1:YearOfBirth>1980</d4p1:YearOfBirth> </d4p1:QueryData> <d4p1:QueryOptions /> <d4p1:ServiceAuthorisation> <d4p1:APIKey>ABC</d4p1:APIKey> <d4p1:ClientReference i:nil="true" /> <d4p1:ClientSubaccount i:nil="true" /> <d4p1:ClientUser i:nil="true" /> <d4p1:RefersToServiceCallReference i:nil="true" /> </d4p1:ServiceAuthorisation> <d4p1:UploadedFiles> <d4p1:UploadedFile> <d4p1:DocumentReference i:nil="true" /> <d4p1:DocumentUID>6e22449c-c979-40b6-88f5-ae9ce4594da9</d4p1:DocumentUID> <d4p1:Group i:nil="true" /> <d4p1:Index i:nil="true" /> <d4p1:Service>W2_DATA_IDVCHECK_013</d4p1:Service> </d4p1:UploadedFile> <d4p1:UploadedFile> <d4p1:DocumentReference i:nil="true" /> <d4p1:DocumentUID>b035520a-391e-4182-9026-244178086e55</d4p1:DocumentUID> <d4p1:Group i:nil="true" /> <d4p1:Index i:nil="true" /> <d4p1:Service>W2_DATA_IDVCHECK_013</d4p1:Service> </d4p1:UploadedFile> </d4p1:UploadedFiles> </serviceRequest> </KYCCheck> </s:Body> </s:Envelope>

application/xml

Response:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header />
  <s:Body>
    <KYCCheckResponse xmlns="http://tempuri.org/">
      <KYCCheckResult 
xmlns:a="http://schemas.datacontract.org/2004/07/NeuromancerLibrary.DataContracts"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:ClientProvidedData> <a:ClientReference i:nil="true" /> <a:ClientSubaccount i:nil="true" /> <a:ClientUser i:nil="true" /> <a:RefersToServiceCallReference i:nil="true" /> </a:ClientProvidedData> <a:ProcessRequestResult> <b:ServiceResult> <b:DirectorUKCheckResult i:nil="true" /> <b:IDCheckATBravoResult i:nil="true" /> <b:IDCheckAddressLookupResult i:nil="true" /> <b:IDCheckCHBravoResult i:nil="true" /> <b:IDCheckCZBravoResult i:nil="true" /> <b:IDCheckDEAlphaResult i:nil="true" /> <b:IDCheckDEBravoResult i:nil="true" /> <b:IDCheckITBravoResult i:nil="true" /> <b:IDCheckNLAlphaResult i:nil="true" /> <b:IDCheckNameLookupResult i:nil="true" /> <b:IDCheckPassportMRZResult i:nil="true" /> <b:IDCheckRUBravoResult i:nil="true" /> <b:IDCheckSKBravoResult i:nil="true" /> <b:IDCheckUKAlphaResult i:nil="true" /> <b:IDCheckUKDeltaResult i:nil="true" /> <b:IDCheckUKDrivingLicenceNumberResult i:nil="true" /> <b:IDCheckZAAlphaResult i:nil="true" /> <b:IDDocumentCheckResult i:nil="true" /> <b:PEPDeskCheckResult i:nil="true" /> <b:ProfileDetailsResult i:nil="true" /> <b:SISPlusCheckResult i:nil="true" /> <b:SPFPlusCheckResult i:nil="true" /> <b:W2DataAddressLookUp007Result i:nil="true" /> <b:W2DataEkybUk009Result i:nil="true" /> <b:W2DataEkycUk007Result i:nil="true" /> <b:W2DataIdvcheck013Result > <c:CallId>WSCR3C6BE94E0BFB4CCAA092968BF5E448BE</c:CallId> <c:ErrorCode>0000</c:ErrorCode> <c:ErrorDesc>Successful</c:ErrorDesc> </b:W2DataIdvcheck013Result> <b:WatchlistCheckResult i:nil="true" /> </b:ServiceResult> <b:TransactionInformation> <b:InterpretResult>NotApplicable</b:InterpretResult> <b:ServiceCallReference>3c6be94e-0bfb-4cca-a092-968bf5e448be</b:ServiceCallReference> <b:ServiceTransactions> <b:ServiceTransactionInformation> <b:FailedOverTo i:nil="true" /> <b:HaltTriggered>false</b:HaltTriggered> <b:Service>W2_DATA_IDVCHECK_013</b:Service> <b:ServiceInterpretResult>NotApplicable</b:ServiceInterpretResult> <b:ServiceTransactionResult>Success</b:ServiceTransactionResult> <b:ServiceTransactionResultMessage>
Application Submitted Successfully.
</b:ServiceTransactionResultMessage> <b:ServiceValidationDetails i:nil="true" /> <b:ValidationResult>Pass</b:ValidationResult> </b:ServiceTransactionInformation> </b:ServiceTransactions> </b:TransactionInformation> </a:ProcessRequestResult> </KYCCheckResult> </KYCCheckResponse> </s:Body> </s:Envelope>

Approximately 30 minutes after the initial request (this time will vary as it involves a manual human intelligence task), W2 will send a second response to the initial query, containing the final result.

This result will be sent either by email or HTTP POST as request. The recipient email address / URL endpoint will have been agreed upon during the on-boarding process.

Email Response

If email was requested, an email will be sent out containing the Call ID of the initial request and the "Pass" or "Fail" result. It will look something like this: 

Result Email

Subject: W2_DATA_IDVCHECK_013 Result

***

Dear [Company Name],

This is the final result of a call to W2_DATA_IDVCHECK_013 that you made at [Date Of Request],

Please see the result below.

CallID: [Call ID returned by first response]

Result: ["PASS" or "FAIL"]

Kind regards

W2 Global Data 

POST Response 

If a POST response was requested, a HTTP post request will be sent out containing a populated TransactionInformation object serialized into XML. 

The TransactionInformation object will be identical in structure to the one returned in the immediate response. However it will only contain a single ServiceTransaction which will be the final result of the W2_DATA_IDVCHECK_013 call. 

This ServiceTransaction will have the following fields:

Property Name Type Possible Outcomes
Service
ServiceEnum
Always "W2_DATA_IDVCHECK_013"
Service Interpret Result
ServiceTransactionResultCategoryEnum
"Pass" or "Fail". This is the final result.
Service Transaction Result
ServiceTransactionResultEnum
Always "Success"
Service Transaction Result Message
String
This will be the Call ID value of the initial service response and, if the result was not a Pass, followed by the reason why after a semicolon, ie: "WSCRB0C3B15DA015454DBF94BD9C8BF660DA; ID expired"
Service Validation Details
ServiceValidationResultDetails
Always NULL
Validation Result
ValidationResultEnum
Always "NotApplicable"

The end result is that the resulting HTTP POST request will look something like this:

Result POST request

POST [Callback URL] HTTP/1.1

Content-Type: application/xml

Authorization: Basic [Network credential built from company name and API key - see note 1]

Host: [Callback URL host]

Content-Length: [Length of message]

Expect: 100-continue


[XML of TransactionInformation object]

Here is an example of what the XML of the TransactionInformation object could look like:

Example TransactionInformation XML

<TransactionInformation 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns: xsd="http://www.w3.org/2001/XMLSchema">
<ServiceTransactions>
<ServiceTransactionInformation>
<Service>W2_DATA_IDVCHECK_013</Service>
<ServiceTransactionResult>Success</ServiceTransactionResult>
<ServiceTransactionResultMessage>
WSCR1C2B4A33C78D4355B93391F9C56BEDAV
</ServiceTransactionResultMessage>
<ValidationResult>NotApplicable</ValidationResult>
<HaltTriggered>false</HaltTriggered>
<ServiceInterpretResult>Pass</ServiceInterpretResult>
<ServiceHasFailedOver>false</ServiceHasFailedOver>
</ServiceTransactionInformation>
</ServiceTransactions>
<ServiceCallReference>c391453f-4546-4306-a274-5520addc812f</ServiceCallReference>
<InterpretResult>Not Applicable</InterpretResult>
</TransactionInformation>

Note 1: An authorization header is added to give customers the option to authenticate the request before accepting it. The credential is a network credential made up from the following:

  • Username: Name of company as it appears in Portal
  • Password: Company API key

The resulting value is constructed as follows (as described here):

  1. Username and password are combined into a string "username:password".
  2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.

This will create something like: 

Example Authorization Header

Basic VzI6cGl6emE=

Allowing the endpoint server to deny the request based on this credential if that is preferred. 

The following tool will spoof a final POST resonse, allowing you to test receiving it. Simply fill in the address of your endpoint and, if needed, any other values that you need to test and click the "Send Post Request" button. The "Request" and "Response" boxes will show what was sent and received. 

Fields that are left blank will send their default value. Note that this tool always gives a final result of "Fail" due to "Fraud". 

 

Spoof Final Response Tool

 

Sometimes the result may not be a pass or a fail, but a "Refer". 

A "Refer" result happens when there is something about the document that is preventing a final decision from being made. The most common cause of this is that the ID is expired or illegible.

If the result has been received via email, the reason is outlined below the result. Here is an example of what the email might look like: 

Example of "Refer" Result Email

Subject: W2_DATA_IDVCHECK_013 Result

***

Dear Globex Corporation,

Further action required, please see below.

This is the final result of a call to W2_DATA_IDVCHECK_013 that you made on 15 January 2016 11:59:30,

Please see the result below.

CallID: WSCRB0C3B15DA015454DBF94BD9C8BF660DA

Result: Refer

Details: ID expired

This means that the submitted document is not adequate for a final decision to be made. A correct document will need to be submitted in order to get a final Pass / Fail decision.

This will require a slightly altered submission to W2_DATA_IDVCHECK_013 that contains the new document and references CallID: WSCRB0C3B15DA015454DBF94BD9C8BF660DA. To find out how to do this, please see the "Refer Result" section on this page: http://developer.w2globaldata.com/Documentation/W2DataIdvcheck013Service/#ReferResult

For further details on this result, please login to https://portal.idvcheck.com using the details given during on-boarding.

Kind regards

W2 Global Data

If the result has been receievd via postback, the reason is given next to the unique ID in the ServiceTransactionResultMessage field of the ServiceTransactionInform object. It is seperated from the ID with a semi-colon. Here is an example of what the post request might look like:

Example of "Refer" Result Post

POST https://www.globexcorporation.com/services/callbackservice.svc HTTP/1.1

Content-Type: application/xml

Authorization: Basic VzI6cGl6emE=

Host: www.globexcorporation.com

Content-Length: 869

Expect: 100-continue


<TransactionInformation 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd=" http://www.w3.org/2001/XMLSchema">
<ServiceTransactions>
<ServiceTransactionInformation>
<Service>W2_DATA_IDVCHECK_013</Service>
<ServiceTransactionResult>Success</ServiceTransactionResult>
<ServiceTransactionResultMessage>
WSCRB0C3B15DA015454DBF94BD9C8BF660DA;ID expired
</ServiceTransactionResultMessage>
<ValidationResult>NotApplicable</ValidationResult>
<HaltTriggered>false</HaltTriggered>
<ServiceInterpretResult>Inconclusive</ServiceInterpretResult>
<ServiceHasFailedOver>false</ServiceHasFailedOver>
</ServiceTransactionInformation>
</ServiceTransactions>
<InterpretResult>NotApplicable</InterpretResult>
</TransactionInformation>

What To Do In The Event of a "Refer" Result

To complete the verification, a replacement / corrected document will need to be uploaded that satisfies the requirements needed for a final decision to be made.

To do this, follow these steps: 

  1. Upload a replacement / corrected document to W2 systems using the UploadDocument API method.
  2. Make a new call to W2_DATA_IDVCHECK_013 with the DocumentUID of the newly uploaded document inserted into UploadedFiles array and add a query option with the key uniqueid and the value as the unique ID of the original call. Query data is not necessary for this request.

This will re-open the process for this document, and the new result will come through via email / postback in the same way as the orignal result. If the new result is also a "refer", this process can be repeated until the document is verfied. 

Could I Send A New Application With The Corrected Document Instead Of Doing The Above? 

It is not recommended to send a new application in the event of a refer, as this will incur a second charge. Using the method described above will not incur any further charges and is the recommended course of action in the event of a refer result. 

If the Sandbox query option is set to "true" then the following test cases can be used:  

PASS Test Case  

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a PASS:  

Field Value
Forename Louie
Surname Ellis
HouseNameNumber 92
Postcode PE12 0WS
DayOfBirth 19
MonthOfBirth 2
YearOfBirth 1944
Country GBR

FAIL Test Case

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a FAIL:

Field Value
Forename Riley
Surname Davies
HouseNameNumber 4
Postcode GU4 4UF
DayOfBirth 27
MonthOfBirth 2
YearOfBirth 1974
Country GBR

REFER Test Case "ID EXPIRED"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "ID EXPIRED":

Field Value
Forename Megan
Surname Brookes
HouseNameNumber 98
Postcode RG19 9DW
DayOfBirth 9
MonthOfBirth 8
YearOfBirth 1979
Country GBR

For more details on what a "Refer" result means, please see here

REFER Test Case "ID ok, POA illegible"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "ID ok, POA illegible":

Field Value
Forename Olivia
Surname Wheeler
HouseNameNumber 82
Postcode PO38 4UU
DayOfBirth 4
MonthOfBirth 2
YearOfBirth 1940
Country GBR

 

REFER Test Case "POA ok, ID invalid"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "POA ok, ID invalid":

Field Value
Forename Jayden
Surname Edwards
HouseNameNumber 42
Postcode PL12 8XY
DayOfBirth 1
MonthOfBirth 5
YearOfBirth 1982
Country GBR

 

 

Finalising a REFER result

In a real world situation you would want to upload a second document in response to a "Refer" result as described in the link above.

This can also be done in sandbox mode for this call. Simply make a request without any query data, and a query option value of uniqueid set to value "WSCRA055F2C9FC32415FB4D189488108F4EB" (still with the sandbox query option set).

The ServiceTransactionInformation object will return the same as above, with the following difference:

<ServiceTransactionResultMessage> Successfully Re-submitted Application. 
                                  (This call was generated using sandbox mode)