• Save
Netverify implementation guide_v1_2_1
Upcoming SlideShare
Loading in...5
×
 

Netverify implementation guide_v1_2_1

on

  • 739 views

Addendum

Addendum

Statistics

Views

Total Views
739
Views on SlideShare
665
Embed Views
74

Actions

Likes
0
Downloads
0
Comments
0

1 Embed 74

http://gadgetsandinnovations.com 74

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Netverify implementation guide_v1_2_1 Netverify implementation guide_v1_2_1 Document Transcript

    • Netverify Implementation GuideThis guide is intended to provide clients with a reference manual andconfiguration guide for the Netverify product. This paper illustrates how toembed Netverify into your own page, to redirect to a customizable landingpage or to implement the Netverify API.Copyright:Jumio Inc. 1971 Landings Drive, Mountain View, CA 94043
    • ContentsNetverify Implementation Guide ............................................................................................... 1 Contents.................................................................................................................................. 2 Release notes ................................................................................................................. 3 Contact ........................................................................................................................... 3 Embed Netverify into your page ............................................................................................ 3 iFrame code to display your Netverify client ................................................................. 4 Configuration step 1: Setting the Jumio merchant API Token ........................................... 4 Configuration step 2: Adjusting the "locale" parameter .................................................... 4 Configuration step 3: Creating success/error URLs ............................................................ 4 Displaying information after redirecting the user ......................................................... 5 Callback........................................................................................................................... 5 Using Netverify redirect.......................................................................................................... 6 Customize your landing page ......................................................................................... 6 Call your landing page .................................................................................................... 7 Callback fields ............................................................................................................... 10 Netverify API ......................................................................................................................... 13 Authentication.............................................................................................................. 13 Perform Netverify......................................................................................................... 13 Initiate embedded Netverify ........................................................................................ 14 Initiate Netverify redirect ............................................................................................. 16 Global Netverify settings ...................................................................................................... 19 Setting server side parameters .................................................................................... 19 Scanning options .......................................................................................................... 20 Supported countries and documents........................................................................... 20 2
    • Release notesVersion Date Description1.2.1 2012-08-23 Improved user experience of landing page1.2.0 2012-08-17 Netverify API, time-limited token1.1.2 2012-07-18 Netverify redirect settings (e.g. localization), callback images1.1.1 2012-06-27 Header and footer image size, JS link for embedding1.1.0 2012-06-15 Netverify redirect solution1.0.2 2012-05-30 Added "idScanImageBackside" in callback1.0.1 2011-03-06 Introduced "showIntroductionText" parameter1.0.0 2011-03-01 Initial releaseContactIf you have any questions regarding our implementation guide please contactsupport@jumio.com.Embed Netverify into your page Important: Obtaining your personalized API tokenThe Netverify client contains your personal profile-specific API token (the"merchantAPItoken"), this token has to be provided in the code. Please log into your accounton www.jumio.com, the token can be found at the bottom of each page. The Netverify client 3
    • will NOT work without your API token. Please replace the parameter below with yourindividual token.iFrame code to display your Netverify clientCopy and paste the following script into your pages "<head>" section right before the"</head>":<script type="text/javascript" src="https://resources.netverify.com/widget/jumio-verify/1.0/iframe-script.js"></script><script type="text/javascript">/*<![CDATA[*/JumioClient.setVars({locale: "en",merchantAPIToken: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",merchantIdScanReference: "YOURIDSCANREFERENCE",cancelUrl: "https://yoursite.com/cancel",errorUrl: "https://yoursite.com/error",successUrl: "https://yoursite.com/success"}).initVerify("__jumio__iframe__clientcontainer__");/*]]>*/</script>To display the Netverify client, paste< div id = “__jumio__iframe__clientcontainer__" ></ div >in your html code where you want our Netverify client to appear.Configuration step 1: Setting the Jumio merchant API TokenFirst, you need to update the "xxx" in the sample below with your own Jumio merchantaccount API token. You find this token on the bottom of each page in your merchant login.merchantAPIToken : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"Configuration step 2: Adjusting the "locale" parameterIt is possible to change the interface language of the Netverify client by modifying the"locale" parameter. At the moment you can choose between "de" (German), "en_GB"(British Englisch) and "en" (American English).locale : "en"Configuration step 3: Creating success/error URLsWhen the ID check is completed the user will be redirected to a specified page. Please makesure you create your own information / follow up pages for success and error. The URLs tothese events need to be configured as described below.successUrlThe user will be redirected to the specified URL after the ID was successfully verified – or ifno success URL is specified the user will be redirected to Jumio’s default successUrl . ThisURL can be configured in the merchant settings page on the Jumio website or you can use 4
    • the successURL parameter. If both are specified then this parameter will override themerchant settings page.errorUrlUpon error the user will be redirected to this page where an error message can be displayed.Displaying information after redirecting the userIf you want to display verification information on the redirected pages, you can do that bysimply using the following parameters, which are also attached to the redirect URL as querystring parameters:idScanStatusSUCCESS or ERRORmerchantIdScanReferenceYour ID scan reference numberjumioIdScanReference:Jumio’s reference number for each scanThe link below shows an example of a URL the end user will be redirected to:https://www.yoursite.com/intranet/verify/success.php?merchantIdScanReference=13107873416&idScanStatus=SUCCESS&jumioIdScanReference=2465941f-b153-4287-84b9-13def3e982a8Tip: It is also possible to set all of the following URLs to the same address, because you canget the status from the URL’s query parameter "idScanStatus".CallbackIf you want to track scans on the server side, you can use callback fields. See chapterCallback fields. 5
    • Using Netverify redirectCustomize your landing pageIn the Jumio Settings page in your merchant backend you can customize and brand yourredirect page:Domain name prefixAs a first step, define your domain name prefix for the URL of your landing page. Yourindividual site will be accessible under [your-domain-prefix].netverify.com.Allowed characters: A-Z, a-z, "-", "."Header image, footer imageIn order to have your own look and feel you can provide header and footer images.All together the file size must not exceed 5 MB.Size header: Horizontal 800 px, vertical 100 pxSize footer: Horizontal 800 px, vertical 60 pxLabel text for (available) customerIDThese two mandatory label texts specify how you identify the customer and how the user isregistered on your system. You can use for example an email address, user name or accountnumber.The first label is used for the customer identification input field on your landing page.If you pass the customer ID to the landing page, the second label will be displayed above thecustomer ID (see Call your landing page).Default localeNetverify redirect is available in English, English (United Kingdom) and German by selectingthe appropriate locale from the list.Max. attempts per customer (0 for unlimited):In addition, you can restrict the maximum attempts per customer. A parameter will bepassed to the error page if the limit is exceeded. 6
    • Call your landing pageYou can place the URL of your landing page (https://[your-domain-prefix].netverify.com/) as a linkon your web page or include it in emails.If you already know the customer name, you can straightaway pass the customer to the URL.Find below a list of optional parameters:customerID Identifies the customer on the merchants systemfirstname The customer‘s first namelastname The customer‘s last namemerchantAPIToken Identifies the merchantmerchantIdScanReference Identifies the merchant’s ID verificationFor example, to verify "John Doe" as the owner of the account with thecustomerID="john@doe.com", you provide this link to the customer:https://[your-domain-prefix].netverify.com/?firstname=John&lastname=Doe&customerID=john@doe.com 7
    • If you only specify the first name and last name, the user will be required to enter thecustomer ID:https://[your-domain-prefix].netverify.com/?firstname=John&lastname=Doe 8
    • If you specify the customer ID the user can immediately start the verification process:https://[your-domain-prefix].netverify.com/?customerID=john@doe.comWithout a parameter the user has to specify the customer id:https://[your-domain-prefix].netverify.com/Additionally, the merchant API token to identify a merchant and merchantIdScanReferenceto identify the verification are supported parameters. This information is passed on to thecallback, so you can associate the callback with the verification.https://[your-domain-prefix].netverify.com/?merchantAPIToken=[your-api-token]https://[your-domain-prefix].netverify.com/?merchantIdScanReference=[your-id-for-this-verification] 9
    • Callback fieldsIf you want to track scans server side, you can use these fields returned in the callback. The field value sometimes depends on the verificationStatus. Approved and verified Fraud Unsupported ID type Unsupported country Name mismatch Not readable No ID uploadedcallBackType NETVERIFYID NETVERIFYID NETVERIFYID NETVERIFYID NETVERIFYID NETVERIFYID NETVERIFYIDclientIp IP address of the client IP address of the client IP address of the client IP address of the client IP address of the client IP address of the client IP address of the clientidCheckDataPositions OK N/A N/A N/A N/A N/A N/AidCheckDocumentValidation OK N/A N/A N/A N/A N/A N/AidCheckHologram OK N/A N/A N/A N/A N/A N/A OK when idType=PASSPORT, N/AidCheckMRZcode N/A N/A N/A N/A N/A N/A otherwiseidCheckMicroprint OK N/A N/A N/A N/A N/A N/AidCheckSecurityFeatures OK N/A N/A N/A N/A N/A N/AidCheckSignature OK N/A N/A N/A N/A N/A N/A ISO 3166-1 alpha 3 ISO 3166-1 alpha 3 ISO 3166-1 alpha 3 ISO 3166-1 alpha 3 ISO 3166-1 alpha 3 ISO 3166-1 alpha 3idCountry ISO 3166-1 alpha 3 country code country code country code country code country code country code country codeidScanStatus SUCCESS ERROR ERROR ERROR ERROR ERROR ERRORidType The ID type (*1) The ID type (*1) The ID type (*1) The ID type (*1) The ID type (*1) - - Jumio’s reference Jumio’s reference Jumio’s reference Jumio’s reference Jumio’s reference Jumio’s referencejumioIdScanReference Jumio’s reference number for each scan number for each scan number for each scan number for each scan number for each scan number for each scan number for each scanmerchantIdScanReference Your ID scan reference Your ID scan reference Your ID scan reference Your ID scan reference empty Your ID scan reference Your ID scan reference DENIED_UNSUPPORTE DENIED_UNSUPPORTE DENIED_NAME_MISM ERROR_NOT_READABLverificationStatus APPROVED_VERIFIED DENIED_FRAUD NO_ID_UPLOADED D_ID_TYPE D_ID_COUNTRY ATCH E_ID The ID of the client as The ID of the client as The ID of the client as The ID of the client as - provided by the provided by the provided by the provided by the The ID of the client as provided by the merchant through a merchant through a merchant through a merchant through acustomerId merchant through a URL parameter or as - URL parameter or as URL parameter or as URL parameter or as URL parameter or as entered by the client (*4) entered by the client entered by the client entered by the client entered by the client (*4) (*4) (*4) (*4) The first name of the The first name of the The first name of the The first name of the -idFirstName The first name of the client - client (*4) client (*4) client (*4) client (*4)idLastName The last name of the client The last name of the The last name of the The last name of the The last name of the - - 10
    • client (*4) client (*4) client (*4) client (*4)idDob Date of birth in the format yyyy-mm-dd - - - - - -idExpiry Date of expiry in the format yyyy-mm-dd - - - - - - Identification number of the scanned -idNumber - - - - - document URL to the image of the ID scan. HTTPS - Basic Authentication is required to access this image. Please use your merchant APIidScanImage token as "userid" and your API secret as - - - - - "password". The API secret can be found in the Settings page of your Jumio account under Change Credentials. (*2) URL to the image of the ID scan. HTTPS - Basic Authentication is required to access this image. Please use your merchant APIidScanImageBackside token as "userid" and your API secret as - - - - - "password". The API secret can be found in the Settings page of your Jumio account under Change Credentials. (*3)(*1) Supported ID types: PASSPORT, DRIVING_LICENSE, ID_TYPE.(*2) For document types that are configured to support separate scan of the front-side and backside this is the front side.(*3) For document types that are configured to support separate scan of the front-side and backside this is the back side(*4) Netverify redirect parameter 11
    • JSON callback example"{ "callBackType":"NETVERIFYID", "clientIp":"127.0.0.1", "customerId":"john@doe.com", "idCheckDataPositions":"OK", "idCheckDocumentValidation":"OK", "idCheckHologram":"OK", "idCheckMRZcode":"N/A", "idCheckMicroprint":"OK", "idCheckSecurityFeatures":"OK", "idCheckSignature":"OK", "idCountry":"AUT", "idDob":"1988-12-31", "idExpiry":"2022-09-08", "idFirstName":"John", "idLastName":"Doe", "idNumber":"987654321", "idScanImage":"https://localhost.jumio.com/recognition/v1/idscan/ea766682-33d7-4c3e-aad5-26bc2bc2df12/frontside", "idScanImageBackside":"https://localhost.jumio.com/recognition/v1/idscan/ea766682-33d7-4c3e-aad5-26bc2bc2df12/backside", "idScanStatus":"SUCCESS", "idType":"DRIVING_LICENSE", "jumioIdScanReference":"ea766682-33d7-4c3e-aad5-26bc2bc2df12", "verificationStatus":"APPROVED_VERIFIED"}" 12
    • Netverify APIAuthenticationEvery processing API call is protected. To access it use HTTP Basic Authenticationwith your Jumio merchant API token and your API secret as userid and password. Once youare logged in, the merchant API token can be found at the bottom of each page onwww.jumio.com. The API secret is provided on the Settings page under Change Credentials.Perform NetverifyJumio offers performNetverify for merchants needing a RESTful solution for ID verificationwithout a Jumio hosted user interface.The merchant simply sends a JSON request with the ID picture and immediately receives aJSON response with a scan reference and a timestamp. The authorized requester will receivethe callback after the verification is completed (see chapter Callback fields).All you have to do is send a HTTP POST to the URL below with JSON parameters to send theID image for verification. Note: Set "accept: application/json" and "content-type:application/json" in the "header" section of your request.REST URL: https://pay.jumio.com/api/netverify/v1/performNetverifySample requestPOST http://pay.jumio.com/api/netverify/v1/performNetverify HTTP/1.1Accept: application/jsonAuthorization: BasicContent-Type: application/jsonContent-Length: 3602791Host: localhost{"merchantApiToken":"4b2adbfc-fb19-4d39-9e79-e2924809fb11","merchantIdScanReference":"1345112750576","frontsideImage":"<binary>"}Sample response{"timestamp": "2012-08-16T10:37:44.623Z", "jumioIdScanReference": "fec40091-76aa-434a-8f01-bbec46d40168"} 13
    • Request parameter Parameter Type Mandatory Possible values or commentsmerchantAPIToken String (GUID) y Your merchant API token To define which fields are mandatory to process during the ID scan and to overrideenabledFields String n the default setting from the Jumio’s merchant settings. Possible fields are: idNumber,idFirstName,idLastName,idDob,idExpiry,idUsStatemerchantIdScanReference String y Merchant’s reference number for each scanmerchantReportingCriteria String n An optional text field for filters in merchant reportscustomerId String n Identification of the customer Callback URL after the verification is completed. This setting overrides the defaultcallbackUrl String n Jumio’s merchant settings (no ports are allowed in the string). Callback email after the verification is completed. This setting overrides the defaultcallbackEmail String n Jumio’s merchant settings.firstName String n First namelastName String n Last namecountry String n ISO 3166-1 alpha 3 country codeusState String n ISO 3166 2 US codeexpiry Date n Expiration datenumber String n Document numberidType String n PASSPORT, DRIVING_LICENSE, ID_CARDdob Date n Date of birthfrontsideImage Picture y Base64 encoded image of ID front sidefrontsideImageMimeType String n Mime type of front side image. Default: image/jpegbacksideImage Picture n Base64 encoded image of ID back sidebacksideImageMimeType String n Mime type of back side image. Default: image/jpeg Default: onFinishcallbackGranularity Enum n onFinish: Callback is only sent after the whole verification onAllSteps: Callback is sent after recognition and verificationResponse parameter Name Type Possible values or commentsjumioIdScanReference String (GUID) Jumio’s reference number for each scantimestamp Date Timestamp of the responseInitiate embedded NetverifyIf you are using embedded Netverify (see chapter Embed Netverify into your page) you canadd additional security features by initiating your Netverify with our RESTful API interface.The merchant calls initiateNetverify and receives an authorization token. The generatedauthorization token determines the authenticity of the merchant and is valid for a certainamount of time only.To receive the authorization token call the RESTful API with the parameters below. Note: Set"accept: application/json" and "content-type: application/json" in the "header" section ofyour request.REST URL: https://pay.jumio.com/api/netverify/v1/initiateNetverify 14
    • Sample requestPOST http://pay.jumio.com/api/netverify/v1/initiateNetverify HTTP/1.1Accept: application/jsonAuthorization: BasicContent-Type: application/jsonContent-Length: 706Host: localhost{"merchantApiToken":"4b2adbfc-fb19-4d39-9e79-e2924809fb11","merchantIdScanReference":"1345112750576","enabledFields":"idNumber,idFirstName,idLastName,idDob,idExpiry,idUsState","authorizationTokenLifetime":"600","merchantReportingCriteria":"merchantReportingCriteria","successUrl":"http://your-success-url.com","errorUrl":" http://your-error-url.com ","callbackUrl":" http://your-callback-url.com ","callbackEmail":"your-callback@email.com","locale":"de","clientIp":"10.10.0.26","customerId":"customerId","firstName":"firstName","lastName":"lastName","country":"USA","usState":"TX","expiry":"2013-07-25T22:00:00Z","number":"number","dob":"1990-01-01T22:00:00Z","idType":"DRIVING_LICENSE"}Sample response{"jumioIdScanReference": "5b1fbc37-8663-4337-8942-f1276480bf87""authorizationToken": "45ab3966-aae3-4013-ac0a-e86321e9b7e0","timestamp": "2012-08-16T10:27:29.494Z",} 15
    • Request parameter Name Type Mandatory Possible values or comments StringmerchantAPIToken y Your merchant API token (GUID) To define which fields are mandatory to process during the ID scan and to override theenabledFields String n default setting from the Jumio’s merchant settings. Possible fields are: idNumber,idFirstName,idLastName,idDob,idExpiry,idUsState Time in seconds until the authorizationToken expires. Default is 300 seconds.authorizationTokenLifetime integer n 0: authorizationToken never expiresmerchantIdScanReference String y Merchant’s reference number for each scanmerchantReportingCriteria String n An optional text field for filters in merchant reports Redirect URL in case of success. This setting overrides the default Jumio’s merchantsuccessUrl String n settings (no ports are allowed in the string). Redirect URL in case of error. This setting overrides the default Jumio’s merchant settingserrorUrl String n (no ports are allowed in the string). Callback URL after the verification is completed. This setting overrides the default Jumio’scallbackUrl String n merchant settings (no ports are allowed in the string). Callback email after the verification is completed. This setting overrides the defaultcallbackEmail String n Jumio’s merchant settings. Locale of the Netverify client: "de" (German), "en_GB" (British Englisch) and "en"locale String n (American English). This setting overrides the Jumio’s merchant settings or the default value "en".clientIp String n IP address of the customercustomerId String n Identification of the customerfirstName String n First namelastName String n Last namecountry String n ISO 3166-1 alpha 3 country codeusState String n ISO 3166 2 US codeexpiry Date n Expiration datenumber String n Document numberdob Date n Date of birthidType String n PASSPORT, DRIVING_LICENSE, ID_CARDResponse parameter Name Type Possible values or commentsjumioIdScanReference String (GUID) Jumio’s reference number for each scanauthorizationToken String (GUID) The token which is valid until the authorizationTokenLifetimetimestamp Date Timestamp of the responseInitiate Netverify redirectIf you implement Netverify redirect (see chapter Using Netverify redirect) you can addadditional security features by initiating your Netverify with our RESTful API interface. UsinginitiateNetverifyRedirect, the server will issue a redirect URL useable for a certain amount oftime to authorize the verification requests.Call the RESTful API with the parameters below. Note: Set "accept: application/json" and"content-type: application/json" in the "header" section of your request. 16
    • REST URL: https://pay.jumio.com/api/netverify/v1/initiateNetverifyRedirectSample requestPOST http://pay.jumio.com/api/netverify/v1/initiateNetverifyRedirect HTTP/1.1Accept: application/jsonContent-Type: application/jsonContent-Length: 674Host: localhost{"merchantApiToken":"4b2adbfc-fb19-4d39-9e79-e2924809fbde","merchantIdScanReference":"1345112754818","enabledFields":"idNumber,idFirstName,idLastName,idDob,idExpiry","authorizationTokenLifetime":"4320","merchantReportingCriteria":"merchantReportingCriteria","successUrl":"http://your-success-url.com","errorUrl":" http://your-error-url.com ","callbackUrl":" http://your-callback-url.com ","callbackEmail":"your-callback@email.com","locale":"de","clientIp":"10.10.0.26","customerId":"1345112754818","firstName":"firstName","lastName":"lastName","country":"USA","usState":"TX","expiry":"2013-07-25T22:00:00Z","number":"number","dob":"1990-01-01T22:00:00Z","idType":"DRIVING_LICENSE"}Sample clientRedirectURLhttps://[your-domain-prefix].netverify.com/?authorizationToken=ae7ca41c-d07e-4fdb-a51d-18b6e58eefa0Request parameter Parameter Type Mandatory Possible values or comments StringmerchantAPIToken y Your merchant API token (GUID) To define which fields are mandatory to process during the ID scan and to override theenabledFields String n default setting from the Jumio’s merchant settings. Possible fields are: idNumber,idFirstName,idLastName,idDob,idExpiry,idUsState Time in seconds until the authorizationToken expires. Default is 300 seconds.authorizationTokenLifetime integer n 0: authorizationToken never expiresmerchantIdScanReference String y Merchant’s reference number for each scanmerchantReportingCriteria String n An optional text field for filters in merchant reports Redirect URL in case of success. This setting overrides the default Jumio’s merchantsuccessUrl String n settings (no ports are allowed in the string). Redirect URL in case of error. This setting overrides the default Jumio’s merchant settingserrorUrl String n (no ports are allowed in the string). Callback URL after the verification is completed. This setting overrides the default Jumio’scallbackUrl String n merchant settings (no ports are allowed in the string). Callback email after the verification is completed. This setting overrides the defaultcallbackEmail String n Jumio’s merchant settings. 17
    • Locale of the Netverify client: "de" (German), "en_GB" (British Englisch) and "en"locale String n (American English). This setting overrides the Jumio’s merchant settings or the default value "en".clientIp String n IP address of the customercustomerId String y Identification of the customerfirstName String n First namelastName String n Last namecountry String n ISO 3166-1 alpha 3 country codeusState String n ISO 3166 2 US codeexpiry Date n Expiration datenumber String n Document numberdob Date n Date of birthidType String n PASSPORT, DRIVING_LICENSE, ID_CARDResponse parameter Parameter Type Possible values or commentsjumioIdScanReference String (GUID) Jumio’s reference number for each scanauthorizationToken String (GUID) The token which is appended in the clientRedirectUrl and valid until the authorizationTokenLifetimetimestamp Date Timestamp of the responseclientRedirectUrl String The redirect URL for the customer 18
    • Global Netverify settingsThese settings are relevant for both integration types, embedding and redirecting.Setting server side parametersIn the Jumio Merchant Settings page you can customize Netverify.Callback URLIf you want to track the scans on the server side, you can specify a callback URL in yoursettings. Once you have set this callback URL, Jumio will post the status of your scans to thisspecified URL.Note: The callback from Jumio is the authoritative answer for the status of verification. The redirection URLscan be manipulated on the client side and must not be used confirming the success or error of a verification.Callback emailIf you want to get an email with scanning details, you can specify an email address.Success/Error URLThe client will be redirected to this URL in case of success or error. This setting can beoverridden by the embedded Netverify parameter "successUrl" or "errorUrl". 19
    • Scanning optionsYou can choose fields which should not be processed during the ID scan. Thesecorresponding fields are also not included in the callback if they are not selected.Supported countries and documentsYou can restrict countries and document types for Netverify processing. Any requestincluding a non-checked country or a non-checked ID type will be rejected. The default setupbelow shows countries and documents supported by Jumio. 20