Integration | Sage Pay | Technical Guide | Debit Order Collection

Please take note:

This file specification for standard debit order collection -and excludes NAEDO and CREDIT CARD debit orders.

Should you like to process NAEDO and CREDIT CARD debit orders; the current integration specification is available here. These (NAEDO -and CREDIT CARD) formats will be phased out over time to make way for this new (below) infrastructure with its added functionality and the new specifications of all such debit orders will be made available in due course. The old production formats will be acceptable on the new infrastructure for the time being as the systems are backwards compatible. (Please contact technical support for details)
It is however highly advisable to keep the expected changes in mind for full –and seamless functionality and to minimize development costs in future.

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 Dated debit orders (Sameday / Two day) for processing.

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)

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

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

H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 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

K 101 111 131 132 133 134 135 136

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.

Mandatory field

The fields indicated by tick are mandatory for the specified instruction.

Key Field name Update SameDay/TwoDay
101 Account reference tick tick
102 Account name tick tick
103 Account active
104 Delete this account
131 Banking detail type tick tick
132 Bank account name tick tick
133 Bank account type tick tick
134 Branch code tick tick
135 Filler tick tick
136 Bank account number tick tick
161 Default debit amount tick
162 Amount tick
201 Email address
202 Mobile number
281 Debit masterfile group
301 Extra 1
302 Extra 2
303 Extra 3

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.
161 Default payment amount N  The default amount to be set in the masterfile (in cents)
162 Payment 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

F 2 0 9999

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 Dated 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

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

Version 1.3/2016 last updated 10 Apr 2016