eMandate Synchronous Service

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

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:

• Web service: https://ws.netcash.co.za/niws/niws_nif.svc
• Method: AddMandate
• Service key: Debit Order service key

Input

The fields indicated by are mandatory for this method

Field name	M	Type	Explanation
ServiceKey		String	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 bank account or Name as it appears on Credit card
BankAccountNumber#		String	Bank account number
BranchCode#		String	Branch code must be 6 digits. Pre-fill with zeroes if less than 6
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 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 which may delay the response
AVSCheckNumber		String	ID number
IncludeDebiCheck		Boolean	False (EFT mandate only) True (Include DebiCheck Authentication with EFT mandate)
DebiCheckMandateTemplateId		String	Id of pre-defined DebiCheck mandate template
DebiCheckCollectionAmount		Decimal	The amount of the DebiCheck mandate
DebiCheckFirstCollectionDiffers		Boolean	False (1st collection same as mandate) True (1st collection differs from mandate)
DebiCheckFirstCollectionAmount		Decimal	The first collection amount of the DebiCheck mandate
DebiCheckCollectionDayCode		String	CCYYMMDD
AddToMasterFile		B	Default=0

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

Unsuccessful request

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

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

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

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