Skip to main content

SOAP API reference

This API uses SOAP. The API authorisation framework is Client authenticated TLS.

The intended audience of this document is software developers who wish to implement this web API in their software.

Download Sample Code

Quick start

  1. Qvalent implementation consultant creates an iLink test account for the customer's technical contact.
  2. Customer contact completes iLink connectivity form in test iLink.
  3. Customer develops SOAP connectivity solution. See Upload File Service and Download Files Service.
  4. Qvalent implementation consultant configures file routing.
  5. Customer undertakes testing in the test environment.
  6. Once customer is satisfied that testing is complete a sign off email is required to progress into production.
  7. Qvalent implementation consultant creates an iLink production account for the customer's technical contact.
  8. Customer contact completes iLink connectivity form in production iLink.
  9. Qvalent implementation consultant configures file routing.
  10. Customer tests the SOAP connection in the live environment.
  11. Once this testing is successful customers can perform low value live testing of the other Westpac products that are being implemented.

Requirements

To use the Westpac SOAP file transfer services, you will need a SOAP client that supports the following standards:

Your SOAP library should also be able to generate client side stubs to simplify your coding.

Environment URL
Test Web Interface https://ilink.support.qvalent.com
Production Web Interface https://ilink.westpac.com.au
Test API Base URL https://ws.support.qvalent.com/services/messaging
Production API Base URL https://ws.qvalent.com/services/messaging

In the early stages of your Westpac project you will be asked to provide the contact details of the IT person who will be responsible for setting up your connection.

Once these details are received you will be provided with an iLink login to enter your IP addresses.

The iLink connectivity process has the following steps:

  1. The Qvalent implementation consultant will provide the user's technical contact with a login to the iLink test instance.
  2. Fill in the setup connectivity form and submit.
  3. Notify your Qvalent and Westpac implementation managers that you have completed the connectivity form.
  4. The Qvalent implementation consultant will configure the file routing and notify all stakeholders when this is done.
  5. User to send and receive test files to confirm the connection.
  6. Once the Qvalent implementation consultant has received confirmation that all relevant testing has been completed steps 1 - 5 will need to be repeated in the production environment.

Setup connectivity form

To setup your connectivity, click the Connectivity menu option at the top of the screen, then click the Setup connectivity button.

The Setup connectivity page will be displayed where you can enter the following details:

  • Contact emails - Add any additional email addresses that should receive connectivity related emails.
  • PGP key - Upload your PGP key here.
  • IP addresses - The iLink solution has a white list of IP addresses accepted for each user. Users need to provide the IP address or addresses that their incoming requests will be coming from, this is the external IP address taking into account any proxy servers or other externally facing network infrastructure. This can be found by logging on to iLink on your server and taking the browser address shown in the IP addresses section of the connectivity form.

After you click Save, you will be able to access the Connectivity details page containing the following information:

  • Westpac's keys - This is the public key that you will need to use to decrypt the files you receive from iLink. This will only be displayed if encryption is enabled.
  • Your keys - You can use these fields during testing to confirm which keys you have loaded into iLink. This will only be displayed if encryption is enabled.
  • Your credentials - The download queue ID will be included in your SOAP requests. This section also contains the details of the client certificate that you will use to authenticate with the iLink server.
  • IP addresses - Lists the IP addresses allowed to access this connectivity.

Upload file service

The Upload file service allows you to upload a file to Westpac with associated metadata.

Request

POST /UploadFile

Parameter Name Format Description
fileID string Optional. The unique identifier for this file. If present, this value must be unique for each file sent. If you cannot generate a unique identifier for each file, you should omit this parameter.
If you do not know whether a file was transmitted successfully, you can resend it with the same fileID. iLink will only process the fileID once. If the same fileID is received again, the file will be ignored by iLink.
fileType string Optional. This value should be used if you send different file types to iLink. Your Westpac representative will provide the values you should use. If you only send one type of file, you can omit this parameter.
mimeType string Optional. The MIME type for the file if known, e.g. text/plain.
fileName string Optional. The name of the file uploaded if known, e.g. directEntry20180801.txt.
parameter string Optional. Arbitrary meta-data parameter relating to this message. Normally you will only provide this information if your Westpac representative requests it. Each parameter is a name-value pair containing additional meta-data.
fileContent base64 encoded file content Required. The file contents encoded using base64.

Example

POST /services/messaging/UploadFile HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: ""
Host: ws.qvalent.com:443
Content-Length: 429

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><uploadFile xmlns="http://www.qvalent.com/soap/namespace/messaging/UploadFile"><fileID>2452357634542635</fileID><fileType>TEST1</fileType><fileName>test1.txt</fileName><fileContent>VGhpcyBpcyBhIHRlc3QgZmlsZQ==</fileContent></uploadFile></s:Body></s:Envelope>

Response

If the upload succeeds, an empty response message will be received.

If a certificate authentication error occurs, a HTTP 403 response will be received.

If any other error occurs, a HTTP 500 response will be received containing a SOAP fault.

Example

HTTP/1.1 200 OK
Content-Type: text/xml
Date: Thu, 20 Aug 2009 02:15:06 GMT
Transfer-Encoding: chunked

f1
<SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header/><SOAP-ENV:Body><qv:uploadFileResponsexmlns:qv="http://www.qvalent.com/soap/namespace/messaging/UploadFile"/></SOAP-ENV:Body></SOAP-ENV:Envelope>
0

Download files service

The Download files service allows you to download any pending files with associated meta-data.

Request

POST /DownloadFiles

Parameter Name Format Description
queueID string The unique identifier for queue to fetch files from. Your Westpac representative will provide you with this value.

Example

POST /services/messaging/DownloadFiles HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: ""
Host: ws.support.qvalent.com:443
Content-Length: 320

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><downloadFiles xmlns="http://www.qvalent.com/soap/namespace/messaging/DownloadFiles"><queueID>nathan2</queueID></downloadFiles></s:Body></s:Envelope>

Response

If a certificate authentication error occurs, a HTTP 403 response will be received.

If any other error occurs, a HTTP 500 response will be received containing a SOAP fault.

Otherwise, the response will contain a number of file elements. If no messages were pending for you to download, no file elements will be present in the response. Each file element contains the following information.

Parameter Name Format Description
fileID string The unique identifier for this file. This value will be unique for each file you download and you can use this value for duplicate checking.
fileType string This value will be present if you receive file types from Westpac. Your Westpac representative will inform you of the applicable values (if any).
mimeType string The MIME type for the file if known, e.g. text/plain.
fileName string The name of the file uploaded if known, e.g. directEntry20180801.txt.
parameter string Arbitrary meta-data parameter relating to this message. Normally you will only receive this information if you have discussed it with your Westpac representative.
fileContent base64 encoded file content The file contents encoded using base64.

Example

HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8
Date: Thu, 20 Aug 2009 02:15:07 GMT
Transfer-Encoding: chunked

1b4
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><ns0:downloadFilesResponse xmlns:ns0="http://www.qvalent.com/soap/namespace/messaging/DownloadFiles"><ns0:file><ns0:fileID>e82fc567000001233596013b00002800</ns0:fileID><ns0:fileType>TEST1</ns0:fileType><ns0:fileName>test1.txt</ns0:fileName><ns0:fileContent>VGhpcyBpcyBhIHRlc3QgZmlsZQ==</ns0:fileContent></ns0:file></ns0:downloadFilesResponse></s:Body></s:Envelope>
0

Note that if a network error occurs while you are downloading the files, the same files will be sent to you again next time you make a download files request. However, if an error occurs in your system after you have received the files but before you have saved them to permanent storage, you will need to contact Westpac to resend the applicable files.

Note that not all the pending files may be sent to you in the download files response due to size restrictions. You should keep polling the Download Files Service until you receive an empty response. This will ensure that you receive all pending files in a timely fashion. The following pseudo-code demonstrates this approach:

  1. Send Download Files request and receive response.
  2. If the response contains no files, stop.
  3. Otherwise, process the files in the response and repeat from step 1.

Developer pack

The developer pack includes sample code for .NET and Java. It also contains WDSL and XSD files.

Download Developer Pack

The developer pack includes sample code for .NET and Java. This sample code gives you an idea of what is required to send and receive files using these two languages. The code is commented with TODO when you need to provide additional information before the sample code will work.

Protecting your certificate

Your certificate file is used to authorise your requests to the iLink server. Do not give your certificate file to anyone. Never email your certificate in clear text. Always use a secure method to copy your certificate file to your server.

.NET sample code

Enter the following information before you can use the .NET sample code:

  • Your certificate's common name.
  • A unique identifier for each uploaded file.
  • A file name for each uploaded file.
  • The location of the file contents to upload.
  • Your download queue ID.

You also need to install your certificate into the machine's certificate store and extract the common name:

  1. Open a Command Prompt window.
  2. Type mmc and press the ENTER key. Note that to view certificates in the local machine store, you must be in the Administrator role.
  3. On the File menu, click Add/Remove Snap In.
  4. Click Add.
  5. In the Add Standalone Snap-in dialog box, select Certificates.
  6. Click Add.
  7. In the Certificates snap-in dialog box, select Computer account and click Next.
  8. In the Select Computer dialog box, click Finish.
  9. In the Add Standalone Snap-in dialog box, click Close.
  10. On the Add/Remove Snap-in dialog box, click OK.
  11. In the Console Root window, click Certificates (Local Computer) to view the certificate stores for the computer.
  12. Optional. On the File menu, click Save or Save As to save the console file for later reuse. Install Certificates in Windows
  13. Expand Certificates (Local Computer) and right-click Personal then select All Tasks then Import....
  14. In the Certificate Import Wizard click Next.
  15. Press Browse and select the .pfx certificate file you downloaded then click Next.
  16. Enter the certificate password and click Next.
  17. Click Next then click Finish.
  18. In the Console Root window, expand Personal then left click Certificates. Check that your certificate is displayed in the list.

Java sample code

You need to enter the following information before you can use the Java sample code:

  • The file path to the .jks certificate file you saved.
  • The password for your certificate file.
  • A unique identifier for each uploaded file.
  • A file name for each uploaded file.
  • The location of the file contents to upload.
  • Your download queue ID.
Privacy Statement

Privacy Statement (for individuals whose personal information may be collected - in this clause referred to as "you"). All personal information we collect about you is collected, used and disclosed by us in accordance with our Privacy Statement which is available at Privacy Statement or by calling us through your relationship manager or Westpac representative. Our Privacy Statement also provides information about how you can access and correct your personal information and make a complaint. You do not have to provide us with any personal information but, if you don't, we may not be able to process an application or a request for a product or service.