Manual Document Check

Compatible Cases

About the service

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

Product Code: W2-DATA-IDVCHECK-013

Does this service leave a credit search Footprint? No

Document Upload

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 Document upload

Callback Preference

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 (Formatted in XML or Json)
This preference must be agreed with W2 during the on-boarding process in order to use the service.

Request

Query Data

The following query data properties pertain to this service.

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

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

Query Options

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

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.

Example Request

{    
    "Data": {
        "Country": "GBR",
        "DayOfBirth": 1,
        "Forename": "Johnny",
        "HouseNumber": "44",
        "MonthOfBirth": 1,
        "Postcode": "CF36 5DJ",
        "Surname": "Testy",
        "YearOfBirth": 1990
    },
    "Files": [
        {
            "DocumentReference": "Test Image",
            "Id": "0FF8F8BA-F0BB-4B53-86D6-7185D9019269",
            "Service": "W2_DATA_IDVCHECK_013"
        }
    ]
}

Response

Immediate Response

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

Immediate response breakdown

The W2_DATA_IDVCHECK_013 result contains the following fields:

A corresponding ServiceTransaction is also sent with the following fields:

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.

Example immediate response

{
	"results": {
		"w2DataIdvcheck013Result": {
			"callId": "WSCR1C2B4A33C78D4355B93391F9C56BEDAV",
			"errorCode": "0000",
			"errorDesc": "Successful"
		}
	},
	"transaction": {
		"interpretResult": "Pass",
		"serviceCallReference": "37d86697-3cb3-4e1b-a14b-7723bc14768f",
		"serviceTransactions": [{
				"haltTriggered": false,
				"service": "W2_DATA_IDVCHECK_013",
				"serviceInterpretResult": "NotApplicable",
				"serviceTransactionResult": "Success",
				"serviceTransactionResultMessage": "Application Submitted Successfully.",
				"validationResult": "Pass"
			}
		]
	}
}

Final Response

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:

Post Response

It’s recommended to verify the request by validating the header value ‘x-w2-signature‘ which is a base64 encoded hash of request body. The algorithm used to generate the hash is SHA256 with your API key as the secret.

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

The TransactionInformation object will be identical in structure to the one returned in the immediate response except that it also contains your ClientReference. 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:

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

Example TransactionInformation

<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>
  <ClientReference>123</ClientReference>
</TransactionInformation>

{
	"ServiceTransactions": [
		{
			"Service": "W2_DATA_IDVCHECK_013",
			"ServiceTransactionResult": "Success",
			"ServiceTransactionResultMessage": "64f7be75-299b-4ee0-a1be-fdb776acc2d1",
			"ValidationResult": "NotApplicable",
			"HaltTriggered": false,
			"ServiceInterpretResult": "Pass",
			"ServiceHasFailedOver": false
		}
	],
	"ServiceCallReference": "57f27731-902c-44b8-b28c-0a5382f7484d",
	"InterpretResult": "NotApplicable",
	"ClientReference": "123"
}

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:

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

'Refer' Result

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:

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

Example of 'Refer' Result Post

<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>

"transaction": {
		"interpretResult": "NotApplicable",
		"serviceCallReference": "37d86697-3cb3-4e1b-a14b-7723bc14768f",
		"serviceTransactions": [{
				"haltTriggered": false,
				"service": "W2_DATA_IDVCHECK_013",
				"serviceInterpretResult": "Inconclusive",
				"serviceTransactionResult": "Success",
				"serviceTransactionResultMessage": "WSCRB0C3B15DA015454DBF94BD9C8BF660DA;ID expired",
				"validationResult": "NotApplicable"
			}
		]
	}

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 Document upload 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 original result. If the new result is also a "refer", this process can be repeated until the document is verified.

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.

Refer IDV Response Codes

Sandbox

To use sandbox the following example request can be used.

Remember to include the W2 provided API key in the Authorization Header.

Example Request

{
    "Bundle": "Your bundle",
    "Data": {
        "Forename": "Louie",
        "Surname": "Ellis",
        "HouseNameNumber": "92",
        "DayOfBirth": 19,
        "MonthOfBirth": 2,
        "YearOfBirth": 1944,
        "Country": "GBR",
        "Postcode": "PE12 0WS"
    },
    "Options": {
        "Sandbox": "true"
    },
    "ClientReference": "your-client-reference"
}

Sandbox cases

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:

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:

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":

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":

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":

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) </ServiceTransactionResultMessage>

The ServiceTransactionInformation object will return the same as above, with the IDV Response codes

Docs not making sense? Please contact us so we can fix them: [email protected] :)