Skip to main content

Debit Order API

Endpoint: {server}/api/collections/v1/ — see Getting started for the server URL, authentication and JSON Web Tokens.

API Post Functions​

addCustomers​

Endpoint: {server}/api/collections/v1/addCustomers

addCustomers: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
testBooleanOSet to true if testing. This will bypass billing and will only validate test data
customerArrayY1-n of customer data to add

addCustomers: CUSTOMER FIELDS

NameTypeRequiredDescription
uniqueReferenceTextYYour unique customer reference identifier
customerTypeTextYIdentifies the customer. See listCustomerTypes
nameTextYThe first name of the account holder if customer type is Individual or the Entity name for all other customer types
lastNameTextCYSurname of the account holder if customer type is Individual. Required if customer type is Individual.
groupTextOThe name of a group to assign the customer to
cellNumberTextOThe customers cell phone number
emailAddressTextOThe customers email address for correspondence
vatNoTextOCustomers vat number
addressLine1TextOCustomers address
addressLine2TextOCustomers address
addressLine3TextOCustomers address
addressLine4TextOCustomers address
TownTextOCustomers address
postalCodeTextOCustomers address
paymentTypeTextYCustomer payments are done via: - EFT - Debit Order - Cash (See listPaymentTypes)
identificationTypeTextCYIdentification type. Possible values are: SID – South African ID SPP – Passport number SBR – Business registration number TRN – Trust number Required if payment type is Debit Order
identificationNumberTextCYThe account holder's identity, passport, company registration or trust number. Required if payment type is Debit Order
bankTextCYThe Bank the account is held at (see listBankOptions). Required if payment type is Debit Order
accountTypeTextCYThe account type (see listAccountTypes). Required if payment type is Debit Order
accountNumberTextCYThe account number. Required if payment type is Debit Order
branchCodeTextCYThe account branch code. Required if payment type is Debit Order
branchNameTextOThe branch name

addCustomers: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
StatusTextYNumber of customers imported
customerArrayY1-n of customer data added

addCustomers: FIELDS

NameTypeRequiredDescription
uniqueReferenceTextYYour unique customer reference identifier
statusTextYSuccess or Failed
messageTextOProvided if the status is Failed. This will be the failure reason
customerCodeTextNProvided if status is Success or there is already a customer. Customer Code is in alphanumeric format AAA000 and is the system code for the Customer

Example addCustomer Post:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

Example addCustomer response:​

:::warning Source conflict — confirm before use This example wraps the results in customers and names each entry's identifier reference, while the tables above specify customer (RESPONSE FIELDS) and uniqueReference (FIELDS). The source document is inconsistent here and the correct field names have not been confirmed with the platform team. :::

{
"jti": "<UNIQUE VALUE>",
"status": "1 of 2customer s imported",
"customers": [
{
"reference": "Ref1",
"status": "Success",
"customerCode": "JOE002"
},
{
"reference": "Ref2",
"status": "Failed",
"message": "Unique reference already exists",
"customerCode": "RON001"
}
]
}

updateCustomer​

Endpoint: {server}/api/collections/v1/updateCustomers

updateCustomer: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
customersArrayY1-n of customer update data

updateCustomer: FIELDS

NameTypeRequiredDescription
customerCodeTextYThe systems 6 character alphanumeric customerCode
uniqueReferenceTextOYour unique customer reference identifier
customerTypeTextOIdentifies the customer. See listCustomerTypes below
nameTextOThe first name of the account holder if customer type is Individual or the Entity name for all other customer types
lastNameTextOSurname of the account holder if customer type is Individual. Required if customer type is Individual.
groupTextOThe name of a group to assign the customer to
cellNumberTextOThe customers cell phone number
emailAddressTextOThe customers email address for correspondence
vatNoTextOCustomers vat number
addressLine1TextOCustomers address
addressLine2TextOCustomers address
addressLine3TextOCustomers address
addressLine4TextOCustomers address
TownTextOCustomers address
postalCodeTextOCustomers address
paymentTypeTextOCustomer payments are done via: - EFT - Debit Order - Cash (See listPaymentTypes)
identificationTypeTextOIdentification type. Possible values are: SID - South African ID SPP - Passport number SBR - Business registration number TRN - Trust number Required if Payment type is Debit Order
identificationNumberTextOThe account holder's identity, passport, company registration or trust number. Required if Debit Order
bankTextOThe Bank the account is held at (see listBankOptions). Required if payment type is EFT
accountTypeTextOThe account type (see listAccountTypes). Required if payment type is EFT
accountNumberTextCYThe account number. Required if payment type is EFT
branchCodeTextOThe account branch code. Required if payment type is EFT
branchNameTextOThe branch name

updateCustomer: RESPONSE FIELDS

NameTypeRequiredDescription
JtiTextYThe unique JWT ID
statusTextYNumber of Customers Updated
customersArrayY1-n of each customer update submission

updateCustomer: CUSTOMER FIELDS

NameTypeRequiredDescription
customerCodeTextYThe provided systems 6 character alphanumeric Customer Code
statusTestYSuccess or Failed
messageTextNProvided the status is Failed. This will be the failure reason

Example updateCustomer Post:​

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"customers": [
{
"customerCode": "JOE001",
"uniqueReference": "Ref1",
"customerType": "Individual",
"name": "Joe",
"lastName": "Soap",
"group": "Test",
"cellNumber": "0823456789",
"emailAddress": "joesoap@gmail.com ",
"addressLine1": "21 Jump Street",
"addressLine2": "Newlands",
"town": "Cape Town",
"postalCode": "7979",
"paymentType": "EFT",
"bank": "Standard Bank",
"accountType": "Cheque",
"accountNumber": "700000000",
"branchCode": "051001"
},
{
"customerCode": "RON001",
"bank": "ABSA",
"paymentType": "EFT",
"identificationType": "SID",
"identificationNumber": "7410025102082",
"accountType": "Cheque Account",
"accountNumber": "100000000",
"branchCode": " 632005"
}
]
}

Example updateCustomer Response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

listCustomers​

Endpoint: {server}/api/collections/v1/listCustomers

listCustomers: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
customerCodesTextOArray of the systems 6 character alphanumeric Customer Code

NOTE: customerCodes is optional and will return customer details of all customer codes in the request list. If customerCodes is not provided, then all customers on the system will be returned.

listCustomers: RESPONSE FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
customersTextYArray Customers

listCustomers: RESULT FIELDS

NameTypeRequiredDescription
customerCodeTextYThe systems 6 character alphanumeric Customer Code
customerTypeTextOIdentifies the customer.
nameTextOThe first name of the account holder if customer type is Individual or the Entity name for all other customer types
lastNameTextOSurname of the account holder if customer type is Individual. Required if customer type is Individual.
uniqueReferenceTextOYour unique customer reference identifier
groupTextOThe name of a group to assign the customer to
identificationTypeTextOThe customer identification type
identificationNumberTextOThe customer identity number
cellNumberTextOThe customers cell phone number
emailAddressTextOThe customers email address for correspondence
vatNoTextOCustomers vat number
addressLine1TextOCustomers address
addressLine2TextOCustomers address
addressLine3TextOCustomers address
addressLine4TextOCustomers address
TownTextOCustomers address
postalCodeTextOCustomers address
paymentTypeTextOCustomer payment type
bankTextOThe Bank the account is held at
accountTypeTextOThe account type
accountNumberTextOThe account number
branchCodeTextOThe account branch code
branchNameTextOThe branch name
messageTextOFor Invalid Customer Codes

Example listCustomers Post:​

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"customerCodes": [
"ABC001", "ABC002", "ABC003"
]
}

Example listCustomers response:​

:::warning Source conflict — confirm before use This example uses type, idType, idNumber, cellphone and email, while the RESULT FIELDS table above specifies customerType, identificationType, identificationNumber, cellNumber and emailAddress. The source document is inconsistent here and the correct field names have not been confirmed with the platform team. :::

{
"jti": "{UNIQUE VALUE}",
"status": "List of Customer s",
"customers": [
{
"customerCode": "ABC001",
"uniqueReference": "Ref1",
"idType": "Business Registration Number",
"idNumber": "2008/027519/07",
"type": "Individual",
"name": "JOE SOAP",
"group": "Test",
"cellphone": "0823456789",
"email": " joesoap@gmail.com ",
"addressLine1": "21 Jump Street",
"addressLine2": "Newlands",
"town": "Cape Town",
"postalCode": "7979",
"paymentType": "EFT",
"bank": "Standard Bank",
"accountType": "Cheque",
"accountNumber": "700000000",
"branchCode": "051001"
},
{
"customerCode": "ABC002",
"message": "Does not exist"
}
]
}

addMandate​

Endpoint: {server}/api/collections/v1/addMandate

NOTE: The addMandate method is to load mandates against existing customers setup with Debit Order payment type so that the collection can run on defined schedule. Calendar dates are in ISO 8601. Format of YYYY-MM-DD

addMandate: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
mandateTextO1-n of mandate data

addMandate: PAYMENT FIELDS

NameTypeRequiredDescription
customerCodeTextYThe systems 6-character alphanumeric Customer Code of the customer to pay
mandateTypeTextYWritten, Voice, or Digital
frequencyTextYThe collection frequency: onceoff, weekly, biweekly, monthly, bimonthly, annually, quarterly
collectionDaysTextYThe date(s), day of the week, or day of the month depending on frequency. Set day of month to 0 for last day of the month
dateFromDateYThe date from which the mandate is active from
dateToDateOThe date the mandate is active to. If not set the mandate does not expire
amountTypeTextYFixed or Variable
amountDecimalYThe collection amount. When amountType is variable this value is the maximum amount the collection can be set to
variableAmountDecimalOSet if the amountType is variable
bankReferenceTextOMaximum 7 characters. Displayed in addition to your merchant short code on the customers bank statement
annualIncreaseBooleanOSet if the mandate must have an annual increase applied
increaseTypeTextCOOptions are % for percentage increase or R for increase amount
increaseAmountDecimalCOThe value or percentage amount based on increaseType
increaseDateDateCOThe date the increase must be applied
callCabinetIDTextCOUsed if mandateType is Voice and the Call Cabinet voice recorder is used.
filenameTextCOUsed for the mandate file
fileMimeTypeTextCOIANA is the official registry of MIME media types and maintains a list of all the official MIME types
fileContentTextCOBase64 encoded file contents

addMandate: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYNumber of mandates successful out of the number of requests submitted
mandatesDecimalY1-n of each mandate submitted

addMandate: RESULT FIELDS

NameTypeRequiredDescription
customerCodeTextYThe systems 6 character alphanumeric Customer Code
mandateIDTextYSuccess or Failed
statusTextNThe mandate document ID
messageTextOFailure Reason

Example addMandate Post:​

:::warning Source conflict — confirm before use This example wraps the payload in mandates, while the POST FIELDS table above specifies mandate. The source document is inconsistent here and the correct field name has not been confirmed with the platform team. :::

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"mandates": [
{
"customerCode": "JOE001",
"mandateType": "written",
"frequency": "monthly",
"collectionDays": "1",
"dateFrom": "2021-11-01",
"dateTo": "2022-10-31",
"amountType": "variable",
"amount": 100.00,
"variableAmount": 75.00,
"bankReference": "SUPPORT",
"annualIncrease": true,
"increaseType": "%",
"increaseAmount": 10,
"increaseDate": "2022-01-01",
"filename": "mandate.pdf",
"fileMimeType": "application/pdf",
"fileContent": "/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNreQABAAQAAABkAAD/4QQIaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLwA8P3hwYWNrZXQgYmVnaW49Iu+7vyIgaWQ9Ilc1TTBNcENlaGlIenJlU3pOVGN6a2M5ZCI /PiA8eDp4bX"
},
{
"customerCode": "JAC001",
"mandateType": "voice",
"frequency": "monthly",
"collectionDays": "1",
"dateFrom": "2021-11-01",
"dateTo": "2022-10-31",
"amountType": "fixed",
"amount": 100.00,
"bankReference": "CONTRAC",
"annualIncrease": false,
"callCabinetID": "5dd1d98d-6491-11ec-b074-0242ac120004"
}
]
}

Example addMandate response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

cancelMandates​

Endpoint: {server}/api/collections/v1/cancelMandate

cancelMandates: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
mandateIDsArrayY1-n of mandate ID's

cancelMandates: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYNumber of mandates cancelled out of the number of requests submitted
mandatesArrayY1-n of each mandate ID

cancelMandates: RESULT FIELDS

NameTypeRequiredDescription
mandateIDTextYThe System's Mandate ID
statusTextYCancelled or Failed
messageTextOFailure reason

Example cancelMandates post:​

:::warning Source conflict — confirm before use This example uses mandates, while the parameter table above specifies mandateIDs. The source document is inconsistent here and the correct field name has not been confirmed with the platform team. :::

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"mandates": [
"MA04235",
"MA04236"
]
}

Example cancelMandates response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

changeMandateState​

Endpoint: {server}/api/collections/v1/changeMandateState

changeMandateState: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
mandateIDsArrayY1-n of mandate ID's
stateTextYActivate or Deactivate

changeMandateState: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYNumber of mandates cancelled out of the number of requests submitted
mandatesArrayY1-n of each mandate ID

changeMandateState: RESULT FIELDS

NameTypeRequiredDescription
mandateIDTextYThe System's Mandate ID
statusTextYCancelled or Failed
messageTextYFailure Reason

Example changeMandateState Post:​

:::warning Source conflict — confirm before use This example uses mandates, while the parameter table above specifies mandateIDs, and it omits state, which the table marks as required ("Activate or Deactivate"). The source document is inconsistent here and the correct form has not been confirmed with the platform team. :::

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"mandates": [
"MA04235",
"MA04236"
]
}

Example changeMandateState Response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

mandateStatus​

Endpoint: {server}/api/collections/v1/mandateStatus

Use one of mandateIDs or customerCodes. Should customerCode be used, all mandates linked to that customer will be returned.

mandateStatus: POST FIELDS

NameTypeRequiredDescription
TokenTextYThe signed JWT
mandateIDsArrayCO1-n of Mandate ID's
customerCodesArrayCO1-n of Customer Codes

mandateStatus: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYMandate Status Results
MandatesArrayY1-n of each Mandate ID

mandateStatus: FIELDS

NameTypeRequiredDescription
mandateIDTextYThe mandate ID
customerCodeTextYThe systems 6 character alphanumeric Customer Code
statusTextY- Active - Inactive - Authorised - Cancelled - Failed - Completed
messageTextOFailure reason
mandateTypeTextYWritten, Voice, or Digital
frequencyTextYThe collection frequency: onceoff, weekly, biweekly, monthly, bimonthly, annually, Quarterly
collectionDaysTextYThe date(s), day of the week, or day of the month depending on frequency. Set day of month to 0 (Zero) for last day of the month
dateFromDateYThe date from which the mandate is active from
dateToDateOThe date the mandate is active till
amountTypeTextYFixed or Variable
amountDecimalYThe collection amount. When amountType is variable this value is the maximum amount the collection can be set to
variableAmountDecimalOSet if the amountType is variable
bankReferenceTextOMaximum 7 characters. Displayed in addition to your merchant short code on the customers bank statement
annualIncreaseBooleanOSet if the mandate must have an annual increase applied
increaseTypeTextCOOptions are % for percentage increase or R for increase amount
increaseAmountDecimalCOThe value or percentage amount based on increaseType
increaseDateDateCOThe date the increase must be applied
lastCollectionDateDateODate of last collection
lastCollectionAmountDecimalOAmount of last collection
lastCollectionResultTextOLast collection result
lastCollectionResultMessageTextOLast collection result message

First example mandateStatus Post:​

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"mandateIDs": [
"MA04235",
"MA04236"
]
}

Second example mandateStatus Post:​

{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcGlLZXkiOiJ7UFJPVklERUQgQVBJIEtFWX0iLCJhY2Nlc3NUb2tlbiI6IntQUk9WSURFRCBBQ0NFU1MgVE9LRU59IiwianRpIjoie1VOSVFVRSBWQUxVRX0iLCJpYXQiOjE1ODk5OTA5MDIsImV4cCI6MTU4OTk5MTUwMn0._Lk6FPqYITrJIUztulif8MdvuOMAVBZXZJEiBpdSwkw ",
"customerCodes": [
"TES001"
]
}

Example mandateStatus Response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

changeVariableAmount​

Endpoint: {server}/api/collections/v1/changeVariableAmount

changeVariableAmount: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT
MandatesArrayY1-n of mandate data

changeVariableAmount: FIELDS

NameTypeRequiredDescription
mandateIDTextYThe System's Mandate ID
amountDecimalYAmount to change the variable amount to

changeVariableAmount: RESPONSE FIELDS

NameTypeRequiredDescription
JtiTextYThe unique JWT ID
statusTextYChanged or Failed
messageTextOFailure Reason

Example changeVariableAmount Post:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

Example changeVariableAmount Response:​

Example pending — this example could not be reconstructed reliably from the source document and is being prepared.

listAccountTypes​

Endpoint: {server}/api/collections/v1/listAccountTypes

listAccountTypes: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT

listAccountTypes: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYList of Account Types
accountTypesArrayY1-n of accountType

listBankOptions​

Endpoint: {server}/api/collections/v1/listBankOptions

listBankOptions: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT

listBankOptions: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYList of Account Types
bankOptionsDecimalY1-n of banks and branches

listCustomerTypes​

Endpoint: {server}/api/collections/v1/listCustomerTypes

listCustomerTypes: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT

listCustomerTypes: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYList of Account Types
customerTypesArrayY1-n of customerType

listPaymentTypes​

Endpoint: {server}/api/collections/v1/listPaymentTypes

listPaymentTypes: POST FIELDS

NameTypeRequiredDescription
tokenTextYThe signed JWT

listPaymentTypes: RESPONSE FIELDS

NameTypeRequiredDescription
jtiTextYThe unique JWT ID
statusTextYList of Account Types
paymentTypesArrayY1-n of paymentType

Errors​

If there is any submission error relating to authentication or missing fields the response fields will be:

  1. status: The status will be Error
  2. error: The error message

Example Error Message:

{
"status": "Error",
"error": "Token secret verify fail"
}