Hints & Tips v1.1 17/10/08

Useful information for developers using the public API

  • All calls to the public API must have a Gateway Token with them apart from GetAverageTransactionTimes. The URL for the token service is: https://secure.dev.gateway.gov.uk/soap/2007/02/sts/GatewayTokenService.ashx
  • The above URL must be used as exactly as above and must be capitalised (as shown above)
  • When preparing the Token Request XML you must not introduce any whitespace into the <Base> element (see example xml, TokenTemplate.xml)
  • The following elements must be populated for each request for a token:
 

Element name

Format

Explanation

<wsu:Created> (in the Timestamp element)

XML date type (ex. 2008-05-21T12:22:30Z )

Current date/time when the message was created

<wsu:Expires>

XML date type (ex. 2008-05-21T12:22:30Z )

Future date/time when the message expires

<wsse:Username>

Non specific

----

<wsse:Password>

Password Digest

Digest process

<wsse:Nonce>

Unique value (base64’d)

A suitably unique value that is Base64’d

<wsu:Created> (in the UsernameToken element)

XML date type (ex. 2008-05-21T12:22:30Z )

Current date/time when the message was created

<wsu:Expires>

XML date type (ex. 2008-05-21T12:22:30Z )

Future date/time when the message expires

NB: All timestamps must be in GMT, the gateway servers do not account for BST (British Summer Time)

  • If you have to create the password digest manually, follow the below process:

Using the ‘testing1’ password for this example:

Hashed/Base64 encoded password must first be created

1. Password string must first be made lowercase.

2. The lowercase password must then be MD5 hashed; the output of this operation must be an array of bytes.

3. Byte array must then be base64 encoded, for ‘testing1’ this will give the result: a3MweCsv60kkAgzEpXeCqQ==

The encoded password and two other elements from the token must then be concatenated, the resulting byte array must then be SHA-1’d and Base 64’d.

Password Digest = Base64 ( SHA-1 (Nonce + Created + Password))

The end result will be different every time, however there is an example of a correctly calculated digest in the TokenRequest.xml example provided in the techpack.

  • The actual request for the token must be a HTTP 1.1 request. The following HTTP headers must be set:

    Content-Type = text/xml
    SOAPAction = http://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
    Method = POST
  • Once you have a token it can be used to make calls to the public API is:
    https://secure.dev.gateway.gov.uk/soap/2007/02/Public/Public.asmx
  • There is an example of the XML generated by a standard SOAP toolkit using the WSDL file available at the URL above in the techpack (GetUserDetailsRequest.xml).
  • Make sure the namespaces in the XML file you generate match the ones in the example above
  • Make sure the endpoint you are sending the calls to is secure.dev (the endpoint in the WSDL file is just secure.gateway so you will have to manual override this for testing
  • The Gateway token should inserted into the <Security> element in the <Header>
  • Do not tamper with the Gateway token at all it must be inserted in exactly the same format it was delivered to you in the token response (example files TokenResponse.xml and Token.xml in the techpack)