Customers
Manage customer records including personal details, billing and shipping addresses, ID verification, and metadata. Create, update, retrieve, and delete customer profiles for payment processing and mandate management.
Used to create, edit and archive customers.
When creating payments you can either submit a payment record with the customer details or create a customer here and then assign a customer_id to a payment record.
Create
API call to create new customer(s) as single or batch records.
WARNINGABSA (provider bank) Registered Mandate (RM) payment methods support the company registration number ID type. You can create ABSA RM payments for companies but you can not create DebiCheck payments 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": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
},
"customer_status": "ACTIVE",
}]
}
Response Body
{
"status": true,
"results": [{
"id": "cus_abc123...",
"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": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | cus_abc123... |
| 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(13) | Required field for DebiCheck. ID number relating to the ID type | 900112... |
| 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 |
| 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 |
| metadata | N | JSON | Any additional meta data | {} |
| customer_status | n/a | ENUM | (ACTIVE,ARCHIVED,DISABLED) | ACTIVE |
| created_at | n/a | Datetime | Date and time record was created | 2024-02-27 09:11:23 |
Update
API call to update existing customer(s) as single or batch records. Records can not be deleted, only archived.
Path
POST /customers/update
WARNINGUpdating 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 payments if those payments are running EFT debit orders and not DebiCheck / Registered Mandates. For DebiCheck / RM it is best to pause the old payment and create a new payment 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 payments for the customer you need to stop the related payments 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_abc123...",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"customer_status": "ACTIVE",
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}]
}
Response Body
{
"status": true,
"results": [{
"id": "cus_abc123...",
"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": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | Y | String(32) | Record id to update | cus_abc123... |
| 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(13) | Required field for DebiCheck. ID number relating to the ID type | 900112... |
| 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 |
| 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 |
| customer_status | n/a | ENUM | (ACTIVE,ARCHIVED,DISABLED) | ACTIVE |
| created_at | n/a | Datetime | Date and time record was created | 2024-02-27 09:11:23 |
| updated_at | n/a | Datetime | Date and time record was last updated | 2024-02-27 09:11:23 |
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_abc123... |
| 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_abc123...",
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "900112....",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
"billing_address_line_1": "145 Superior Complex",
"billing_address_line_2": "541 New River Road",
"city_or_town": "Pretoria",
"postal_code": 1285,
"customer_status": "ACTIVE",
"metadata": {
"custom_field_1": "custom data 1",
"custom_field_2": "custom data 2",
...
},
"updated_at": "2024-03-17 12:35:24",
"created_at": "2024-02-27 09:11:23",
}, ...]
}
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 payment processing.