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

A web service called ‘NIWS_NIF’ used to send batched Debit order files to a Sage Pay account and then the National Payment System.

Quick Start Guides

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

Technical Information

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to submit a batch file of Debit orders (Same day / Two day) for processing.

Sage Pay is compliant with the Payment Card Industry Data Security Standards (PCI DSS) and does therefore not accept or store Credit Card numbers. Only tokens representing the card details and masked credit card numbers (for tracing purposes) may be submitted in this file. The system will reject any file which contains unmasked credit card numbers.

The service

Object	Name	Description
method	BatchFileUpload	Parameter: ServiceKey (Debit order service key) File (Built in external system)
method	RequestFileUploadReport	Parameter: ServiceKey (Debit order service key) FileToken (received on file upload if successful)

Object

Name

Description

method

BatchFileUpload

Parameter:

ServiceKey (Debit order service key)
File (Built in external system)

method

RequestFileUploadReport

Parameter:

ServiceKey (Debit order service key)
FileToken (received on file upload if successful)

Once you have built the file call:

Web service: https://ws.sagepay.co.za/NIWS/niws_nif.svc
Method: BatchFileUpload
Service key: Debit order service key

Input

Requests to the web service are sent as strings

The BatchFileUpload method requires two parameters: –

Service key (to authenticate the method call)
File (the batch file containing the debit order instructions)

Example

public string BatchFileUpload(string ServiceKey, string File)
        {
            //initialise client 
            NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

            //call the BatchFileUpload method equal to a string variable
            string Request = client.BatchFileUpload(ServiceKey, File);

            //close client after response is received
            client.Close();

            switch (Request)
            {
                case "100"://Authentication failure
                    break;
                case "102"://Parameter error
                    break;
                case "200"://General code exception. 
                    break;
                default: //successful
                    return Request;
            }

            //use response to call RequestFileUploadReport method
            return Request;
        }

public string BatchFileUpload(string ServiceKey, string File)

{

//initialise client

NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

//call the BatchFileUpload method equal to a string variable

string Request = client.BatchFileUpload(ServiceKey, File);

//close client after response is received

client.Close();

switch (Request)

{

case "100"://Authentication failure

break;

case "102"://Parameter error

break;

case "200"://General code exception.

break;

default: //successful

return Request;

}

//use response to call RequestFileUploadReport method

return Request;

}

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: 20000000.2550236530.0483.2.2

Unsuccessful request

If the method call fails, the web 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 Pay Technical Support.

Input File Structure

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

Record Structure

Field	Name	Type	Value
1	Record Identifier	AN	H
2	Service Key	AN	Debit Order Service Key
3	Version	AN	1
4	Instruction	AN	Purpose of the file
5	Batch name	AN	Your identifier
6	Action date	N	CCYYMMDD
7	Software vendor code	AN	The key issued by Sage Pay to identify the software origin of transactions. (only used by Sage Pay business partners else use default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)

Field explanations

Field	Explanation
Record Id	“H” – Identifies the record as a header
Service key	Debit order service key
Version	“1” – This is the Sage Pay version of the file specification
Instruction	Update – update the master file without loading a batch SameDay – Sameday debit order batch upload (ideal for once off collection where the time the recipient is debited, is not important) TwoDay – Dated debit order batch upload (ideal for recurring billing) Refer to service cutoff times below.
Batch name	Use this field as an identifier of your batch when retrieving the load report.
Action date	The date on which the bank accounts are to be debited.
Software vendor code	This is a code issued by Sage Pay.

Example

C74EF975-5429-4663-85FB-2A64CA0FB9EF

TwoDay

My Test Batch

20100331

24ade73c-98cf-47b3-99be-cc7b867b3080

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

101

102

131

132

133

134

135

136

162

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).
Empty fields should be replaced by a blank tab or a default value, where one has been defined.
Where fields are left empty, the Sage Pay system will assume spaces or zeroes for fields defined in the key record.

Example

Acc001

AccName001

BankAccountName001

470010

25000000000

100

Mandatory field

The fields indicated by are mandatory for the specified instruction.

Key	Field name	SameDay/TwoDay
101	Account reference
102	Account name
103	Account active
104	Delete this account
131	Banking detail type
132	Bank account name/Credit card holder name as it appears on the front of the card
133	Bank account type/Credit card type
134	Branch code/Expiry month
135	Filler/Expiry year
136	Bank account number/Credit card token
137	Masked credit card number	*
161	Default debit amount
162	Amount
201	Email address
202	Mobile number
281	Debit masterfile group
301	Extra 1
302	Extra 2
303	Extra 3

* Field 137 is mandatory for any file which contains debit against credit cards. The field should be present but left blank for records containing normal bank account numbers

Optional fields

If the optional fields are to be included in the transaction records, they must be specified in the key record (K).

Transaction fields

Field	Name	Type	Value
101	Account reference	AN22	The unique account reference that you will use in the future to address this client (Minimum 2; Maximum 22)
102	Account name	AN25	The name of your client’s account on the Sage Pay system (Typically your client’s name) (Minimum 2; Maximum 25)
103	Account active	N	0 = Inactive 1 = Active
104	Delete this account	N	0 = Don’t delete 1 = Delete
131	Banking detail type	N1	1 = Bank account 2= Credit card
USE THESE FIELDS IF FIELD 131 IS SET TO 1 (Bank account)
132	Bank account name (account holder name)	AN30	The name of the bank account to be debited or credited (may differ to the name in field 102) (Maximum 30 characters)
133	Bank account type	N1	1 = Current / Checking 2 = Savings 3 = Transmission 4 = Bond
134	Bank account branch	N6	The branch code of the homing account. This field MUST be 6 digits. Pre-fill with zeroes if less than 6.
135	Filler	N1	0
136	Bank account number	N11	The homing bank account number. May not exceed 11 digits.
USE THESE FIELDS IF FIELD 131 IS SET TO 2 (Credit card)
132	Credit card holder	AN30	The card holder name as it appears on the front of the card (may differ to the name in field 102) (Maximum 30 characters)
133	Credit card type	N1	1 = Mastercard 2 = Visa
134	Expiry month	A2	2-digit month (MM) include the leading zero
135	Expiry year	N4	4-digit year (CCYY)
136	Credit card token	AN36	PCI token generated for card processing
137	Masked credit card number	N16	First 4 and last 4 digits of the card number – middle 8 digits replaced with zeroes
161	Default debit amount	N	The default amount to be set in the masterfile (in cents)
162	Debit amount	N	The amount of this payment (in cents)
201	Email address	AN50	This is the email address used to notify your client of the debit order. (The “@” and “.” symbols are allowed in this field)
202	Mobile number	N11	The cell number to be used for SMS notifications Include dialling code EG: 27827822349 NOTE: cell numbers which are not correctly formatted will be ignored and not updated to the masterfile
281	Debit masterfile group	AN50	Links this account to an existing group Validation will fail if the group indicated does not exist.
301	Extra 1	AN50	Custom User-defined data (Extra data you want returned for your internal system use)
302	Extra 2	AN50	Custom User-defined data (Extra data you want returned for your internal system use)
303	Extra 3	AN50	Custom User-defined data (Extra data you want returned for your internal system use)

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

Field	Name	Type	Value
1	Record Identifier	AN	F
2	No of transactions	N	A count of the transaction records
3	Sum of amounts	N	The sum of the monetary fields (in cents)
4	End-of-file indicator	N	9999

Field explanations

Field	Explanation
Record Identifier	“F” – Identifies the record as a footer
No of transactions	This is the count of all the ‘T’ records in the file.
Sum of amounts	This is the sum of all the values in the 161 fields. If field 161 is not specified in the key record, this will be the sum of all the 162 fields.
End-of-file indicator	‘9999’ – Indicates there are no more records.

Example

9999

Example of input file

H xx34x5802-xxxx-abcd-c7xxxxz1ad9q 1 TwoDay TestBatch 20131204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K 101 102 103 104 131 132 133 134 135 136 161 162 302
T UniqueRef1 AccountName 1 0 1 Joe Bloggs 2 632005 0 9091111334 10000 10000 Extra2
T UniqueRef2 AccountName2 1 0 1 Sam Smith 1 250655 0 4011111193 10000 10000 Extra2
T UniqueRef3 AccountName3 1 0 2 John Jones 2 03 2017 25ayz73c-98cf-47b3-99be-cc7b867b3121 4208000000003456 10000 10000 Extra2
F 2 20000 9999

H xx34x5802-xxxx-abcd-c7xxxxz1ad9q 1 TwoDay TestBatch 20131204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080

K 101 102 103 104 131 132 133 134 135 136 161 162 302

T UniqueRef1 AccountName 1 0 1 Joe Bloggs 2 632005 0 9091111334 10000 10000 Extra2

T UniqueRef2 AccountName2 1 0 1 Sam Smith 1 250655 0 4011111193 10000 10000 Extra2

T UniqueRef3 AccountName3 1 0 2 John Jones 2 03 2017 25ayz73c-98cf-47b3-99be-cc7b867b3121 4208000000003456 10000 10000 Extra2

F 2 20000 9999

Example of string file (C#)

string fl = "H\xx34x5802-xxxx-abcd-c7xxxxz1ad9q\t1\tTwoDay\tTestBatch\t20131204\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080" + Environment.NewLine +
"K\t101\t102\t103\t104\t131\t132\t133\t134\t135\t136\t161\t162\t302" + Environment.NewLine +
"T\tUniqueRef1\tAccountName\t1\t0\t1\tJoe Bloggs\t2\t632005\t0\t9091111334\t10000\t10000\tExtra2" + Environment.NewLine +
"T\tUniqueRef2\tAccountName2\t1\t0\t1\tSam Smith\t1\t250655\t0\t4011111193\t10000\t10000\tExtra2" + Environment.NewLine +
"T\tUniqueRef3\tAccountName3\t1\t0\t1\ John Jones \t2\t03\t2017\t25ayz73c-98cf-47b3-99be-cc7b867b3121 /t4208000000003456\t10000\t10000\tExtra2" + Environment.NewLine +
"F\t3\t30000\t9999";
string FileToken = BatchFileUpload("xx34x5802-xxxx-abcd-c7xxxxz1ad9q", fl);

string fl = "H\xx34x5802-xxxx-abcd-c7xxxxz1ad9q\t1\tTwoDay\tTestBatch\t20131204\t24ade73c-98cf-XXXX-XXXX-cc7b867b3080" + Environment.NewLine +

"K\t101\t102\t103\t104\t131\t132\t133\t134\t135\t136\t161\t162\t302" + Environment.NewLine +

"T\tUniqueRef1\tAccountName\t1\t0\t1\tJoe Bloggs\t2\t632005\t0\t9091111334\t10000\t10000\tExtra2" + Environment.NewLine +

"T\tUniqueRef2\tAccountName2\t1\t0\t1\tSam Smith\t1\t250655\t0\t4011111193\t10000\t10000\tExtra2" + Environment.NewLine +

"T\tUniqueRef3\tAccountName3\t1\t0\t1\ John Jones \t2\t03\t2017\t25ayz73c-98cf-47b3-99be-cc7b867b3121 /t4208000000003456\t10000\t10000\tExtra2" + Environment.NewLine +

"F\t3\t30000\t9999";

string FileToken = BatchFileUpload("xx34x5802-xxxx-abcd-c7xxxxz1ad9q", fl);

Processing deadlines

All times in 24hr format.
Action date is the date the transaction is processed on the debtor’s bank account.
Business days are the days between -and including Monday to Friday but do not include public holidays and/or weekends.

	Same day debit orders	Two day debit orders
Processing days (excludes any public holidays)	Monday to Saturday	Monday to Friday
Must be loaded -and authorized on Sage Pay before	10:59 on the action date (Mon-Fri) -or 23:59 one (1) business day prior to the action date for Saturday service	23:59 two (2) business days prior to action date
Debits processed by banks (as a general rule but might differ from bank to bank)	usually after 16h00 on the action date	usually 00h01 on the action date
Payment of collection value less retentions and fees as available balance in the Sage Pay merchant account	One (1) business day after the action date.	On the action date.

Retrieving the Load Report

Postback option

If you have activated the postback option in your Sage connect 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_nif.svc
Method: RequestFileUploadReport
Service key: Debit Order service key

Requests to the web service are sent as strings

Example

public string RequestFileUploadReport(string ServiceKey, string FileToken)
         {
             //initialise client 
             NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

             //call the RequestFileUploadReport method equal to a string variable
             //the same service key used for the bactch file upload
             string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

             //close client after response is received
             client.Close();

             //use response to output to UI
             //service will respond with the result of the file uploaded
             return Request;
         }

public string RequestFileUploadReport(string ServiceKey, string FileToken)

{

//initialise client

NIWS_NIF.NIWS_NIFClient client = new NIWS_NIF.NIWS_NIFClient();

//call the RequestFileUploadReport method equal to a string variable

//the same service key used for the bactch file upload

string Request = client.RequestFileUploadReport(ServiceKey, FileToken);

//close client after response is received

client.Close();

//use response to output to UI

//service will respond with the result of the file uploaded

return Request;

}

Output file

File content

Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.

File 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	Name	Type	Value
1	Record identifier	AN8	###BEGIN
2	Batch name	AN	{your batch name}
3	Result of upload	A13	SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
4	Start time of report	AN8	HH:MM AM/PM
5	Batch Value	AN15	TOTAL OF BATCH
6	Action Date	AN8	CCYYMMDD

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

Field	Name	Type	Value
1	Account reference	AN58	Acc Ref :{your account reference}
2	Line number	AN	Line :{line in your file where error was found}
3	Error message	AN	The error message
OR
1	Record identifier	AN8	###ERROR
2	Error message	AN	The error message

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

Field	Name	Type	Value
1	Record identifier	AN6	###END
2	End time of report	AN8	HH:MM AM/PM

Upload report example (successful)

###BEGIN MY DEBIT BATCH SUCCESSFUL 01:59 PM R1.00 20160410

###END 01:59 PM

###BEGIN MY DEBIT BATCH SUCCESSFUL 01:59 PM R1.00 20160410

###END 01:59 PM

Upload report example (successful with errors)

###BEGIN MY DEBIT BATCH SUCCESSFUL WITH ERRORS 01:29 PM R1.00 20160410
Acc Ref :XI001 Line :3 Account details could not be validated. Please check the fields Bank account type, Branch code and Account number.
Acc Ref :XI001 Line :3 Bank account number has incorrect length (min 4, max 11 characters)
Acc Ref :HCOS01 Line :5 Beneficiary statement reference has incorrect length (min 4, max 20 characters)
Acc Ref :HCOZ01 Line :6 Beneficiary statement reference has incorrect length (min 4, max 20 characters)
###END 01:29 PM

###BEGIN MY DEBIT BATCH SUCCESSFUL WITH ERRORS 01:29 PM R1.00 20160410

Acc Ref :XI001 Line :3 Account details could not be validated. Please check the fields Bank account type, Branch code and Account number.

Acc Ref :XI001 Line :3 Bank account number has incorrect length (min 4, max 11 characters)

Acc Ref :HCOS01 Line :5 Beneficiary statement reference has incorrect length (min 4, max 20 characters)

Acc Ref :HCOZ01 Line :6 Beneficiary statement reference has incorrect length (min 4, max 20 characters)

###END 01:29 PM

Upload report example (unsuccessful)

###BEGIN MY DEBIT BATCH UNSUCCESSFUL 01:23 PM R1.00 20160410
###ERROR: A system error occurred. Please contact Sage Pay R0.00 20160410

###END 01:23 PM

###BEGIN MY DEBIT BATCH UNSUCCESSFUL 01:23 PM R1.00 20160410

###ERROR: A system error occurred. Please contact Sage Pay R0.00 20160410

###END 01:23 PM

Credit Card Vault Tokenization Web Service

Technical Information

The Sage Pay vault web service is provided for the secure storage of credit card numbers in terms of the Payment Card Industry Data Security Standard (PCI DSS). The service accepts credit card details into a secure PCI DSS compliant environment and returns a credit card token together with a masked version of the original credit card number.

The credit card token is used in all further transactions performed against the account in place of the credit card number. It is not necessary to request a new token each time a transaction is performed against the card. The token remains valid for the life of the card. (A new token should only be requested if the card details change)

This eliminates the need for vulnerable data to be transferred and stored in non-compliant environments.

Sage Pay vault is a synchronous web service. The credit card token and masked credit card number will be returned to the calling system without the need for polling or postback.

Input

Web service: https://cde.sagepay.co.za/Service/cceService.asmx
Method: AddCard
Service key: Vault service key obtained from Sage Pay Account Manager

AddCard parameters

Parameter	Format	Description
Service key	AN32	The vault service key
Cardholder name	AN30	The name of the cardholder as it appears on the front of the card
Card number	N16	The 16-digit card number (no spaces)
Expiry month	N2	The 2-digit expiry month (including leading zero. EG: 05)
Expiry year	N4	The 4-digit expiry year CCYY

Output

If the call is successful, the web service will return:

Parameter	Format	Description
Credit card token	AN36	The token for the card (to be used in future batch file uploads)
Cardholder name	AN30	The name of the cardholder as it appears on the front of the card
Masked card number	N16	The 16-digit card number (no spaces)
Expiry month	N2	The 2-digit expiry month (including leading zero. EG: 05)
Expiry year	N4	The 4-digit expiry year CCYY

These details should be used when submitting debit order batches, where the debit order is against a credit card.

If the call is unsuccessful, the web service will return one of the following error codes: –

Error code	Description
100	Authentication failure. Ensure the call has the correct Vault service key
101	Input card number failed initial validation. Check the card number and the expiry date
102	One or more input parameters are incorrect

View change log

Pay Now Invoice

Change Log