General

Customers

Manage customer records including personal details, billing and shipping addresses, ID verification, and metadata. Create, update, retrieve, and delete customer profiles for collection processing and mandate management.

Used to create, edit and archive customers.

When creating collections you can either submit a collection record with the customer details or create a customer here and then assign a customer_id to a collection record.

Create

API call to create new customer(s) as single or batch records.

WARNING
ABSA (provider bank) Registered Mandate (RM) payment methods support the company registration number ID type. You can create ABSA RM collections for companies but you can not create DebiCheck collections for companies.
Nedbank (provider bank) RM payment methods do not support company registration numbers yet.

Path

POST /customers/create

Request Body

{
  "records": [{
    "reference": "CLN240919000001",
    "company_name": null,
    "person_name": "John",
    "person_surname": "Doe",
    "client_type": "RESIDENT_INDIVIDUAL",
    "id_type": "SOUTH_AFRICAN_ID",
    "id_number": "8007014800087",
    "email": "johndoe@mail.com",
    "contact_number": "+27831234567",
    "customer_status": "ACTIVE",

    "is_tax": true,
    "tax_number": "9560164031",

    "billing_address_line_1": "145 Superior Complex",
    "billing_address_line_2": "541 New River Road",
    "city_or_town": "Pretoria",
    "postal_code": 1285,
    "billing_province_or_state": "Gauteng",
    "billing_country": "ZA",
    "billing_email": "james.may@example.com",

    "shipping_contact_name": "James May",
    "shipping_contact_number": "+27712345678",
    "shipping_address_line_1": "145 Superior Complex",
    "shipping_address_line_2": "541 New River Road",
    "shipping_city_or_town": "Pretoria",
    "shipping_postal_code": 1285,
    "shipping_province_or_state": "Gauteng",
    "shipping_country": "ZA",

    "metadata": {
      "custom_field_1": "custom data 1",
      "custom_field_2": "custom data 2",
      ...
    },
  }]
}

Response Body

The response follows the same format as the list response

{
    "status": true,
    "results": [{
        "id": "cus_9F3jl6zuRAJxuBmiN3H4D",
        "customer_status": "ACTIVE",
        ...
    }, ...]
}

Parameters

Field	Required	Type	Description	Example
id	n/a	String(32)	Record id returned	cus_9F3jl6zuRAJxuBmiN3H4D
customer_status	n/a	ENUM	(`ACTIVE`,`ARCHIVED`,`DISABLED`)	ACTIVE
deleted_at	n/a	Datetime	Date and time record was deleted	2024-02-28 12:15:15
updated_at	n/a	Datetime	Date and time record was updated	2024-02-27 16:25:39
created_at	n/a	Datetime	Date and time record was created	2024-02-27 09:11:23
reference	Y	String(35)	Reference to identify a specific customer	CLN240919000001
company_name	C	String(64)	Either a company name OR person name and surname must be provided. Company name is used when collection is made from a specific company. DebiCheck only works with individuals, not companies.	Superior Meteor Corp
person_name	C	String(32)	Name of the person to be collected from. Required for DebiCheck mandates.	John
person_surname	C	String(32)	Surname of the person to be collected from. Required for DebiCheck mandates.	Doe
client_type	N	ENUM	For use with Nedbank payment methods (payment_methods.provider_bank is Nedbank). Defaults to Resident individual / Domestic company. (`DOMESTIC_COMPANY`,`FINANCIAL_INSTITUTION`,`FOREIGN_COMPANY`,`NONRESIDENT_INDIVIDUAL`,`RESIDENT_INDIVIDUAL`)	RESIDENT_INDIVIDUAL
id_type	C	ENUM	Required field for DebiCheck. Note: Company Registration Number type lookup only applies to ABSA Registered Mandates. (`COMPANY_REGISTRATION_NUMBER`,`PASSPORT_NUMBER`,`SOUTH_AFRICAN_ID`,`TEMPORARY_RESIDENCE`)	SOUTH_AFRICAN_ID
id_number	C	String(14)	Required field for DebiCheck. ID number relating to the ID type	8007014800087
email	Y	String(128)	Valid email address of the person to be collected from	johndoe@mail.com
contact_number	C	String(16)	Mobile contact number of the person to be collected from. Must include the area code. Required for DebiCheck mandates	+27831234567
is_tax	N	Boolean	true - Customer is taxed	true
tax_number	N	String(64)	Customer tax number	9560164031
billing_address_line_1	N	String(128)	First line of address for the person to be collected from. Should be the street address if no complex number is applicable.	145 Superior Complex
billing_address_line_2	N	String(128)	Second line of address for the person to be collected from. Should be the street address if a complex was used on line 1.	541 New River Road
city_or_town	N	String(64)	City/Town where billing address is located in.	Pretoria
postal_code	N	Integer	Postal code related to the billing address.	1285
billing_province_or_state	N	String(64)	Province/State where billing address is located in.	Gauteng
billing_country	N	ENUM	Country where billing address is located in. (`ZA`, `AU`, `GB`, `US`, etc.)	ZA
billing_email	N	String(128)	Email related to the billing address	james.may@example.com
shipping_contact_name	N	String(128)	Shipping contact name	James May
shipping_contact_number	N	String(16)	Shipping contact person's cellphone/telephone number.	+27712345678
shipping_address_line_1	N	String(128)	First line of address for the person to be shipped to. Should be the street address if no complex number is applicable.	145 Superior Complex
shipping_address_line_2	N	String(128)	Second line of address for the person to be shipped to. Should be the street address if a complex was used on line 1.	541 New River Road
shipping_city_or_town	N	String(64)	City/Town where shipping address is located in.	Pretoria
shipping_postal_code	N	Integer	Postal code related to the shipping address.	1285
shipping_province_or_state	N	String(64)	Province/State where billing shipping is located in.	Gauteng
shipping_country	N	ENUM	Country where shipping address is located in. (`ZA`, `AU`, `GB`, `US`, etc.)	ZA
metadata	N	JSON	Any additional meta data	{}

Update

API call to update existing customer(s) as single or batch records. Records can not be deleted, only archived.

Path

POST /customers/update

WARNING
Updating customer details here will not update a DebiCheck mandate / Registered Mandate, to update DebiCheck mandates / Registered mandates check the mandates update section.
Likewise customer updates will only update the connected collections if those collections are running EFT debit orders and not DebiCheck / Registered Mandates. For DebiCheck / RM it is best to pause the old collections and create a new collection once the mandate changes have been approved.
If you archive/disable a customer then it will not cancel a DebiCheck mandate / Registered Mandate. A customer can not be archived/disabled if you have running collections for the customer you need to stop the related collections first.

Request Body

Only include fields you wish to change (besides id used to find the record). Setting a column to null e.g. city_or_town = null will clear that fields' value if allowed

{
  "records": [{
    "id": "cus_9F3jl6zuRAJxuBmiN3H4D",
    "reference": "CLN240919000001",
    "company_name": null,
    "person_name": "John",
    "person_surname": "Doe",
    "client_type": "RESIDENT_INDIVIDUAL",
    "id_type": "SOUTH_AFRICAN_ID",
    "id_number": "8007014800087",
    "email": "johndoe@mail.com",
    "contact_number": "+27831234567",
    "customer_status": "ACTIVE",

    "is_tax": true,
    "tax_number": "9560164031",

    "billing_address_line_1": "145 Superior Complex",
    "billing_address_line_2": "541 New River Road",
    "city_or_town": "Pretoria",
    "postal_code": 1285,
    "billing_province_or_state": "Gauteng",
    "billing_country": "ZA",
    "billing_email": "james.may@example.com",

    "shipping_contact_name": "James May",
    "shipping_contact_number": "+27712345678",
    "shipping_address_line_1": "145 Superior Complex",
    "shipping_address_line_2": "541 New River Road",
    "shipping_city_or_town": "Pretoria",
    "shipping_postal_code": 1285,
    "shipping_province_or_state": "Gauteng",
    "shipping_country": "ZA",

    "metadata": {
      "custom_field_1": "custom data 1",
      "custom_field_2": "custom data 2",
      ...
    }
  }]
}

Response Body

The response follows the same format as the list response

{
    "status": true,
    "results": [{
        "id": "cus_9F3jl6zuRAJxuBmiN3H4D",
        "customer_status": "ACTIVE",
        ...
    }, ...]
}

Parameters

Field	Required	Type	Description	Example
id	Y	String(32)	Record id to update	cus_9F3jl6zuRAJxuBmiN3H4D
reference	Y	String(35)	Reference to identify a specific customer	CLN240919000001
company_name	C	String(64)	Either a company name OR person name and surname must be provided. Company name is used when collection is made from a specific company. DebiCheck only works with individuals, not companies. Only applies to EFT DO payment methods and RM payment methods provided by ABSA.	Superior Meteor Corp
person_name	C	String(32)	Name of the person to be collected from. Required for DebiCheck mandates.	John
person_surname	C	String(32)	Surname of the person to be collected from. Required for DebiCheck mandates.	Doe
client_type	N	ENUM	For use with Nedbank payment methods (payment_methods.provider_bank is Nedbank). Defaults to Resident individual / Domestic company. (`DOMESTIC_COMPANY`,`FINANCIAL_INSTITUTION`,`FOREIGN_COMPANY`,`NONRESIDENT_INDIVIDUAL`,`RESIDENT_INDIVIDUAL`)	RESIDENT_INDIVIDUAL
id_type	C	ENUM	Required field for DebiCheck. Note: Company Registration Number type lookup only applies to ABSA Registered Mandates. (`COMPANY_REGISTRATION_NUMBER`,`PASSPORT_NUMBER`,`SOUTH_AFRICAN_ID`,`TEMPORARY_RESIDENCE`)	SOUTH_AFRICAN_ID
id_number	C	String(14)	Required field for DebiCheck. ID number relating to the ID type	8007014800087
email	N	String(128)	Valid email address of the person to be collected from	johndoe@mail.com
contact_number	C	String(16)	Mobile contact number of the person to be collected from. Must include the area code. Required for DebiCheck mandates	+27831234567
customer_status	n/a	ENUM	(`ACTIVE`,`ARCHIVED`,`DISABLED`)	ACTIVE
is_tax	N	Boolean	true - Customer is taxed	true
tax_number	N	String(64)	Customer tax number	9560164031
billing_address_line_1	N	String(128)	First line of address for the person to be collected from. Should be the street address if no complex number is applicable.	145 Superior Complex
billing_address_line_2	N	String(128)	Second line of address for the person to be collected from. Should be the street address if a complex was used on line 1.	541 New River Road
city_or_town	N	String(64)	City/Town where address lines 1 and 2 are located in.	Pretoria
postal_code	N	Integer	Postal code related to address lines 1 and 2.	1285
billing_province_or_state	N	String(64)	Province/State where billing address is located in.	Gauteng
billing_country	N	ENUM	Country where billing address is located in. (`ZA`, `AU`, `GB`, `US`, etc.)	ZA
billing_email	N	String(128)	Email related to the billing address	james.may@example.com
shipping_contact_name	N	String(128)	Shipping contact name	James May
shipping_contact_number	N	String(16)	Shipping contact person's cellphone/telephone number.	+27712345678
shipping_address_line_1	N	String(128)	First line of address for the person to be shipped to. Should be the street address if no complex number is applicable.	145 Superior Complex
shipping_address_line_2	N	String(128)	Second line of address for the person to be shipped to. Should be the street address if a complex was used on line 1.	541 New River Road
shipping_city_or_town	N	String(64)	City/Town where shipping address is located in.	Pretoria
shipping_postal_code	N	Integer	Postal code related to the shipping address.	1285
shipping_province_or_state	N	String(64)	Province/State where billing shipping is located in.	Gauteng
shipping_country	N	ENUM	Country where shipping address is located in. (`ZA`, `AU`, `GB`, `US`, etc.)	ZA
metadata	N	JSON	Any additional meta data	{}

List

List customers loaded on the platform.

Path

GET /customers/list?{params}

Query Parameters

Field	Type	Required	Description	Example
customer_status	ENUM	N	Filter for a specific customer status. (`ACTIVE`,`ARCHIVED`,`DISABLED`).	ACTIVE
date_start	Date(YYYY-MM-DD)	N	Filter for records that have a created date after this date specified.	2024-09-13
date_end	Date(YYYY-MM-DD)	N	Filter for records that have an created date before this specified date	2025-04-24
customer_id	String(32)	N	Filter for a specific customer id.	cus_9F3jl6zuRAJxuBmiN3H4D
customer_reference	String(35)	N	Filter for a specific customer reference.	CLN240919000001
customer_company_name	String(64)	N	Filter for a specific customer company names.	Fast Corp LTD
customer_person_name	String(32)	N	Filter for a specific customer name.	John
customer_person_surname	String(32)	N	Filter for a specific customer surname.	Doe
customer_id_number	String(32)	N	Filter for a specific customer ID Number.	7807085800085
customer_email	String(128)	N	Filter for a specific customer email.	johndoe@mail.com
customer_contact_number	String(19)	N	Filter for a specific customer contact number.	27831234567

Response Body

{
  "status": true,
  "results": [{
    "id": "cus_9F3jl6zuRAJxuBmiN3H4D",
    "customer_status": "ACTIVE",
    "deleted_at": null,
    "updated_at": null,
    "created_at": "2024-02-27 09:11:23",
    "reference": "CLN240919000001",
    "company_name": null,
    "person_name": "John",
    "person_surname": "Doe",
    "client_type": "RESIDENT_INDIVIDUAL",
    "id_type": "SOUTH_AFRICAN_ID",
    "id_number": "8007014800087",
    "email": "johndoe@mail.com",
    "contact_number": "+27831234567",
    "is_tax": true,
    "tax_number": "9560164031",
    "billing_address_line_1": "145 Superior Complex",
    "billing_address_line_2": "541 New River Road",
    "city_or_town": "Pretoria",
    "postal_code": 1285,
    "billing_province_or_state": "Gauteng",
    "billing_country": "ZA",
    "billing_email": "james.may@example.com",
    "shipping_contact_name": "James May",
    "shipping_contact_number": "+27712345678",
    "shipping_address_line_1": "145 Superior Complex",
    "shipping_address_line_2": "541 New River Road",
    "shipping_city_or_town": "Pretoria",
    "shipping_postal_code": 1285,
    "shipping_province_or_state": "Gauteng",
    "shipping_country": "ZA",
    "metadata": {
      "custom_field_1": "custom data 1",
      "custom_field_2": "custom data 2",
      ...
    }
  }, ...]
}

Payment Methods

Retrieve available payment methods including EFT Debit Orders, DebiCheck, Registered Mandates, Card payments, and Pay-in methods. Essential for determining supported banks and payment options for your customers.

Bank Accounts

Manage customer bank account details including account numbers, branch codes, account types, and bank verification. Required for EFT Debit Orders, DebiCheck, and Registered Mandate processing.