Lead Status File Specification | Integration Documents | Sage Pay

Introduction

The Sage Pay Lead status file is generated on request via the NIWS_partner web service.

The file contains the remote account number supplied when the lead was logged, the number of the Sage Pay account which was opened when the lead was logged, the current status of the account as well as any detail which is captured for the account on the Sage pay system.

The remote system supplies the Software vendor key and the account number, which was used to register the original lead and polls to retrieve the lead status file generated by the Sage Pay system.

Access

Endpoint url:

https://ws.sagepay.co.za/niws/niws_partner.svc

Methods:

Returns either

  • 100
  • 200
  • 300
  • FileToken

Returns either

  • 200
  • FILE NOT READY
  • Lead status file

Response

The web service is asynchronous.

The remote system calls the RequestAccountStatus method, which returns a file token.

The remote system then calls the RetrieveAccountStatus method using the file token returned in the previous call to retrieve the account status data.

If a postback URL has been supplied, the load report will be returned to the URL as an HTTP post.

Web service validation

The NIWS web service performs initial validation on the incoming web service method call. If the validation fails, the service will return an error code.

Code Description
100 Authentication failure. Ensure that the Lead generator key in the method call is correct
200 General code exception. Please contact Sage Pay Technical Support.
300 Account not found

Lead status file format

The file is a tab-delimited text file.

The file contains the latest data for the requested account, as it exists in the Sage pay database.

File header and footer records bind the file.

File header

Occurs once at the start of the file

Field Name Type Value
1 Record identifier A FH
2 File date stamp N CCYYMMDDHHMMSSS
3 Lead generator key AN The GUID key assigned by Sage Pay
4 Sage account number AN The account number of the Sage software
5 Sage Pay account number N11 The number of the linked Sage Pay account
6 Account status N 0 – Inactive opportunity

1 – Lead opportunity

2 – Active opportunity

10 – Busy registering

11 – Registration complete

12 – Registration verification

20 – Active pending

21 – Active

22 – Suspended

30 – Closed

31 – Unused account

Account detail

Field Name Type Value
1 Trading name AN Account trading name
2 Registration number AN Registration number
3 Registered name AN Account registered name
4 VAT number AN VAT registration number
5 Legal entity N2 1 = Registered company (Pty Ltd)

2 = Close corporation

3 = Section 21 company

4 = Non-profit organisation

5 = Trust

6 = Co-operative

7 = Sole proprietor

8 = Partnership

9 = Educational institution

10 = Unknown

11 = Association

12 = Incorporation

6 Company web address AN50 The “//:” and “.” symbols are allowed in this field
7 Phone number N11 Include dialing codes EG: 27117822349
8 Fax number N11 Include dialing codes EG: 27117822349
9 Physical address line 1 AN50
10 Physical address line 2 AN50
11 Physical suburb AN50
12 Physical city AN50
13 Physical code N4
14 Physical province N1 1 = Western Cape

2 = Gauteng

3 = Eastern Cape

4 = Free State

5 = KwaZulu Natal

6 = Limpopo

7 = Mpumalanga

8 = Northern Cape

9 = North West

15 Postal address line 1 AN50
16 Postal address line 2 AN50
17 Postal suburb AN50
19 Postal city AN50
20 Postal code N4
21 Postal province N1 1 = Western Cape

2 = Gauteng

3 = Eastern Cape

4 = Free State

5 = KwaZulu Natal

6 = Limpopo

7 = Mpumalanga

8 = Northern Cape

9 = North West

22 Account user ID N13 Primary account user details
23 Account user surname A15 Primary account user details
24 Account user first name A10 Primary account user details
25 Account user title N1 1 = Mr

2 = Mrs

3 = Ms

4 = Miss

5 = Dr

6 = Prof

26 Designation A25 Director, Member, Trustee, Sole proprietor, etc
27 Job description A25 Manager, Owner, Bookkeeper, etc.
28 Email address AN50
29 Telephone number N11 Include dialing codes EG: 27117822349
30 Mobile number N11 Include dialing codes EG: 27117822349
31 Bank account holder AN50 The name linked to the bank account
32 Bank account type N1 1 = Current / Checking

2 = Savings

3 = Transmission

33 Bank account branch N6 The branch code of the homing account. This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
34 Bank account number N11 The homing bank account number.
35 Extra 1 AN User-defined data received in upload file
36 Extra 2 AN User-defined data received in upload file
37 Extra 3 AN User-defined data received in upload file
38 Sage ID AN150 Valid ‘@sage.com’ email address

File footer

Occurs once at the end of the file

Field Name Type Value
1 Record identifier A FF
2 End of file indicator AN #END#