Programmers guide | Sage Pay


This document is intended as a guide to programmers designing remote systems which will interact with the NIWS web service.


Please note that testing with live transactional data will incur charges. Please speak to your Sage Pay account manager for more details.

Please note:

Sage Pay may provide example/sample/demo code snippets in the respective technical documents linked hereto. 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.

What is NIWS?

The New Integration Web Service (NIWS) is designed to provide remote systems with the same functionality which is available to clients on the Sage Pay website.
The web service revels methods which enable a software developer to automate access to a variety of Sage Pay services.

The web service uses a standard, generic file format (NIF) which allows the remote system to request various services without extensive reprogramming by the developer.
The NIWS service combines and consolidates the functionality provided by all the existing web services. It also provides the option of sending multiple requests in a single file.

Responses Synchronous Services

The NIWS_Validation entry point offers a range of synchronous services. The calling system receives a response in the same session. Responses from the synchronous services do not need to be retrieved.


  • Responses are returned by the web service, polling is not required. The web service can be used without supplying a postback URL.


  • Not all Sage Pay products can be offered as synchronous web services.
  • Synchronous services are restricted to one transaction per call.
  • Files cannot be uploaded using the synchronous services.
  • Input data is restricted to specified parameters.
  • Responses differ in format due to the nature of the data returned.

Asynchronous Services

The NIWS_NIF entry point supports asynchronous services for file upload, thus allowing multiple transactions in a single call. Asynchronous services require a postback URL to which the responses can be returned. If a postback URL cannot be supplied, the calling system needs to poll in order to retrieve the responses.


  • Most services offered by the synchronous services are also available using the asynchronous methods.
  • Batch-based uploads (e.g.  Payments of Salaries) can only be offered as asynchronous services.
  • Asynchronous methods utilise the Sage Pay Integration File (NIF) format. NIF is a generic file format which can be adapted to all services without extensive reprogramming.
  • Input data is flexible and can be adapted to the end-user’s requirements.
  • Because they permit file uploads, asynchronous services allow multiple transactions to be processed in a single call.
  • Asynchronous services allow the end-user to determine when responses are collected.
  • Error handling parameters (e.g.  jump errors and forward action date) can be set by the business user on the Sage Pay web site
  • Both postback and polling are supported.
  • Even if a postback URL has been supplied, response files can still retrieved from the Sage Pay polling queue.


  • Asynchronous services require polling or a postback URL to retrieve the responses.

What do you need?

  • Developers should familiarise themselves with calling a web service and processing the return in their chosen development language.
  • The web service is only available to registered Sage Pay merchants. You need to ensure that the Sage Pay account you are using is activated.
  • Access to services is regulated by service specific keys which are issued by Sage Pay. You should ensure you have the correct service key for the service you wish to access.
  • You should ensure you have the latest version of the NIF file specification.
  • If you are utilising the postback responses, you need to create a handler to accept incoming posted responses.
    • ASPX page
    • ASHX handler
    • PHP page
    • Or any other type of endpoint that accepts an HTTP POST form.

Service keys

Service keys are GUIDs used to authenticate the calling system. Service keys are issued per service to a Sage Pay merchant account.

  • The service key must be valid.
  • The service key must be activated on the Sage Pay system.
  • The service must be active for the specified merchant account.
  • The merchant account must be active.
  • The service key must be valid for the instruction issued.

How to get a service key

  1. From your Sage Pay account manager

Service keys can be issued by Sage Pay administrators, contact your Sage Pay Account Manager for assistance.

  1. Generate keys from the Sage Pay web site

Keys can also be created using the Sage connect pages on the merchant website.

  1. Manage existing keys from the Sage Pay web site

The super user of the account can use the Sage connect services pages to activate or deactivate existing service keys to meet user requirements. The page can also be used to re-generate keys in the event that a current service key is compromised.


The moment a service key is re-generated from the web page, the existing key is de-activated on the system and can no longer be used. Any files containing the old service key will fail authentication.

Usage Accessing the web service

The web service entry points can be accessed via the following URLs:


Entry points and methods

The following functions are available within the single NIWS web service:

Entry Point Type Method Description
NIWS_Validation Synchronous ValidateBankAccount Check Branch and CDV
Synchronous ValidateBranchCode Check branch
Synchronous GetBankList List of supported banks
Synchronous Get Bank List With Default Branch Code List of supported banks, including a default branch code if it exists
Synchronous Get Branch List List of branches for specified bank
NIWS_NIF Asynchronous Request MerchantS tatement Returns daily statement by date
Asynchronous RequestInterimMerchantStatement Returns interim statement for current date
Synchronous RequestActionDate Checks action date
Asynchronous BatchFileUpload All NIF format file uploads
Synchronous RequestFileUploadReport For polling for the upload reports
Synchronous RequestCreditDataReport For polling for the result files
Synchronous RequestAVSReport For polling for the result files
NIF_HELP Synchronous GetFileStructure Returns information about the makeup of the NIF file for a specified service
Synchronous CreateFileTemplate Will create a sample NIF file for the specified service
Synchronous RequestNIFConvertedFile Takes a legacy format file and returns the converted NIF format file

Request string

Incoming web service calls are in the format:
{Method}({Service key}, {parameters})

public string BatchFileUpload(string ServiceKey, string File)

The service key in the input string authenticates the calling application and authorises access to the web service. Where a file is sent to the BatchFileUpload method, the header record of the file will contain the service key as well. The service key contained in the file will be used both for authentication and to indicate the service being accessed.

Retrieving Data Synchronous

  • Synchronous services respond in the same session.
  • Only single requests can be sent to the synchronous methods.
  • For a description of the responses, refer to the individual web service documentation.


Responses from asynchronous services can be accessed either by polling for a result or by supplying a postback URL to which the result can be sent.


Where no postback URL has been supplied, the remote system should poll the Sage Pay queue to retrieve data.

The asynchronous web service methods will return a file token which is used by the calling system to retrieve the load report and/or data file. A file token is a GUID generated by the web service to uniquely identify the report to be retrieved. Requests are file-based and may contain multiple transactions therefore responses are not immediate. If the request passes initial validation, the NIWS web service responds with a file token. The remote system uses the file token to request results from the polling queue. If the load report or response file is not yet available, the web service returns “FILE NOT READY”

Upload Report

The file token is sent to the NIWS_NIF RequestFileUploadReport method to retrieve the load report.
public string RequestFileUploadReport(string ServiceKey, string FileToken)

Risk Reports

Use the same file token and send the request to NIWS_NIF RequestCreditDataReport method to retrieve the base64 encoded PDF file.
public string RequestCreditDataReport(string ServiceKey, string FileToken)

Account Verification Report

Use the same file token and send the request to NIWS_NIF RequestAVSReport method to retrieve the string array.
public string RequestAVSReport(string ServiceKey, string FileToken)

Postback response

Where the remote system has supplied a postback URL, both the load report and, where applicable, the requested report will be posted back to the supplied URL.The POST parameters are as follows:

Type Polling Id File Account reference
uploadreport string tab delimited No
creditdatareport string base64 encoded Yes
avsdatareport string tab delimited No

The remote system processes the response and prints OK to the URL to indicate that the response has been received successfully. The Sage Pay system will continue to retry the postback until the remote system responds with “OK”.

The first two retries will be immediate, with a 30 second delay between retries. Subsequent retries will occur at 10 minute intervals until the maximum of 10 retries has been reached.

Note: even when a postback URL has been supplied, the load report and requested reports will still be placed in the polling queue. The remote system can still use the supplied file token to retrieve the reports.

NIF Response files

The responses in this chapter apply to the asynchronous services. For responses from the synchronous services refer to the web service specific documentation. The web service has a three tiered response structure.

  • Web service validation, which checks the web service call and responds with an error code.
  • 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.

These responses are described in detail below.

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 service key in the method call is correct
101 Date format error. If the string contains a date it should be in the format CCYYMMDD
102 Parameter error. One or more of the parameters in the string is incorrect
200 General code exception. Please contact Sage PayTechnical Support.

This validation takes place before the NIF file is checked. If an error code is returned, the web service has not yet begun to parse the file data.

File Parsing

If the request is successfully validated, the file contained in the string is parsed. Responses are returned in the load report structure. The report is tab delimited with a linefeed character as line terminator.

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

Field Type Value
Record identifier AN8 ###BEGIN
Batch name AN {your batch name}
Start time of report AN8 HH:MM AM/PM

Load report message (occurs multiple times – once per error record)

Field Type Value
Account reference AN58 Acc Ref :{your account reference}
Line number AN Line :{line in your file where error was found}
Error message AN The error message


Field Type Value
Record identifier AN8 ###ERROR
Error message AN The error message

Load 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

Email confirmation

In addition to the load report which is returned to the calling application, the NIWS system also sends an email confirmation to the email address which is registered against the Sage Pay service key.

As with service keys, email addresses can be managed by Sage Pay administrators on request or by a user on the merchant web site.

The email could be used to inform business users of the outcome of a submitted batch. Only a single email address is captured, if the merchant requires the mail to be sent to multiple users, the onus is on the merchant to set up an email distribution list on their system and supply Sage Pay with the email address of the distribution list.

The format of the email confirmation mirrors the load report format in that it contains the BEGIN and END tags so that it can be machine readable. Due to the unreliability of mail servers, it is not recommended that developers rely on the email confirmation but rather use the load report to determine the outcome of a request.

NIF Error handling

Three different types of errors can be returned during file parsing:

  • Data errors
  • File structure errors
  • System errors

These errors will be reported in the load report file structure. The Load report message format (between the header and trailer records) differs slightly between Data errors and Structure or System errors.

Data errors

Data errors refer to lines in a file which has passed structural validation. The load report will contain the line(s) which failed validation indicating the account reference and the line in the file where the error was detected.


Acc Ref :EMP001 Line :3 Invalid account number
###END 03:45 PM

File structure errors

If any structural errors are detected the file is rejected before any transaction records are processed. In this case the account reference and line number fields will be replaced with an error tag indicating that no records in the file were parsed.


###BEGIN My Test Batch UNSUCCESSFUL 03:45 PM
###ERROR File is malformed, header record could not be identified
###END 03:45 PM

System errors

System errors which cause the web service to abort the parsing will be reported in the same way, using the error tag.


###BEGIN My Test Batch UNSUCCESSFUL 03:45 PM
###ERROR A system error has occurred. Contact Sage Pay support
###END 03:45 PM

Version 1/2014 last updated 1 Feb 2014