Currently set to Index
Currently set to Follow
  1. Home
  2. /
  3. Inbound Payments
  4. /
  5. Electronic Debit Order Mandates
  6. /
  7. Electronic Mandates Synchronous Web...

Overview

e-Mandate synchronous service is a web service that allows the generation of a debit order mandate which is displayed to the bank account holder or cardholder for signature with the result posted back to a user-defined URL. Any software which requires the immediate acceptance of a mandate by a cardholder and submits a single mandate request at a time should use this method.

In cases where the cardholder is not online and expecting the mandate or where multiple mandates are submitted at once, the host system should use the NIWS_NIF batch file upload service which is better suited to such a requirement.

The AddMandate service requires a URL to be set up by the integrator to which signed mandate data can be posted.
It is suggested that the URL is different from the postback URL used for normal debit order batch file processing postbacks.

Web Service Methods

The list of Netcash web service methods can be found here

QuickStart Guides

We have developed some Quick Start Guides to help you understand this service and to help you get started.

Programmers Guide

To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

Process Flow

Technical Information

AddMandate is an online, synchronous web service which allows an external system to generate a single mandate for immediate signature and receive a response posted to the URL configured for the purpose. This service permits only a single request per web service call

From your application call:

Input

Mandatory fields

The fields indicated by are mandatory for the specified instruction

 

Field name Mandatory

 

Field Type Field Explanation
ServiceKey String The Debit Order service key
AccountReference String The unique reference you will use in the future to address this mandate. (If the client exists in your Debit Order master file, use the Debit Order master file reference)
Minimum 2 Maximum 22 characters
MandateName String Your client’s name
MandateAmount Decimal The amount of the mandate (Example 100.00)
IsConsumer Boolean False (Business)
True (Individual)
FirstName String Account holder first name
Surname String Account holder surname
TradingName String Business account name (this parameter is mandatory, leave blank for Individual)
RegistrationNumber String Business account registration number (this parameter is mandatory, leave blank for Individual)
RegisteredName String Business account registered name (this parameter is mandatory, leave blank for Individual)
MobileNumber String Account holder cell number. (EG: 0825551234)
DebitFrequency Enum

MandateOptions.MandateDebitFrequency

Monthly
Bimonthly
ThreeMonthly
SixMonthly
Annually
Weekly
Biweekly
CommencementMonth Int32 MM
CommencementDay String Debit day options
01 – 31 or Last day of month
Forward slash-separated list (EG: 05/15/25/LDOM)
AgreementDate String CCYYMMDD
AgreementReferenceNumber String Agreement reference (Max 50 characters)
CancellationNoticePeriod Int32 01 – 60
PublicHolidayOption Enum

MandateOptions.MandatePublicHolidayOption

PrecedingOrdinaryBusinessDay
VeryNextOrdinaryBusinessDay
Notes String Additional notes
Field1 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field2 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field3 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field4 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field5 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field6 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field7 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field8 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
Field9 String Custom User Defined data (Extra data to be stored with this mandate record) Max 50 characters
AllowVariableDebitAmounts Boolean False (No variable amounts)
True (Variable amount allowed)
BankDetailType# Int32 1 = Bank account
2 = Credit card
BankAccountName# String Name of the bank account holder or
Name as it appears on Credit card
BankAccountNumber# String Bank account number
BranchCode# String The branch code must be 6 digits. (Pre-fill with zeros if less than 6 chars)
BankAccountType# String Current
Savings
Transmission
CreditCardToken String PCI Token generated for Credit card processing
CreditCardType Int32 1 = Mastercard
2 = Visa
ExpiryMonth Int32 2 digit month (MM) include leading zero
ExpiryYear Int32 4 digit year (CCYY)
IsIdNumber Boolean False = Not an SA Id number
True = SA Id number
Title Enum

MandateOptions.Title

Mr
Mrs
Ms
Miss
Dr
Prof
Rabbi
Ds
Adv
NotSet
EmailAddress String The email address of the account holder (The “@” and “.” Symbols are allowed in this field)
PhoneNumber String Account holder phone number (EG: 0115551234)
DateOfBirth String CCYYMMDD
DecemberDebitDay String 01 – 31 or Last day of the month
Forward slash-separated list EG: 05/15/25/LDOM (Default December debit day is Commencement day)
DebitMasterfileGroup String Links this mandate to an existing group (Validation will fail if the group does not exist)
PhysicalAddressLine1 String min:2, max:50
PhysicalAddressLine2 String min:2, max:50
PhysicalAddressLine3 String min:2, max:50
PhysicalSuburb String min:2, max:50
PhysicalCity String min:2, max:50
PhysicalProvince String min:2, max:50
PhysicalPostalCode String EG: 1000
MandateActive Boolean False (Inactive)
True (Active)
(If active and the Debit Order master file is updated, the entry in the master file will also be active)
RequestAVS Boolean False (Do not run Bank account verification check)
True (Run Bank account verification check – Not recommended for AddMandate as AVS is an asynchronous service that may delay the response

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 becomes 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, none of the fields can be sent without the others.

Output

On submission, the service responds with a code to indicate success/failure of the submission.

For successful submissions, the Netcash Mandate service will construct the mandate and return a Netcash Mandate site URL to which the calling system should redirect the browser. The URL is the site on which the account holder accepts and signs the mandate

Numeric Response Description

000

Success (includes redirect URL)


Unsuccessful request

If the method call fails, the web service will return an error code:

Numeric Response Description

100

Authentication error

200

Web service error contact support@netcash.co.za

203

Failed – check Warnings and Errors array for messages

Examples

Success

<AddMandate>
  <MethodParameters>
    <AddMandateResponse>
      <Errors attr0="StringArray" isNull="false" />
      <MandateUrl>https://short.surf/SPDxhL</MandateUrl>
      <Warnings attr0="StringArray" isNull="false" />
      <ErrorCode>000</ErrorCode>
    </AddMandateResponse>
  </MethodParameters>
</AddMandate>

Failure

<AddMandate>
  <MethodParameters>
    <AddMandateResponse>
      <Errors attr0="StringArray" isNull="false">
        <StringArray0>CommenceMonth out of range (1-12)</StringArray0>
      </Errors>
      <MandateUrl isNull="true" />
      <Warnings attr0="StringArray" isNull="false" />
      <ErrorCode>203</ErrorCode>
    </AddMandateResponse>
  </MethodParameters>
</AddMandate>

 

If there is no error the short URL to the Netcash mandate site will be returned.

Redirect on signature

If The host system should redirect the browser to the Short URL returned in the response above.

The account holder will use the One Time PIN sent from the Netcash system to access the mandate.

 

POST to host system

The account holder completes the mandate detail and digitally signs the mandate.

On signature the Netcash mandate site generates a Form POST to the host system containing the details of the mandate and two additional fields:

MandateSuccessful
ReasonForDecline

AccountRef	FINALtestABC
AccountName	FINALtestABC
DefaultAmount	11.0000
AllowVariableAmounts	False
IsActive	True
IsValid	True
IsFromWebService	False
MandateStatus	6
CompTradingName	
CompRegName	
CompRegNo	
FirstName	ABCtest
LastName	DEFtest
ContactPerson	ABCtest DEFtest
Email	abc@def.com
CellNo	0812345678
TelephoneNumber	
IsRSAId	True
IdentityNumber	3706220230085
PhysicalComplex	
PhysicalStreetAddress	
PhysicalSuburb	
PhysicalCity	
PhysicalAddressPostcode	
Field1	
Field2	
Field3	
Field4	
Field5	
Field6	
Field7	
Field8	
Field9	
NotificationEmail	
NotificationByEmailActive	False
NotificationCellNo	
NotificationByCellNoActive	False
AgreementDate	2020-12-25 12:00:00 AM
DebitDay	25
DecemberDebitDay	25
DebitOnLastDay	False
MandateReferenceNumber	FINALtest
NoticeDays	20
LuMandatePublicHolidayOptionId	1
DoAVS	False
MandateDebitFrequencyId	5
SignBy_FirstName	ABCtest
SignBy_LastName	DEFtest
SignBy_Email	abc@def.com
SignBy_CellNo	0812345678
IsCreditCard	False
BankName	ABSA
BankAccountName	FINALtest
BankAccountNo	321*****7
BranchCode	632005
BankAccountType	Current
CCAccountName	
CCAccountNo	
CCType	
CCExpYYYY	
CCExpMM	
CCToken	
IsDeclined 0
ReasonForDecline 
MandateSuccessful 1
AdditionalClauses 0001,0012,0245
MandatePDFLink  https://short.surf/SPtzT8
https://short.surf/SPtZS9

Postback URL

To facilitate the POST, the host system must supply a postback URL.

The URL is set up once in the Debit order section of the NetConnector page

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.

Version 2020.1

Copyright © 2021 Netcash (PTY) Ltd