SOAP File Transfer Specification
Version 1.4 1-Sep-2015
SOAP File Transfer – Specification
Date
Version
Description
18-Aug-2009
1.0
Original Version
30-Aug-2010
1.1
Added section on sample code
30-Jun-2011
1.2
Added FAQ section
03-Jul-2015
1.3
iLink administration documentation added
01-Sep-2015
1.4
Updated for new layout
Page 2
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Table of Contents 1
Introduction ..................................................................................................... 4
2
Quick Start ....................................................................................................... 5
3
Requirements ................................................................................................... 6
4
iLink connectivity setup .................................................................................... 7
5
Upload File Service ........................................................................................... 9
5.1
Upload File Request ............................................................................................ 9
5.2
Upload File Response.......................................................................................... 9
6
Download Files Service ..................................................................................... 9
6.1
Download Files Request ...................................................................................... 9
6.2
Download Files Response .................................................................................. 10
7
Sample Code ................................................................................................... 11
7.1
Protecting Your Certificate ................................................................................. 11
7.2
.NET Sample Code ........................................................................................... 11
7.3
Java Sample Code............................................................................................ 12
Appendix A – Upload File Example ....................................................................... 13 HTTP Request .......................................................................................................... 13 HTTP Response ........................................................................................................ 13 Appendix B – Download Files Example ................................................................. 14 HTTP Request .......................................................................................................... 14 HTTP Response ........................................................................................................ 14 Appendix C – Westpac HTTPS addresses .............................................................. 15 Test Environment ..................................................................................................... 15 Production Environment ............................................................................................ 15 Appendix D – FAQ ................................................................................................ 16
Page 3
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
1
Introduction
This document defines Westpac’s WIBS SOAP file transfer protocol. The SOAP file transfer protocol allows partners to transfer files securely and reliably over the internet. It provides a standard mechanism for transport using existing infrastructure (such as web servers, proxy servers and firewalls). Communication uses standard TCP/IP ports to prevent the need for network changes. SSL is used to provide encryption of data between partners, and authorisation assures the identity of each partner. The intended audience of this document are software developers who wish to implement this messaging protocol. Knowledge of SOAP, HTTP and SSL is assumed. This document gives an English description of the SOAP services provided. This is followed by example messages for reference.
Page 4
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
2
Quick Start Customer task
Westpac task
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
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.
Page 5
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
3
Requirements
To use the Westpac SOAP file transfer services, you will need a SOAP client that supports the following standards:
SOAP 1.1 – http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
TLS 1.0 or higher – http://www.ietf.org/rfc/rfc2246.txt
Your SOAP library should also be able to generate client side stubs to simplify your coding.
Page 6
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
4
iLink connectivity setup
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 SOAP 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 SOAP 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.
4.1 iLink URLs Test – https://ilink.support.qvalent.com Production – https://ilink.westpac.com.au
4.2 Setup connectivity form To setup your connectivity, click the Connectivity menu option at the top of the screen, then press the Setup Connectivity button. The Setup Connectivity will be displayed where you can enter the following details:
PGP Key – If you have elected to PGP encrypt files sent to Westpac, upload your PGP key here. Otherwise, this field will not be shown on the screen.
IP addresses – The WIBS 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 press Save, you will see the WIBS server details on the Setup connectivity page.
Westpac’s key – this is the public key that you will need to use to decrypt the files you receive from WIBS. This will only be displayed if encryption is enabled.
Your key - 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.
Page 7
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
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 WIBS server.
IP Addresses – lists the IP addresses allowed to access this connectivity.
Page 8
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
5
Upload File Service
The Upload File service allows you to upload a file to Westpac with associated metadata.
5.1
Upload File Request
All parameters in the upload request are optional except for fileContent. Parameter Name
Description
fileID
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 or not, you can resend it with the same fileID. Westpac will only process the fileID once. If the same fileID is received again, the file will be ignored by Westpac.
fileType
This value should be used if you send different file types to Westpac. Your Westpac representative will provide the values you should use. If you only send one type of file, you can omit this parameter.
mimeType
The MIME type for the file if known, e.g. text/plain
Filename
The name of the file uploaded if known, e.g. directEntry20090801.txt
Parameter
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
The file contents encoded using base64.
Your SOAP client must also provide a valid client certificate with the request. You will need to find out how to specify your client certificate information to your SOAP library.
5.2
Upload File 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.
6
Download Files Service
The Download Files service allows you to download any pending files with associated meta-data.
6.1
Download Files Request
Parameter Name
Description
Page 9
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Parameter Name
Description
queueID
The unique identifier for queue to fetch files from. Your Westpac representative will provide you with this value.
Your SOAP client must also provide a valid client certificate with the request. You will need to find out how to specify your client certificate information to your SOAP library.
6.2
Download Files 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
Description
fileID
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
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
The MIME type for the file if known, e.g. text/plain
filename
The name of the file uploaded if known, e.g. directEntry20090801.txt
parameter
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
The file contents encoded using base64.
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 sending 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 get receive response 2. If the response contains no files, stop 3. Otherwise, process the files in the response and repeat from step 1
Page 10
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
7
Sample Code
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.
7.1
Protecting Your Certificate
Your certificate file is used to authorise your requests to the WIBS SOAP 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.
7.2
.NET Sample Code
You need to 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.
Page 11
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
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. You will need to add the configuration from UploadTest.exe.config to your project’s configuration file.
7.3
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.
Unlike .NET, you do not need to “install” the certificate. All you need to do is copy the certificate file to an appropriate place on your server.
Page 12
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Appendix A – Upload File Example HTTP Request POST /services/messaging/UploadFile HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Host: ws.support.qvalent.com:443 Content-Length: 429 2 452357634542635TEST1test1.txtVGhpcyBpcyBhIHRlc3QgZmlsZQ==
HTTP Response HTTP/1.1 200 OK Content-Type: text/xml Date: Thu, 20 Aug 2009 02:15:06 GMT Transfer-Encoding: chunked f1 0
Page 13
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Appendix B – Download Files Example HTTP Request POST /services/messaging/DownloadFiles HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Host: ws.support.qvalent.com:443 Content-Length: 320 nathan2
HTTP Response 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 e82fc567000001233596013b00002800TEST1test1.txtVGhpcyBpcyBhIHRlc3QgZmlsZQ== 0
Page 14
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Appendix C – Westpac HTTPS addresses Test Environment Upload File URL: https://ws.support.qvalent.com/services/messaging/UploadFile Download Files URL: https://ws.support.qvalent.com/services/messaging/DownloadFiles
Production Environment Upload File URL: https://ws.qvalent.com/services/messaging/UploadFile Download Files URL: https://ws.qvalent.com/services/messaging/DownloadFiles
Page 15
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
SOAP File Transfer – Specification
Appendix D – FAQ Q) I execute the downloadFile.cmd and receive the following error: Curl: (22) The requested URL returned error: 502 A) The file you are trying to fetch may have a space in its name. Contact Westpac and ask them to check that there is no space in the filenames being fetched.
Page 16
Copyright © 2009-2011, Westpac Banking Corporation, ABN 33 007 457 141. All rights reserved.
