Please note:

It is highly recommended that developers rather use Sage Connected Services for verification.

Programmers guide

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

Testing

Please note that testing with live transactional data will incur charges.  Please contact us for more details.

Introduction

The following document gives a basic guideline of using the Sage Pay Web Service for systems integration. The Location for this web service is at: https://ws.sagepay.co.za/NIWS/niws_nif.svc

This service enables a software developer to write code enabling a user to do South African bank account, -and SA consumer ID verification from the Sage Pay System without user interaction. It is a simple web service. Developers should familiarize themselves with calling a web service and processing the return in their chosen development language.

To submit a verification request, the Risk Reports service must be activated on your Sage Pay account and you must have a valid, active Risk Reports service key.

ObjectNameDescription
methodBatchFileUploadParameter:

  • ServiceKey (risk report service key)
  • File
methodRequestFileUploadReportParameter:

  • ServiceKey (risk report service key)
  • FileToken (received on file upload if successful)
methodRequestCreditDataReportParameters:

  • ServiceKey
  • FileToken (the same file token received)
methodRequestAVSReportParameters:

  • ServiceKey
  • FileToken (the same file token received)

Bank Account verification (AVS)

The following banks support account verification:

  • ABSA
  • Capitec
  • FNB
  • Nedbank
  • Standard bank

Please note:

We can currently only verify Absa, Capitec, FNB, Nedbank and Standard Bank -bank accounts. Please do not submit accounts for any other banks as these cannot be processed but will be charged for.

Consumer: The client’s identity number and bank account details are submitted to the issuing bank to verify that the account is open, active and associated with the identity number supplied.

Commercial: The company’s registration number and bank account details are submitted to the issuing bank to verify that the account is open, active and associated with the company registration number supplied.

Technical Information

The following instruction is permitted for consumer enquiries:

  • CD35

The following table indicates the fields which are applicable to bank account verification.

The fields indicated by tick  are mandatory and must be included in every file which is uploaded for the specified service.

KeyField nameCD35
101Account referencetick
126AVS check numbertick
127Is ID numbertick
131Banking detail typetick
132Bank account nametick
133Bank account typetick
134Branch codetick
135Fillertick
136Bank account numbertick
301Extra 1
302Extra 2
303Extra 3

Verification responses

Upload report example

 

The web service has a tiered response structure.

example_2

  • Web service validation, which checks the web service call and responds with an error code if an error is detected. If the call passes evaluation, the web service returns a file token to be used for polling or to identify the report on the postback url.
  • File parsing, which validates the content of the file string and responds in the load report.
  • Email confirmation, which generates automatic emails containing the same information contained in the load report.
  • Verification report, this is the response from the external service provider.

Please see the programmers guide for more information on retrieving AVS reports.

Verification report

Once Sage Pay has received a response from the service provider, the returned data is made available to the calling system via the Sage Pay polling queue and posted back if a postback url has been supplied. The data is returned as a tab-delimited file.

Input File Structure

The file is a tab delimited text file and 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.

AVS report header

(occurs once at the start of the AVS report)

FieldField nameCD35
Record identifierAN8###BEGIN
File TokenNThe polling id returned in the original response
TypeA6REPORT
Start time of reportAN8HH:MM AM / PM

Key record

(occurs once between header and transaction records)

FieldTypeValue
Record identifierAN6###KEY
Field 1AACCOUNTREFERENCE
Field 2ABANKACCOUNTNUMBERVALID
Field 3AIDNUMBERVALID
Field 4ALASTNAMEMATCH
Field 5AACCOUNTACTIVE
Field 6APERIODACTIVE
Field 7AACCEPTSDEBITS
Field 8AACCEPTSCREDITS
Field 9AACCOUNTDORMANT
Field 10AERRORMESSAGE
Field 11ANEXTRA1
Field 12ANEXTRA2
Field 13ANEXTRA3

AVS transaction

(occurs multiple times – once per account number)

FieldTypeValue
Account referenceAAcc Ref :{your account reference}
Bank account numberAVALID / INVALID
AVS check numberAVALID / INVALID
(AVS check number matches account number)
Last name match *AVALID / INVALID or N/A
Account active *AVALID / INVALID or N/A
Period active *AY = account active for longer than 6 months
N = account not active
N/A
Accepts debits *AVALID / INVALID or N/A
Accepts credits *AVALID / INVALID or N/A
Account dormant *AVALID / INVALID or N/A
Error messageAAny error message received from the bank
Extra 1AUser defined data which was sent in the request file
Extra 2AUser defined data which was sent in the request file
Extra 3AUser defined data which was sent in the request file

Please note:

Not all banks are able to supply this data. Where values are received by the service provider they are included in the response. Where no data can be received, they put N/A in the file.

AVS report trailer

(occurs once – the last line in the report)

FieldTypeValue
Record identifierAN6###END
End time of reportAN8HH:MM AM / PM

ID Number Verification

To submit a South African ID verification consumer enquiry, the Risk Reports service must be activated on your Sage Pay account and you must have a valid, active Risk Reports service key.

For the Risk Reports service the instruction consists of the prefix CD followed by the product id(s) required.
Examples:

CD14 – Verify a South African Id number.

The tables below list the Risk Reports product IDs:-

Product IDDescriptionType
14ID number verificationConsumer

XML response products

Product IDDescriptionType
37ID Number Verification – (XML response)Consumer

Usually all Risk Reports enquiries are returned in PDF format as a standard.

Product id 37 has been set up separately to return an XML response. A signed disclaimer; to use this specific service is required.

This product is not available as part of a combined consumer product and should be requested separately.

The fields indicated by tick are mandatory and must be included in every file which is uploaded for the specified instruction.

FieldField nameProduct ID: CD14, CD37
101Account referencetick
111ID numbertick
113Surnametick
114Nametick
450Reason codetick

Risk Reports response

The web service has a tiered response structure.

  • Web service validation, which checks the web service call and responds with an error code if an error is detected. If the call passes evaluation, the web service returns a file token to be used for polling or to identify the report on the postback url.
  • File parsing, which validates the content of the file string and responds in the load report.
  • Email confirmation, which generates automatic emails containing the same information contained in the load report.
  • Risk Reports report, this is the response from the external service provider.

Response example layout

Version 1.3/2016 last updated 6 Apr 2016

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