Before you start

Please download the suggested API integration process flow document and use it as a reference when developing.
Kindly adhere to the Netcash brand guidelines when developing.

Programmers Guide

Refer to our Programmers guide for more detail on how to apply the required methodology in this document.
Ensure that the settings for developers are adhered to before you proceed with your implementation.

Web Service Methods

The list of Netcash web service methods can be found here.

Quick Start Guides

Quick Start Guides will help you understand this service and get you started.

Overview

e-Mandate request is a web service that allows a remote system to send batched electronic requests for electronic debit order mandates to account holders for authorization.

Technical Information

 

 

Input

Requests to the web service is sent as a string.

Example:  public string BatchFileUpload(string ServiceKey, string File)

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 Netcash Technical Support.

Input File Structure

Each file has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Netcash 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)

files must contain a header record being the first record in the file.

Record Structure

Field

Name

Type

Value

1

Record Identifier

AN

H

2

Service Key

AN

Service GUID

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 key

AN

The key issued by Netcash to identify the software origin of transactions. (only used by Netcash


Field explanations

Field Explanation
Record Id “H” – Identifies the record as a header
Service key Debit order service key
Version “1” – This is the Netcash version of the file specification
Instruction Mandates
Batch name Use this field as an identifier of your batch.
Action date Current date
Software Vendor Key The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)


Example
  H C74EF975-5429-4663-85FB-2A64CA0FB9EF 1 Mandates My Test Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080

 

Key record (K)

  • The key record is mandatory and appears in the file between the header record and the transaction records.
  • The key record is mandatory and appears in the file between the header record and the transaction records.
  • The key defines the content, order and length of the transaction 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 102 161 162 110 114 113 121 122 123 202 530 531 532 534 535 536 540 541 202 311

 

Transaction record (T)

  • There must be at least one transaction record in the file.
  • 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 138) is defined as the first field in the record, therefore, every transaction record MUST have the Budget 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 Netcash system will assume spaces or zeroes for fields defined in the key record.


Mandatory fields

The fields indicated by are mandatory for the specified instruction.

Key Field name Mandatory
See key legend for value requirements
101 Account reference
102 Mandate name
103 Mandate active
110 Is Consumer
113 Surname
114 First name
119 Title
121 Trading name
122 Registration number
123 Registered name
126 Bank account verification number (ID number/Company registration number)
127 Is ID number
131# Mandate type (Bank account or Credit card)
132# Bank account name/Name on Credit card
133# Bank account type/Credit card type
134# Branch code/Expiry month
135# Filler/Expiry year
136# Bank Account number / Credit card token
161 Default mandate amount
162 Mandate amount
201 Email address
202 Account holder mobile number (N10) eg. 0801234567
241 Include DebiCheck authentication
242 DebiCheck mandate template Identifier
243 DebiCheck collection amount
244 DebiCheck number of debits
245 DebiCheck mandate initiation date
246 DebiCheck first collection differs
247 DebiCheck first collection amount
248 DebiCheck first collection date
281 Debit Masterfile group
311 Field 1
312 Field 2
313 Field 3
314 Field 4
315 Field 5
316 Field 6
317 Field 7
318 Field 8
319 Field 9
530 Debit Frequency
531 Commencement month
532 Commencement day (debit day options)
533 December debit day
534 Agreement date
535 Agreement reference number
536 Cancellation notice period
537 Allow variable debit amounts
538 Request AVS
539 Additional clauses
540 Send mandate
541 Debit day on a public holiday
542 Add to Masterfile

If one or more of the banking/card detail fields indicated by a “#“ above is included in the transaction line; all the banking/card detail fields indicated by # above become mandatory. Although not mandatory for using this web service; fields 131 – 136 must all be present in the request if one or more of the fields (131-136) are sent,

Field explanations

Field Name Type Value
See key legend for value requirements
101 Mandate reference AN22 The unique reference for this client. Use the Masterfile reference if the client already exists in your debit order Masterfile.
102 Mandate name AN50 The name of your client’s account on the Netcash system
103 Mandate active N1 0 = Inactive
1 = Active
110 Consumer/Commercial N 0 = Company
1 = Individual
113 Surname AN50 Your client’s surname. For a Commercial mandate, the surname of the person who will sign the mandate
114 First name AN50 Your client’s first name. For a Commercial mandate, the first name of the person who will sign the mandate
117 Date of birth N8 CCYYMMDD
119 Title N1 1 = Mr
2 = Mrs
3 = Ms
4 = Miss
5 = Dr
6 = Prof
121 Company trading name AN50 trading name of the company signing the mandate (leave blank for individuals)
122 Company registration number AN50 registration number of the company signing the mandate (leave blank for individuals)
123 Company registered name AN50 registered name of the company signing the mandate (leave blank for individuals)
126 Bank account verification number AN This field contains the identifying number linked to the bank account.
(EG: ID number or Company registration number of the account holder)
127 Is SA ID number N1 Indicates whether field 126 (Bank account verification number) is an SA Identity number.
0 = Not an SA ID number
1 = SA Id number (SA ID numbers will be validated before being sent to the bank)
131 Banking detail type N1 1 = Bank account
2 = Credit card
132 Bank account name AN30 The name of the bank account to be debited
133 Bank account type N1 If Bank account:
1 = Current
2 = SavingsIf Credit card:
1 = MasterCard
2 = Visa
134 Branch code/Expiry month N6 If Bank account:
The branch code of the account to be debited.
Must be 6 digits (pre-fill with zeroes if less than 6 (EG: 051001)If Credit card:
MM – The two-digit expiry month of the card (EG: 02)
135 Expiry year / Filler N4 If Bank account: 0
If Credit card: CCYY – The four-digit expiry year of the card (EG: 2021)
136 Bank account number/CC token AN36 If Bank account:
The bank account number to be debited.
Must be 6 digits (pre-fill with zeroes if less than 6 (EG: 051001)If Credit card:
The PCI credit card token
161 Mandate amount N The amount of the mandate (in cents)
202 Mobile number N11 The mobile number of the person signing the mandate
201 Email address AN50 The email address of the account holder. one email address is permitted
241 Include DebiCheck authentication N1 Indicates whether DebiCheck authentication is requested in addition to the Mandate
0 = Do not request DebiCheck authentication
1 = Request DebiCheck authentication
242 Debicheck mandate template Identifier AN The identifier of the DebiCheck template to be used to generate this mandate
eg.: NCDCT000000001
242 Debicheck mandate template Identifier AN The identifier of the DebiCheck template to be used to generate this mandate
eg: NCDCT000000001
243 DebiCheck collection amount N The amount of the DebiCheck mandate (in cents)
244 DebiCheck number of debits N The number of collections specified in the mandate
245 DebiCheck mandate initiation date N8 CCYYMMDD
246 DebiCheck first collection differs N1 0 = Amount of the 1st debit is the same as 243 DebiCheck collection amount
1 = Amount of the 1st debit differs from 243 DebiCheck collection amount
247 DebiCheck first collection amount N The amount of the 1st collection (in cents)
248 Debicheck first collection date N8 CCYYMMDD
281 Debit Masterfile group AN Links this mandate to an existing group
(Validation will fail if the group does not exist)
311 Field 1 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
312 Field 2 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
313 Field 3 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
314 Field 4 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
315 Field 5 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
316 Field 6 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
317 Field 7 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
318 Field 8 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
319 Field 9 AN50 Custom User Defined data
(Extra data can be stored with this mandate record)
341 Phone number N11 The phone number of the person signing the mandate
530 Debit frequency N1 1 = Monthly
2 = Twice monthly (bi-monthly)
3 = Three monthly (quarterly)
4 = 6 Monthly (semi-annually)
5 = Annually
6 = Weekly
7 = Twice weekly (bi-weekly)
531 Commencement month N2 01 – 12 (MM)
532 Commencement day AN100 01 – 31 or Last day of the month.
Forward slash-separated list of options EG: 05/15/25/LDOM ( Last Day of Month)
533 December debit day AN100 01 – 31 or Last day of the month.
Forward slash-separated list of options EG: 05/15/25/LDOM( Last Day of Month)
534 Agreement date N8 CCYYMMDD
535 Agreement reference number AN50 Agreement reference
536 Cancellation notice period N2 01 – 60
537 Allow variable amounts N1 0 = Do not allow variable amounts
1= Allow variable amounts
538 Request AVS N1 0 = Do not run Bank account verification check
1= Run Bank account verification check
539 Additional clauses AN The ID of additional clauses to be included in the mandate (Comma separated list)
540 Send mandate N1 0 = Do not automatically send mandate for signature
1 = Automatically send valid mandates to the account holder for signature
541 Debit day on public holiday N1 Alternate debit day if debit day, if selected debit day falls on a non-business date
0 = Preceding ordinary business day
1 = Very next ordinary business day
542 Add to Masterfile field B 0 = False

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

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

Retrieving the Load Report

Postback option

Where the postback option in your NetConnector profile is utilised, the load report is automatically posted back to the URL specified.

Polling option

You will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

Requests to the web service are sent as strings

Example:

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;
}

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

Unique reference

AN25

The unique reference you supplied in (p2)

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

Retrieve Batch Status

Click here for the Netcash Retrieve batch status file format. Retrieve Batch Status is a web service that allows a user to retrieve up to the last 10 (ten) batches uploaded to the Netcash system. The web service will return all batches, whether they were uploaded via the web service or manually created via the Netcash web site.

Netcash brand guidelines

Please refer to the Netcash brand guidelines here when using any logos, images, icons, labels, descriptions, and references to Netcash in your software.

Testing

See Testing section for more details. If you require any integration assistance contact our technical support team

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.