SA ID Validations | Technical Documents | Partners & Developers | Sage Pay

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.

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.

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.

Object Name Description
method BatchFileUpload Parameter:

  • ServiceKey (risk report service key)
  • File
method RequestFileUploadReport Parameter:

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

  • ServiceKey
  • FileToken (the same file token received)
method RequestAVSReport Parameters:

  • 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.

Key Field name CD35
101 Account reference tick
126 AVS check number tick
127 Is ID number tick
131 Banking detail type tick
132 Bank account name tick
133 Bank account type tick
134 Branch code tick
135 Filler tick
136 Bank account number tick
301 Extra 1
302 Extra 2
303 Extra 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)

Field Field name CD35
Record identifier AN8 ###BEGIN
File Token N The polling id returned in the original response
Type A6 REPORT
Start time of report AN8 HH:MM AM / PM

Key record

(occurs once between header and transaction records)

Field Type Value
Record identifier AN6 ###KEY
Field 1 A ACCOUNTREFERENCE
Field 2 A BANKACCOUNTNUMBERVALID
Field 3 A IDNUMBERVALID
Field 4 A LASTNAMEMATCH
Field 5 A ACCOUNTACTIVE
Field 6 A PERIODACTIVE
Field 7 A ACCEPTSDEBITS
Field 8 A ACCEPTSCREDITS
Field 9 A ACCOUNTDORMANT
Field 10 A ERRORMESSAGE
Field 11 AN EXTRA1
Field 12 AN EXTRA2
Field 13 AN EXTRA3

AVS transaction

(occurs multiple times – once per account number)

Field Type Value
Account reference A Acc Ref :{your account reference}
Bank account number A VALID / INVALID
AVS check number A VALID / INVALID
(AVS check number matches account number)
Last name match * A VALID / INVALID or N/A
Account active * A VALID / INVALID or N/A
Period active * A Y = account active for longer than 6 months
N = account not active
N/A
Accepts debits * A VALID / INVALID or N/A
Accepts credits * A VALID / INVALID or N/A
Account dormant * A VALID / INVALID or N/A
Error message A Any error message received from the bank
Extra 1 A User defined data which was sent in the request file
Extra 2 A User defined data which was sent in the request file
Extra 3 A User 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)

Field Type Value
Record identifier AN6 ###END
End time of report AN8 HH: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 ID Description Type
14 ID number verification Consumer

XML response products

Product ID Description Type
37 ID 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.

Field Field name Product ID: CD14, CD37
101 Account reference tick
111 ID number tick
113 Surname tick
114 Name tick
450 Reason code tick

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