idvCheck allows a client to submit details for sanction checking, electronic kyc and manual kyc using the same api call.

The api can be set up using one of five modes. Depending on the mode in use the api will return a result out of a possible list.

Mode 1 - Sanctions check only

0020 Sanctions - No Match
0021 Sanctions - Requires Investigation

Mode 2 - Sanctions check, electronic kyc, manual kyc

0018 eKYC Approved
0019 eKYC Pending
0021 Sanctions - Requires Investigation

Mode 3 - Sanctions check, manual kyc

0020 Sanctions - No Match
0021 Sanctions - Requires Investigation

Mode 4 - Electronic kyc, manual kyc

0018 eKYC Approved
0019 eKYC Pending

Mode 5 - Manual kyc

0000 Successful submission.

For all modes

Any other code returned would signify that an error had occurred during the call of the service. An exhaustive list of codes is found here. Calling the idvcheck api also results in an aysynchrons call (postback) to the client. This call contains more details of the result. Information about this call can be found here.

API

This document outlines the api adopted by idvcheck to allow clients to submit documentation to idvcheck. This integration route is only applicable for clients who cannot make use of the rapid integration kit.

In order to integrate you need to create two modules. The first module is used to register an application to idvcheck. The UniqueId field identifies each application. No two submitted applications can contain the same UniqueId field. The application can contain the documents that need to be verified by idvcheck, or the documents can be sent in subsequent calls to api. If documents are sent in subsequent calls of the api, the calls must share the same UniqueId field. The second module is used to receive results from idvcheck once the verification process is completed. idv will post the result of the verification to a URL of your choice into a parameter called DATA. The data submitted will include all the data used for verification plus a new field with the result of the verification.

• Calling the api
• Registering an application
• Field mapping
• Sending files at a later stage
• Receiving the results of the verification process
• Pending Status
• Updating an application

The wsdl for the api used to receive applications and file is available here. This api requires 5 mandatory parameters:

Parameter	Description
username	User name supplied by idvcheck at the time of integration
password	Password supplied by idvcheck at the time of integration. Note that you might be asked to change the password at any point and hence it is advisable not to hardcode the password in the implementation
APISignature	Identifies the api being called
MessageID	An identifier set by the client which can be used to identify the call if a call to support is required. This identifier must be unique for each api call
Data	A well defined XML document outlined in the sections below

Notes

• During Integration clients will integrate with a staging service. Upon successful tests the client will be provided with a link to the service used in production. The staging service runs over http whilst the production service runs over https
• Ensure that in the webrequest headers you are adding "SOAPAction", "\"http://tempuri.org/IService/Process\".
  In dot net this is done using the following code:
  

  webRequest.Headers.Add("SOAPAction", "\"http://tempuri.org/IService/Process\"");
  

• Since you are posting to a web service the XML parameter data must Http encoded

[Table of Contents]

To register an application call the process api with an apisignature of NewApplication

The data parameter requires an XML document similar to the sample below. The XSD for this XML can be found here.

<A xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <P2>Matthew</P2>
  <P3>Smith</P3>
  <P4>09 Jun 1986</P4>
  <P13>CLA20130929145554480</P13>
  <P7>
    <I>+39 66599811</I>
  </P7>
  <P8>
    <I>+35699815754</I>
  </P8>
  <P9>
    <I>[email protected]</I>
  </P9>
  <P10>
    <P10A>
      <R1>Primary</R1>
      <R2>68, Block F</R2>
      <R3>Baker Street</R3>
      <R4>SomePlace</R4>
      <R5>PO143FD</R5>
      <R6 />
      <R7>United Kingdom</R7>
      <R8>GB</R8>
    </P10A>
  </P10>
  <P11>
    <I>57792A</I>
  </P11>
  <P12>
    <P12A>
      <S1>contents of file in a BASE64STRING </S1>
      <S2>id.jpg</S2>
    </P12A>
    <P12A>
      <S1>contents of file in a BASE64STRING </S1>
      <S2>passport.jpg</S2>
    </P12A>
  </P12>
</A>

The api will return an XML document with the following format:

<APIReturn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorCode>0000</ErrorCode>
  <ErrorDesc>Successful</ErrorDesc>
</APIReturn>

The two fields return can be one of the following:

ErrorCode	ErrorDesc	Description
0000	Successful	Api submission was successful
0001	Authentication failed	Submitted useraname or password are incorrect
0002	Operation failed	A general failure while using the api
0003	Data incorrect	The data xml has incorrect data
0004	Application already exists	The unique id is already used with another application
0005	Files did not save: [Name of File]	Adding file to application failed
0006	Application failed to save	Application failed to save
0007	Application does not exists	Added file unique ID does not match any application
0009	MessageID is already used	Api submission message ID is already used by another application
0010	RIK configuration error	Issues related to RIK configurations
0011	Application status does not allow to add file	If application is worked out, a new file cannot be added
0012	File addition failed	A generic error when file fails to be added to application
0013	File base64 string is invalid	A file being added to application is not a valid base64 string
0014	XML validation failed [ERRORS]	The XML does not validated against the XSD Schema. A list of errors will be returned
0015	No files received	In the API request there was no files attached
0016	Invalid file extension	The file extension is not supported
0018	eKYC Approved	Application was verified using electronic kyc
0019	eKYC Pending	Application failed electronic kyc - call addfile to add documents for manual kyc verification

Meaningful names for each XML attribute can be located in the table below:

Field Name	Occurrence	Description
P1	Single Valued	Title
P2	Single Valued	Name
P3	Single Valued	Surname
P4	Single Valued	DateOfBirth (dd MMM yyyy)
P5	Single Valued	Gender
P6	Single Valued	CountryOfOrigin
P7	Multi Valued	Phone
P8	Multi Valued	Mobile
P9	Multi Valued	Email
P10	Multi Valued Address	AddressList
P11	Multi Valued	UDF
P12	Multi Valued Files	FileList
P13	Single Valued	UniqueID
I	Item in multivalued list
P10A	Item in multivalued address
R1	Single Valued	Type of Address
R2	Single Valued	Address Line 1
R3	Single Valued	Address Line 2
R4	Single Valued	City
R5	Single Valued	Postcode
R6	Single Valued	County
R7	Single Valued	Country
R8	Single Valued	Country Code ISO 3166-1-alpha-2 code
P12A	Item in multivalued File
S1	Single Valued	A BASE64STRING containing contents of file
S2	Single Valued	name of file

Sample communication between client and IDV for a new application Request Response

[Table of Contents]

Sending files in subsequent calls

A client might choose to send files for verification in subsequent api calls. To send file in subsequent calls the process api with an apisignature of AddFile

The data parameter requires an XML document similar to the sample below. The XSD for this XML can be found here.

<A xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <P13>CLA20130929145554480</P13>
  <P12>
    <P12A>
      <S1>contents of file in a BASE64STRING</S1>
      <S2>bankstatement.jpg</S2>
    </P12A>
    <P12A>
      <S1>contents of file in a BASE64STRING;</S1>
      <S2>reference.jpg</S2>
    </P12A>
    <P12A>
      <S1>contents of file in a BASE64STRING;</S1>
      <S2>electricitybill.jpg</S2>
    </P12A>
  </P12>
</A>

Note that P13 (uniqueid) should match the uniqueid sent in the NewApplication call for this application

Sample communication between client and IDV for adding a file to an existing application Request Response

[Table of Contents]

Receiving the results of the verification process

Once idvcheck processes an application an XML document is posted to the client at a URL submitted to the project manager at integration stage. The XML document will contain the data which was used during the verification stage together with the outcome of the verification. The outcome of the verification will be placed in field R. R can contain one of the following values:

• Approved
• Expired
• Fraud
• Pending
• KYCUpdated
• Sanctions

Only some of the above values of R might be returned to the client depending on the service on offer.

The client should return an HTTP Response of 200 if the posting was successful or 500 in case of an error. If idvcheck receives a status other than 200 it will retry submission after a short period until a response of 200 is received.

<A xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <P2>Matthew</P2>
  <P3>Smith</P3>
  <P4>09 Jun 1986</P4>
  <P13>CLA20130929145554480</P13>
  <P7>
    <I>+39 66599811</I>
  </P7>
  <P8>
    <I>+35699815754</I>
  </P8>
  <P9>
    <I>[email protected]</I>
  </P9>
  <P10>
    <P10A>
      <R1>Primary</R1>
      <R2>68, Block F</R2>
      <R3>Baker Street</R3>
      <R4>SomePlace</R4>
      <R5>PO143FD</R5>
      <R6 />
      <R7>United Kingdom</R7>
      <R8>GB</R8>
    </P10A>
  </P10>
  <P11>
    <I>57792A</I>
  </P11>
  <R>Approved</R>
</A>
        

Notes:

• that P12 is omitted from this reply
• The XML document is URLencoded
• The XML document is sent in a parameter called DATA
• The XSD for the XML document above can be found here

Sample communication between client and IDV for adding a file to an existing application Response Sent to Client Expected Reply

[Table of Contents]

Pending Status

If the status sent back by idv is the Pending status, further information about the application can be obtained by checking the UDF fields. The UDF fields can contain one of:

• Visa or Work permit required
• Suspicious docs
• Refer
• POA wrong format
• POA out of date range
• POA out of date
• POA out date
• POA ok, ID non-compliant
• POA ok, ID invalid
• POA ok, ID illegible
• POA non-comp
• POA internet copy
• POA incorrect details
• POA incorrect
• POA illegible
• No Match
• Missing dom photo page or POA stamp
• Missing back of ID
• ID, POA invalid
• ID or POA expired
• ID ok, POA out of date
• ID ok, POA not accepted
• ID ok, POA non-compliant
• ID ok, POA illegible
• ID not accepted, POA OK
• ID non-compliant, POA ok
• ID non-comp
• ID incorrect, POA non-compliant
• ID incorrect details
• ID incorrect
• ID illegible, POA ok
• ID illegible
• ID expired, POA ok
• ID expired
• ID doesn’t match application details, POA not accepted
• ID and POA incorrect
• ID and POA illegible
• ID and POA don’t match application details
• ID and POA discrepancy
• Fix
• False Match
• Alternative POA

Client can use the AddFile method (see Sending files in subsequent call) to send additional documentation for the application.

[Table of Contents]

Updating an application

If information about an application changes once an application is approved an update application call can be placed to update the information. To update an application call the process api with an apisignature of UpdateApplication The data parameter requires an XML document similar to the sample below. The XSD for this XML can be found here.

<A xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <P3>Whatever</P3>
  <P13>ClientA.20150908030741424</P13>
  <P8 ovr="y">
    <I>35361223501</I>
  </P8>
  <P9 ovr="y">
    <I>[email protected]</I>
  </P9>
  <P10 ovr="y">
    <P10A>
      <R1>Primary</R1>
      <R2>New Addy</R2>
      <R3>St Philip's Gate</R3>
      <R4>London</R4>
      <R5>none</R5>
      <R6 />
      <R7>Ireland</R7>
      <R8>IE</R8>
    </P10A>
  </P10>
</A>

Note that P13 (uniqueid) should match the uniqueid sent in the NewApplication call for this application

An update in the application information needs to be accompanied with the relevant documentation. The AddFile method (see Sending files in subsequent call) should be used to upload the relevant documents to idv

Once the application is approved the client will receive the status KYCUpdated. Please see section Receiving the results of the verification process on how to receive a response from idv.

0000    Successful
0001    Authentication Failed Check username/password
0002    Operation Failed
0003    Data Incorrect
0004    Application already exists (value of UniqueId field was used before)
0005    Files did not save      (Resend an addfileapi with file for the same uniqueid)
0007    Application does not exists  (Addfile or Updateapplication was submitted with a UniqueId field which was not sent previously)
0011    Application status does not allow to add file 
0012    File addition failed  (Resend an addfileapi with file for the same uniqueid)
0013    File base64 string is invalid (Please check that the file is being sent as a valid base 64 string)
0014    XML validation failed
0016    Invalid file extension 
0017    Error Connecting to eKYC service
0018    eKYC Approved
0019    eKYC Pending
0020    Sanctions - No Match
0021    Sanctions - Requires Investigation
0022    Error Connecting to Sanctions service