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