Programmers guide

To start, please refer our programmer’s guide for more detail on how to apply the required methodology.

Introduction

A web service that allows the Sage OpCo’s and Business Partners to send client leads directly into the Sage Pay system for the account activation process.

Depending on the indicator in field 525, leads can be sent as:

  • Active: the data will be routed to the account activation process.
  • Marketing only: the data will be stored in the marketing database. (only used by Sage OpCo’s)

The normal procedure for the registration of a Sage Pay account is by means of an account activation web site. A Sage Pay account manager captures minimal account detail and sends an account activation email to the prospective client. The client is given a unique login to the site and captures the new account details on the web pages.

The purpose of the Lead generator web service is to shorten the activation process by furnishing the Sage Pay system with as much data as possible in the initial step. The system will record the uploaded data and the activation web site will merely be used by the client to verify the data.

Quick Start Guides

We have designed some quick start guides to help you get started.

Technical Information

NIWS_PARTNER is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of leads to the Sage Pay system

Once you have built the file, call:

  • Format: Tab Delimited Text
  • Web service: https://ws.sagepay.co.za/NIWS/niws_partner.svc
  • Method: BatchFileUpload
  • Service key:  Lead generator service key

Input

Requests to the web service are sent as strings

Output

Successful request

If the method call was successful and the file is being processed, the web service will return a file token which is used to retrieve the load report

Example: 1507296452.20131202

Unsuccessful request

If the method call fails, the web service will return an error code:

CodeDescription
100Authentication failure. Ensure that the Lead generator key in the method call is correct
200General code exception. Please contact Sage Pay Technical Support.

Input file structure

Each file has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Sage Pay server to determine the purpose of the file.

K – Key record must follow the header record. The key record describes the transaction records which follow. The format defined in the key record is used to validate the record structure and content.

T – Transaction records follow the key record. The fields in the transaction records must conform to the layout defined in the key.

F – Footer record must be the last record in the file and confirms that the file is complete.

Header record (H)

Every file must contain a header record as the first record in the file.

Structure

FieldNameAlpha/NumericValue
1Record IdentifierANH
2Partner Service Key (request from Sage Pay Channel department)ANLead generator service key
3VersionAN1
4InstructionANPurpose of the file
5Batch nameANYour identifier
6Action dateNCCYYMMDD
7FillerAN0

Field explanations

FieldExplanation
Record Identifier“H” – Identifies the record as a header
Service keyThe web service uses a Lead generator service key issued by Sage Pay.
Version“1” – This is the Sage Pay version of the file specification
InstructionThis is the instruction to the Sage Pay system. It is used in conjunction with the service key in the previous field to determine what action is taken on receipt of the file.
Registration– Data submitted is for a new Sage Pay client account.
Batch nameUse this field as a unique identifier of your batch.
Action dateThe current date
Filler0

Example

HC74EF975-XXXX-XXXX-XXXX-2A64CA0FB9EF1RegistrationMy Test Batch201003310

Key record (K)

  • The key record is mandatory and must appear in the file between the header record and the transaction records.
  • The key defines the content, order and length of the transactions records in the file.
    It can be likened to the column headings in a spreadsheet.
  • The key lists all the possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
  • While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.

Example

K101113114121201441524525528

Transaction record (T)

  • There must be at least one transaction record in the file.
  • The transaction records must conform to the order of the fields as described in the key record. (In the example above, the account reference (field id 101) is defined as the first field in the record therefore every transaction record MUST have the account reference as the first field or it will fail validation)
  • Every transaction record must have the same number of fields as defined in the key record (K).
  • Every transaction record is on a new line in the file.
  • Empty fields should be replaced by a default value, where one has been defined.
  • Where no default is defined, empty fields are indicated by two consecutive tabs
    (IE: the field delimiters preceding and following the empty field)
  • Where fields are left empty, the Sage Pay system will assume spaces or zeroes for fields defined in the key record.

Mandatory fields

Please refer to Appendix 1 below for the full list of optional fields.

The more information correctly supplied in the request, the less the client will have to capture on the Sage Pay account activation web site. This will expedite the process from request to opening the account.

The following fields are mandatory. If these fields are not present and valid, the file will be rejected.

KeyField nameValid criteria
101Account referencemin2,  max 22   Alpha-Numeric
113Surnamemin2,  max 15   Alpha
114First namemin1,  max 10   Alpha
121Trading namemin2,  max 25   Alpha-Numeric
201Email addressmin 5 max 50   Alpha-Numeric
Format: {text}@{text}.{text}
Full-stop allowed in text fields.
301Extra fieldmin 5 max 999   Alpha-Numeric
302Extra fieldmin 5 max 50   Alpha-Numeric
303Extra fieldmin 5 max 50   Alpha-Numeric
441Telephone numbermin 10; max12   Numeric
524NotesOPCO / Business Partner name, Software serial number, Software account number (same as 101)

or

ACC NR: Internal Acc # (OpCo Name) eg.ABC123(VIP)   EMPL BR: (Employee Bracket)eg.350   DEAL: (Promo Name)eg.VIP Premier   OTHER:(optional) eg. pep name, cost center, etc.

Triple space separated.

525Activate nowNumeric
0 = Marketing lead only (only used by SAGE OpCo’s)
1 = Log active opportunity
528Sage IDValid ‘@sage.com’ email address of lead referral.

Validation of optional fields

  • Any additional data supplied will be validated according to the table in Appendix 1.
  • Only valid data will be inserted into the database.
  • Any fields which fail content validation will not be inserted.
  • Any fields which do not meet the specified minimum length will fail validation.
  • Any fields which exceed the specified maximum length will be truncated.
  • Non-mandatory fields which fail validation will not cause the file to be rejected.

Footer record (F)

The footer record indicates that the complete file has been received. It must be the last record in the file. If the record is not present, the system will fail the file without processing any transaction records.

Structure

FieldNameAlpha/NumericValue
1Record IdentifierANF
2No of transactionsNA count of the transaction records
3Sum of amountsNThe sum of the monetary fields (in cents)
4End-of-file indicatorN9999

Field explanations

FieldExplanation
Record Identifier“F” – Identifies the record as a footer
No of transactionsThis is the count of all the ‘T’ records in the file.
Sum of amountsThis field must contain zero.
End-of-file indicator‘9999’ – Indicates there are no more records.

Example

F209999

Retrieving the Load Report

Postback option

If you have activated the postback option in your Sage partner profile, the load report is automatically posted back to the URL you supplied.

Polling option

If you have not activated the postback option, you will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

  • Web service: https://ws.sagepay.co.za/NIWS/niws_partner.svc
  • Method: RequestFileUploadReport
  • Service key:  Lead generator key

Requests to the web service are sent as strings.

Output file

File content
For each successful lead in the file, the load report will contain the Sage Pay account number for the lead. Where errors were detected, the load report will stipulate the line number and the error message

Load report structure:

Load report header (occurs once at the start of each load report)

FieldTypeValue
Record identifierAN8###BEGIN
Batch nameAN{your batch name}
Result of uploadA13SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
Start time of reportAN8HH:MM

Load report message (occurs multiple times – once per T record in the input file)

FieldTypeValue
Account referenceAN58Acc Ref :{your account reference}
Batch nameANLine :{line in your file where error was found}
Line numberANThe Sage Pay account number or error message

Load report trailer (occurs once – the last line in the report)

FieldTypeValue
Record identifierAN6###END
End time of reportAN8HH:MM

Errors
The following is a list of the errors which could be returned:

Error messageMeaning
A system error occurred. Please contact Sage Pay.A fatal error occurred and the file could not be processed
Invalid service key.Partner service key could not be authenticated
Service key inactive.Partner service key not activated on the Sage Pay system
Invalid instruction.Instruction should be “Registration”
File structure invalid. Transaction record fields do not match key record fields.Columns supplied in the transaction record(s) do not match the columns specified in the key record
Required key XXX was not provided.A mandatory key was omitted
File structure invalid. Please check header, key or footer records.One or more of the record types H,K or F is not present in the file.
File structure invalid. Please check transaction records.Record type T not found
Transaction field XXX has invalid characters.
Transaction field XXX has an invalid length. Minimum X characters.
Transaction field XXX has an invalid range. Only from {1} to {2} allowed.

Examples:

1.
###BEGIN key record UNSUCCESSFUL 16:03
###ERROR A system error occurred. Please contact Sage Pay.
###END 16:03

2.
###BEGIN UNSUCCESSFUL 16:02
Acc Ref :NA  Line :2 Required key 101 was not provided
###END 16:02

3.
###BEGIN My test batch SUCCESSFUL 15:45
Acc Ref : 001    Line :3  51002977916
###END 15:45

4.
###BEGIN My test batch SUCCESSFUL WITH ERRORS 11:45
Acc Ref : 001    Line :3  51002977916
Acc Ref : 002    Line :4  INVALID EMAIL ADDRESS
###END 11:45

Appendix 1 Transaction fields

* refers to a mandatory field

Account reference

KeyNameTypeValue
101Account referenceAN22001 for the first account in the file.
002 for the second account
Etc.

Company details

KeyNameTypeValue
121Trading nameAN25The name of the business to be checked.
122Registration numberN20The number of a registered business
123Registered nameAN25The name of a registered business
124VAT numberN10The VAT number of a registered business
125Legal entityN11 = 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

Company contact details

KeyNameTypeValue
203Company web addressAN50The “//:” and “.” symbols are allowed in this field
341Company phone numberN11Include dialing codes EG: 27117822349
min:10, max:12
342Company fax numberN11Include dialing codes EG: 27117822349
min:10, max:12

Company physical address

KeyNameTypeValue
321Physical address line 1AN50min:2, max:50
322Physical address line 2AN50min:2, max:50
323Physical address line 3AN50min:2, max:50
324Physical suburbAN50min:2, max:50
325Physical cityAN50min:2, max:50
326Physical postal codeN4Must be 4 digits
327Physical provinceN11 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = Kwazulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West

Company postal address

KeyNameTypeValue
331Postal address line 1AN50min:2, max:50
332Postal address line 2AN50min:2, max:50
333Postal address line 3AN50min:2, max:50
334Postal suburbAN50min:2, max:50
335Postal cityAN50min:2, max:50
336Postal codeN4Must be 4 digits
337Postal provinceN11 = Western Cape
2 = Gauteng
3 = Eastern Cape
4 = Free State
5 = Kwazulu Natal
6 = Limpopo
7 = Mpumalanga
8 = Northern Cape
9 = North West

Account user details

KeyNameTypeValue
111Id numberN13South African identity number. Must be 13 digits.
113*SurnameA15Details to be used for Consumer enquiry
114*First nameA10Details to be used for Consumer enquiry
119TitleN11 = Mr
2 = Mrs
3 = Ms
4 = Miss
5 = Dr
6 = Prof
128DesignationA25Director, Member, Trustee, Sole proprietor, etc
129Job descriptionA25Manager, Owner, Bookkeeper, etc.
201Email addressAN50The “@” and “.” symbols are allowed in this field
441*Telephone numberN11Include dialing codes EG: 27117822349
min:10, max:12
442Mobile numberN11Include dialing codes EG: 27827822123
min:10, max:12

Bank account details

KeyNameTypeValue
132Bank account holderAN50The name linked to the bank account
133Bank account typeN11 = Current / Checking
2 = Savings
3 = Transmission
134Bank account branchN6The branch code of the homing account. This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
136Bank account numberN11The homing bank account number.

Software vendor information

KeyNameTypeValue
524*NotesAN399OPCO / Business Partner name, Software serial number, Software account number
Triple   space   separated.
525*Activate nowN0 = Marketing lead only (only used by SAGE OpCo’s)
1 = Log active opportunity
528Sage IDAN150Valid ‘@sage.com’ email address of lead referral.

Read the Lead Status File Specifications here.

Version 1.3/2015 last updated 1 Dec 2015

Please note:

Sage Pay may provide example/sample/demo code snippets in this technical document. Such snippets are for guidance purposes only and may not function on every developer’s system/s. Sage Pay disclaims any and all liability for the usage of any of the example/sample/demo code snippets provided -and you as
the developer must accept full responsibility for the usage of any example/sample and/or demo code.

While every possible effort has been taken to ensure compatibility across multiple system configurations, the example/sample/demo code cannot be guaranteed to work on all systems, with all operating systems and or with all system configuration/s.

Sage Pay Login