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.


Sage Connect is regarded as the place in an application where a Sage Pay customer will enter details to enable / communicate via the software with sage Pay.

Sage Connect is divided into three (3) critical components

Click here for the quick start guides for:

  • Account Service
  • Sage Pay system permissions

The Sage Pay Integration Web Service is a single web service which exposes multiple endpoints. This specification is specific to the NIWS_partner endpoint:- and describes the input to the ValidateServiceKey method

To access this web service method you require a valid Software Vendor Key (issued by Sage Pay)


The NIWS_Validation endpoint has the following methods available:

Method name Usage
ValidateServiceKey Check a range of Service key/Service Id combinations for a specified Sage Pay account to ensure that the key is valid
Object Name Description
Class ServiceInfo


  • ServiceID
  • ServiceKey
List ServiceInfoList Generic list to add service info
Class ValidateServiceKeyRequest


  • MerchantAccount
  • ServiceInfoList
  • SoftwareVendorKey
Class ValidateServiceKeyResponse
Class ServiceInfoResponse


  • ServiceID
  • ServiceKey
  • ServiceStatus
List ServiceInfoResponseList Generic list holding service info responses per service


The service accepts an object which contains the Software vendor key and account number, used for authentication and then an array of service Id/service key combinations to be validated:


The service responds synchronously with an object containing an authentication status and a status for each element pair in the array:

The original data submitted in the request is returned with a status for each section.

In the example above:

  • The software vendor key is valid and active.
  • The merchant account number is valid and active.
  • The service key submitted for service id 1 is either invalid or not activated.
  • The service id 3 is not activated for the merchant account number submitted.


Invalid/inactive service keys should not be stored in the calling application.

Only where the service key response is 001 should the key be stored in the application.

Response Code Response status
001 Authenticated
103 No active partner found for this Software vendor key
104 No active client found for this Account number
200 General service error – contact Sage Pay support
201 Account locked out

Service key validation

Per ServiceId/Servicekey combination submitted.

Response Code Response status
001 Validated
105 No active service found for this Account number/ServiceId combination
106 No active service key found for this Account number/ServiceId /Servicekey combination

Service ID

The following service Ids may be submitted:

Service ID Service name
1 Debit orders
2 Creditor payments
3 Risk reports
5 Account service
10 Salary payments
14 Pay Now

Security lockout

Due to the inherent risk in exposing a service which validates authentication details (service keys), an automated 10-minute lockout is built into the system to minimize the risk of brute force attacks by malicious persons or software.

Each request which includes a non-positive response (authentication failure or invalid service key) will be recorded. After the 3rd attempt within a 10-minute period, the account number will be locked and no further requests relating to that account number will be permitted for 10 minutes. The system will return a 201 error.

After the 10-minute timer has expired, any further requests which include an invalid service key will re-initiate the 10-minute lockout.

Only a request which contains valid data will clear the table.

General Security

It is highly recommended that:

  • Login details for Sage Connected Services is encrypted in the application database. A restore / password reminder service for these credentials must not be made available to the user. The user can reset his/her login details on the Sage Pay website and re-enter them in Sage Connected Services and/or the application database.
  • Invalid service keys are not stored in Sage Connected Services and/or the application database. The “OK” button must only be enabled once all the keys are validated. If a new key is entered; it must be validated using this specification before it can be allowed to be stored in Sage Connected Services and/or the application database.

Labels are to be used in software (where applicable).

Sage Pay endeavours to minimalize support and training related issues by using standardized software labels within integrated software. This makes it easier for end users to understand as the labels on the integrated software and the labels on the Sage Pay system matches. We therefore require the usage of the following labels for the following input fields in integrated software.

  • Sage Pay Account Number
  • Account Service Key
  • Debit Order Service Key
  • Authenticated Collections Service Key
  • Risk Reports Service Key
  • Supplier Payment Service Key
  • Salary Payment Service Key
  • Pay Now Service key

All applications follow the Sage Pastel Evolution methodology in opening Sage Connected Services in a “frameless pop up window” from the respective application. The dimensions Sage Pay has designed the content for is 560w x 650h (pixels).

Sage Pay Login