As the second step in verifying a user, a customer organisation needs to provide a link from their website to greenID’s website. The user will follow this link and begin the process of verifying their identity electronically.

Redirecting the user is a two-step process:

1. Receive a session token via the getOneTimeSessionToken web service
2. POST to the start page

Receiving a session token

Method Summary

The getOneTimeSessionToken method is used to obtain a unique, one time token that allows an individual with a particular userID and a particular customerID to be re-directed to the greenID web site. This is a security measure that prevents an attacker from executing a “replay” attack whereby they hijack a browser’s sessionID, and use that to view pages with data that do not belong to them. 

The token can be configured on a per-client basis. For example, it can have a configurable time-to-live, or it can never expire.

Method Signature

String getOneTimeSessionToken(String customerId,
                         String userId) 

Parameters

Return Value

This method will return a String object that is the value of the token. This must be included in the HTTP POST, discussed in the next section.

Faults

This method may raise a FaultDetails, inside which can be the following codes:

• SystemFault
• InvalidCustomerIdFault
• InvalidCertificateException

greenID allows customer organisations to perform an HTTPS POST or GET (though we recommend POST) to the starting page. Within the POST, greenID requires several parameters, which are the main subject of this page.

POSTing to the start page

URL to POST to

Test environment

The test URL to POST to is:

https://test.edentiti.com/verification/start.seam

Production environment

The production URL to POST to is:

https://www.edentiti.com/verification/start.seam

POST Variables

token 

The token is the unique, one-time token issued by the getOneTimeSessionToken method above. 

userId

The userId parameter is the customer organisation’s identifier for the user. This is the same value that was returned by whichever of the register Web Service methods was used. 

customerId

This parameter is greenID's identifier for the client application. The value is supplied by greenID

returnUrl

This is the URL to which the user will be redirected once they have completed the online identity verification process. This is invoked when the customer clicks the "Finish" button. If preferred, the customer can be automatically redirected to this URL upon completion of their verification session (just ask your greenID representative).

cancelUrl

This is the URL to which the user will be redirected if they leave the online identity verification process and are not yet verified.  This is the URL that will be used when the person chooses to leave the process via the "save & complete later"/"complete later" button on the greenID screen.

timeoutUrl

This is the URL to which the user will be redirected if they do not complete the online identity verification process within greenID’s session timeout period.

exceptionUrl

This is the URL to which the user will be redirected if an exception is encountered during the online identity verification process.

offlineOptionsUrl

This is an optional URL to which the user can be sent if they click on a custom button in the "Having trouble completing your verification?" section. An optional customisation, this can provide a way to differentiate between customers who click the default "save & complete later" button (and subsequently get sent to the cancelUrl) and those who wish to abandon electronic verification and try an offline/manual option.

ui

This is the name of a "skin" that can be selected based upon the value given to the ui paramter.  Please note that the skin names need to be pre-defined by greenID.

Previously Collected Personal Numbers

In some situations identifiing number may have already been obtained before the greenID system is invoked.  It is possible to include these numbers as additional POST variables in the data sent to start.seam.  This enables the greenID system to prepopulate more data in the data entry screens.  This is provided simply as a way of improving the user experience for the user.  For example if the user provides their drivers licence number as part of the product application process then it can be sent down to greenID and when the user clicks on the drivers licence check the number that they entrered previously is already prefilled.  Any of the data in these variables are only stored temparily in the session while the user is using the greenID system.   Below the names of these POST variables are listed.  

Australia

passport_number - the passport number, for australian passports (non-DVS)

actrego_number - the ACT drivers licence number (non-DVS)

warego_number - the WA drivers licence number (non-DVS)

sarego_number - the SA drivers licence number (non-DVS)

vicrego_number - the VIC drivers licence number (non-DVS)

nswrego_licenceNumber - the NSW drivers licence number (non-DVS)

nswrego_rtaNumber - the NSW drivers licence RTA number (non-DVS)

qldrego_number - the QLD drivers licence number (non-DVS)

actregodvs_licenceNumber - the ACT drivers licence number (DVS)

waregodvs_licenceNumber - the WA drivers licence number (DVS)

saregodvs_licenceNumber - the SA drivers licence number (DVS)

vicregodvs_licenceNumber - the VIC drivers licence number (DVS)

nswregodvs_licenceNumber - the NSW drivers licence number (DVS)

qldregodvs_licenceNumber - the QLD drivers licence number (DVS)

ntregodvs_licenceNumber - the NT drivers licence number (DVS)

tasregodvs_licenceNumber - the TAS drivers licence number (DVS)

visadvs_passportNumber - the passport number for non-australian passports (DVS)

passportdvs_number - the passport number, for australian passports (DVS)

medicare_number - the medicare number (non-DVS)

medicare_referenceNumber - the medicare reference number (non-DVS)

medibank_number - the medibank private membership number

visa_number - the passport number for non-australian passports (non-DVS)

New Zealand

nztadriverslicence_number - the NZ Driver Licence number

nztadriverslicence_versionNumber - the NZ Driver Licence version number

nzpassport_number - the NZ Passport number

About these URLs

Note that by default greenID will append the userId as a URL encoded parameter (GET request) to the any URL supplied, for example http://www.example.com/return.html will become http://www.example.com/return.html?userId=123.

This feature is not available for the timeoutUrl.  

greenID can turn this feature on and off on a per customer basis.

Example HTML

The HTML below is an example of a form that can be used to POST to greenID’s test server:

<form action="https://test.edentiti.com/verification/start.seam" method="post">  
 <input name="token" value="0987654321" type="hidden" />
 <input name="userId" value="123456" type="hidden" />
 <input name="customerId" value="59" type="hidden"/>
 <input name="returnUrl"  
 value="https://www.exampleorg.com/verification/return.html"  
 type="hidden" />
 <input name="cancelUrl"  
 value="https://www.exampleorg.com/verification/cancel.html"  
 type="hidden" />
 <input name="timeoutUrl"  
 value="https://www.exampleorg.com/verification/cancel.html"  
 type="hidden" />
 <input name="exceptionUrl"  
 value="https://www.exampleorg.com/verification/cancel.html"  
 type="hidden" />
 <input type="submit" value="Proceed" />  
</form>