Specification
Mandates
Mandates API calls
Used to create (DebiCheck: authenticate), edit (DebiCheck: Update, Reauthorise or Cancel) and archive mandates.
When creating payments you can either submit a payment record with the customer, bank accounts and mandate details or create a mandate here and then assign a customer_id, bank_account_id and mandate_id to a payment record.
Create
API call to create (DebiCheck: authenticate) new mandates(s) as single or batch records.
Path
POST /mandates/create
Request Body
{
"records": [{
"customer_id": "cus_abc123...",
"bank_account_id": "ban_abc123...",
"payment_methods_id": "pam_abc123...",
// Not applicable to DebiCheck
"mandate_status_lookups_id": "loo_abc123...",
"amount": "45.00",
// required for recurring payments
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
// used with one-time payments
"one-time": {
"process_date": "2024-10-25"
},
// required if Payment method is DebiCheck or EFT Debit Order
"payment_industry_lookups_id": "loo_abc123...",
// required if Payment Method is DebiCheck
"debicheck": {
"contract_reference": "CTC24091900001",
"first_collection_amount": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category_lookups_id": "loo_abc123...",
"adjustment_type_lookups_id": "loo_abc123...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window_lookups_id": "loo_abc123..."
}
}]
}
Example: One-time EFT Debit Order
{
"records": [{
"customer_id": "cus_...",
"bank_account_id": "ban_...",
"payment_methods_id": "pam_...",
"mandate_status_lookups_id": "loo_...",
"amount": "45.00",
"one-time": {
"process_date": "2025-06-25"
},
"payment_industry_lookups_id": "loo_..."
}]
}
Example: Recurring EFT Debit Order
{
"records": [{
"customer_id": "cus_...",
"bank_account_id": "ban_...",
"payment_methods_id": "pam_...",
"mandate_status_lookups_id": "loo_...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
"payment_industry_lookups_id": "loo_..."
}]
}
Example: One-time DebiCheck
{
"records": [{
"customer_id": "cus_...",
"bank_account_id": "ban_...",
"payment_methods_id": "pam_...",
"amount": "45.00",
"one-time": {
"process_date": "2025-06-25"
},
"payment_industry_lookups_id": "loo_...",
"debicheck": {
"contract_reference": "CTC24091900002",
"maximum_collection_amount": "60.00",
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"approval_window_lookups_id": "loo_..."
}
}]
}
Example: Recurring DebiCheck
{
"records": [{
"customer_id": "cus_...",
"bank_account_id": "ban_...",
"payment_methods_id": "pam_...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_...",
"date_release": "2026-05-12"
},
"payment_industry_lookups_id": "loo_...",
"debicheck": {
"contract_reference": "CTC24091900002",
"first_collection_amount": "50.45",
"first_collection_date": "2025-05-01",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category_lookups_id": "loo_...",
"adjustment_type_lookups_id": "loo_...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window_lookups_id": "loo_..."
}
}]
}
Response Body
{
"status": true,
"results": [{
"id": "man_abc123...",
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"customer_id": "cus_abc123...",
"bank_account_id": "ban_abc123...",
"payment_methods_id": "pam_abc123...",
"mandate_status_lookups_id": "loo_abc123...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
"one-time": {...},
"payment_industry_lookups_id": "loo_abc123...",
"debicheck": {
"contract_reference": "CTC24091900001",
"first_collection_amount": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category_lookups_id": "loo_abc123...",
"adjustment_type_lookups_id": "loo_abc123...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window_lookups_id": "loo_abc123..."
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | man_abc123... |
| updated_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When last the record was updated | 2024-02-27 09:11:23 |
| created_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When this record was created | 2024-02-27 09:11:23 |
| customer_id | Y | String(32) | Customer ID | cus_abc123... |
| bank_account_id | Y | String(32) | Bank Account ID | ban_abc123... |
| payment_methods_id | Y | String(32) | Payment Method ID | pam_abc123... |
| mandate_status_lookups_id | n/a | String(32) | Mandate status lookups ID; found by 'mandate_status' in lookups. DebiCheck payment status is always 'created' on mandate submission until feedback is received. | loo_abc123... |
| amount | Y | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | Y | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.payment_interval_lookups_id | N | String(32) | Lookups ID relating to how often this collection should be run e.g. monthly | loo_abc123... |
| recurring.date_release | N | Date(YYYY-MM-DD) | When this mandate is to release or complete | 2026-05-01 |
| one-time.process_date | N | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
| debicheck.contract_reference | C | String(14) | Required when using DebiCheck. This uniquely identifies the collection. | CTC24091900001 |
| debicheck.first_collection_amount | N | Decimal | Amount to be collected on the very first billing day for DebiCheck. This would be your instalment amount plus any fee which you may require e.g. if your payment amount is R 10.00 and you require a R 5.00 fee to be processed on the first billing run then your first collection amount would be R 15.00. | 50.45 |
| debicheck.first_collection_date | C | Date(YYYY-MM-DD) | When the first collection amount is to be collected | 2024-03-01 |
| debicheck.maximum_collection_amount | Y | Decimal | Required by DebiCheck. This is the maximum collection amount allowed for the mandate. This maximum amount may not be more than 1.5 times the payment amount e.g. if your payment amount is R 10.00 then your maximum collection amount may not be more than R15.00. | 60.00 |
| debicheck.allow_date_adjustment | N | Boolean | Used by DebiCheck to indicate that collections may be made on billing days other than the day specified on the mandate. | true |
| debicheck.allow_variable_amount | N | Boolean | Used by DebiCheck to indicate that the amount collected on the billing day may differ from the mandate payment amount as long as it is less than the maximum collection amount. Must be true when using adjustment category amount/rates. | false |
| debicheck.allow_payment_tracking | N | Boolean | Used by DebiCheck to allow resubmission of a payment should the payment fail on the collection day. The payment will be resubmitted up to a maximum amount of days, or until the payment succeeds whichever comes first. Warning: this resubmitted payment becomes disputable. | true |
| debicheck.payment_tracking_max_days | N | Integer | 1 to 10 Days. Used by payment tracking specified above to defined the maximum amount of days a resubmission is allowed after the billing day. | 4 |
| debicheck.adjustment_category_lookups_id | N | String(32) | Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. | loo_abc123... |
| adjustment_type_lookups_id | N | String(32) | Lookups ID determining the type of adjustment e.g. Rate adjustment | loo_abc123... |
| debicheck.adjustment_rate | N | Decimal | Determines the percentage to increase the DebiCheck payment amount per adjustment category interval. | 5.12345 |
| debicheck.adjustment_amount | N | Decimal | Determines the amount to increase the DebiCheck payment amount per adjustment category interval. Either adjustment rate OR adjustment amount must be used when an adjustment category is specified and both may not be specified at the same time | 0.00 |
| debicheck.approval_window_lookups_id | N | String(32) | Determines how long the user has to approve the DebiCheck mandate. | loo_abc123... |
Update EFT Debit Order
API call to update existing mandate(s) as single or batch records. Records can not be deleted, only archived.
Path
POST /mandates/eft/update
WARNINGAn EFT debit order mandate can not be archived/disabled if it has connected running payments you need to stop those payments first.
Only provide the fields you wish to change in the body.
One-time mandates can not be converted to recurring mandates and vice versa. Payment interval of recurring mandates can not be changed after creation.
Request Body
{
"records": [{
"id": "man_abc123...",
"amount": "45.00",
// for recurring mandates
"recurring": {
"process_day": 1,
"date_release": "2026-05-12"
},
// or for one-time mandates
"one-time": {
"process_date": "2024-10-25"
},
"payment_industry_lookups_id": "loo_abc123...",
"mandate_status_lookups_id": "loo_abc123..."
}]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | Y | String(32) | Record id to update | man_abc123... |
| amount | N | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | N | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.date_release | N | When this mandate is to release or complete | 2026-05-01 | |
| one-time.process_date | N | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
| debit_order.mandate_status_lookups_id | N | String(32) | Only allowed to be changed for EFT debit orders. Mandate status lookups ID; found by 'mandate_status' in lookups | loo_abc123... |
Response Body
{
"status": true,
"results": [{
"id": "man_abc123...",
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"customer_id": "cus_abc123...",
"bank_account_id": "ban_abc123...",
"payment_methods_id": "pam_abc123...",
"mandate_status_lookups_id": "loo_abc123...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
"one-time": {...},
"payment_industry_lookups_id": "loo_abc123..."
}, ...]
}
Response Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | man_abc123... |
| updated_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When last the record was updated | 2024-02-27 09:11:23 |
| created_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When this record was created | 2024-02-27 09:11:23 |
| customer_id | Y | String(32) | Customer ID | cus_abc123... |
| bank_account_id | Y | String(32) | Bank Account ID | ban_abc123... |
| payment_methods_id | Y | String(32) | Payment Method ID | pam_abc123... |
| mandate_status_lookups_id | n/a | String(32) | Mandate status lookups ID; found by 'mandate_status' in lookups | loo_abc123... |
| amount | Y | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | Y | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.payment_interval_lookups_id | N | String(32) | Lookups ID relating to how often this collection should be run e.g. monthly | loo_abc123... |
| recurring.date_release | N | Date(YYYY-MM-DD) | When this mandate is to release or complete | 2026-05-01 |
| one-time.process_date | N | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
Update DebiCheck
API call to update existing mandate(s) as single or batch records. Records can not be deleted, only archived.
Re-submit
POST /mandates/debicheck/update/resubmit
TT1 (approval_window) DebiCheck mandates only. Resubmit the created mandate that is of 'no reply' status.
{
"records": [{
"id": "man_abc123..."
}]
}
Cancel
POST /mandates/debicheck/update/cancel
Cancel/stop the DebiCheck mandate.
WARNINGThe cancel reason will show immediately on the record but the status will not be updated until a response is received from the bank.
{
"records": [{
"id": "man_abc123...",
"cancel_reason_lookups_id": "loo_abc..."
}]
}
Update
POST /mandates/debicheck/update/request
Update the details of an existing mandate
WARNINGWhen updating DebiCheck mandates depending on the field that you want to update you either perform an update or re-auth.
Only provide the fields you wish to change. Additionally only a select number of fields may be updated for DebiCheck, this is according to the bank rules.
One-time mandates can not be converted to recurring mandates and vice versa. Payment interval of recurring mandates can not be changed after creation.
Example: Recurring
{
"records": [{
"id": "man_abc123...",
// Required when action is UPDATE
"update_reason_lookups_id": "loo_abc...",
// pull in the latest customer name, id, contact number & email
"update_customer": true,
// pull in the latest bank account number and type
// NOTE: bank branch is not allowed to change
"update_bank_account": true,
// This is the re-authentication instrument used,
// must be TT2 if original submission was TT2
"approval_window_lookups_id": "loo_abc123...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"date_release": "2026-05-12"
},
"payment_industry_lookups_id": "loo_abc123...",
"allow_date_adjustment": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"first_collection_amount": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"adjustment_category_lookups_id": "loo_abc123...",
"adjustment_type_lookups_id": "loo_abc123...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00"
}]
}
Example: One-time
{
"records": [{
"id": "man_abc123...",
// Required when action is UPDATE
"update_reason_lookups_id": "loo_abc...",
// pull in the latest customer name, id, contact number & email
"update_customer": true,
// pull in the latest bank account number and type
// NOTE: bank branch is not allowed to change
"update_bank_account": true,
// This is the re-authentication instrument used,
// must be TT2 if original submission was TT2
"approval_window_lookups_id": "loo_abc123...",
"amount": "45.00",
"one-time": {
"process_date": "2024-10-25"
},
"payment_industry_lookups_id": "loo_abc123...",
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"maximum_collection_amount": "60.00"
}]
}
Request Parameters
Field | Required | DebiCheck Action | Type | Description | Example |
|---|---|---|---|---|---|
| id | Y | n/a | String(32) | Record id to update | man_abc123... |
| cancel_reason_lookups_id | N | n/a | String(32) | Lookups ID relating to the reason for the cancellation. | loo_abc123... |
| update_reason_lookups_id | Y | n/a | String(32) | Lookups ID relating to the reason for the update. | loo_abc123... |
| amount | N | re-auth | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | N | re-auth | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.date_release | N | update | When this mandate is to release or complete | 2026-05-01 | |
| one-time.process_date | N | re-auth | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | update | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
| approval_window_lookups_id | Y | n/a | String(32) | If original mandate creation was TT2 then this must also be TT2 otherwise any of the TT1 options may be selected. Determines how long the user has to approve the DebiCheck mandate update. Only used if a field is contained that requires re-auth. | loo_abc123... |
| update_customer | N | update | Boolean | Updates the DebiCheck details with the currently linked customer name, surname, ID number, contact number and email details | true |
| update_bank_account | N | re-auth | Boolean | Updates the DebiCheck details with the currently linked bank account number and bank account type. The bank branch can not be changed, mandates can not be moved between banks. | true |
| allow_date_adjustment | N | update | Boolean | Used by DebiCheck to indicate that collections may be made on billing days other than the day specified on the mandate. | true |
| allow_payment_tracking | N | update | Boolean | Used by DebiCheck to allow resubmission of a payment should the payment fail on the collection day. The payment will be resubmitted up to a maximum amount of days, or until the payment succeeds whichever comes first. Warning: this resubmitted payment becomes disputable. | true |
| payment_tracking_max_days | N | update | Integer | 1 to 10 Days. Used by payment tracking specified above to defined the maximum amount of days a resubmission is allowed after the billing day. | 4 |
| first_collection_amount | N | update | Decimal | Amount to be collected on the very first billing day for DebiCheck. This would be your instalment amount plus any fee which you may require e.g. if your payment amount is R 10.00 and you require a R 5.00 fee to be processed on the first billing run then your first collection amount would be R 15.00. | 50.45 |
| first_collection_date | N | re-auth | Date(YYYY-MM-DD) | When the first collection amount is to be collected | 2024-03-01 |
| maximum_collection_amount | N | re-auth | Decimal | Required by DebiCheck. This is the maximum collection amount allowed for the mandate. This maximum amount may not be more than 1.5 times the payment amount e.g. if your payment amount is R 10.00 then your maximum collection amount may not be more than R15.00. | 60.00 |
| adjustment_category_lookups_id | N | update | String(32) | Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. | loo_abc123... |
| adjustment_type_lookups_id | N | update | String(32) | Lookups ID determining the type of adjustment e.g. Rate adjustment | loo_abc123... |
| adjustment_rate | N | re-auth | Decimal | Determines the percentage to increase the DebiCheck payment amount per adjustment category interval. | 5.12345 |
| adjustment_amount | N | re-auth | Decimal | Determines the amount to increase the DebiCheck payment amount per adjustment category interval. Either adjustment rate OR adjustment amount must be used when an adjustment category is specified and both may not be specified at the same time | 0.00 |
Response Body
{
"status": true,
"results": [{
"id": "man_abc123...",
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"customer_id": "cus_abc123...",
"bank_account_id": "ban_abc123...",
"payment_methods_id": "pam_abc123...",
"mandate_status_lookups_id": "loo_abc123...",
"bank_request_status_lookups_id": "loo_abc123...",
"cancel_reason_lookups_id": "loo_abc123...",
"update_reason_lookups_id": "loo_abc123...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
"one-time": {...},
"payment_industry_lookups_id": "loo_abc123...",
"debicheck": {
"contract_reference": "CTC24091900001",
"first_collection_amount": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category_lookups_id": "loo_abc123...",
"adjustment_type_lookups_id": "loo_abc123...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window_lookups_id": "loo_abc123..."
}
}, ...]
}
Response Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | man_abc123... |
| updated_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When last the record was updated | 2024-02-27 09:11:23 |
| created_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When this record was created | 2024-02-27 09:11:23 |
| customer_id | Y | String(32) | Customer ID | cus_abc123... |
| bank_account_id | Y | String(32) | Bank Account ID | ban_abc123... |
| payment_methods_id | Y | String(32) | Payment Method ID | pam_abc123... |
| mandate_status_lookups_id | n/a | String(32) | Mandate status lookups ID; found by 'mandate_status' in lookups | loo_abc123... |
| bank_request_status_lookups_id | n/a | String(32) | Bank request status lookups ID applicable to DebiCheck update and cancellation requests. | loo_abc123... |
| cancel_reason_lookups_id | n/a | String(32) | Mandate cancel reason lookups ID; found by 'cancel_reason' in lookups | loo_abc123... |
| update_reason_lookups_id | n/a | String(32) | Mandate update reason lookups ID; found by 'update_reason' in lookups | loo_abc123... |
| amount | Y | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | Y | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.payment_interval_lookups_id | N | String(32) | Lookups ID relating to how often this collection should be run e.g. monthly | loo_abc123... |
| recurring.date_release | N | Date(YYYY-MM-DD) | When this mandate is to release or complete | 2026-05-01 |
| one-time.process_date | N | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
| debicheck.contract_reference | C | String(14) | Required when using DebiCheck. This uniquely identifies the collection. | CTC24091900001 |
| debicheck.first_collection_amount | N | Decimal | Amount to be collected on the very first billing day for DebiCheck. This would be your instalment amount plus any fee which you may require e.g. if your payment amount is R 10.00 and you require a R 5.00 fee to be processed on the first billing run then your first collection amount would be R 15.00. | 50.45 |
| debicheck.first_collection_date | C | Date(YYYY-MM-DD) | When the first collection amount is to be collected | 2024-03-01 |
| debicheck.maximum_collection_amount | Y | Decimal | Required by DebiCheck. This is the maximum collection amount allowed for the mandate. This maximum amount may not be more than 1.5 times the payment amount e.g. if your payment amount is R 10.00 then your maximum collection amount may not be more than R15.00. | 60.00 |
| debicheck.allow_date_adjustment | N | Boolean | Used by DebiCheck to indicate that collections may be made on billing days other than the day specified on the mandate. | true |
| debicheck.allow_variable_amount | N | Boolean | Used by DebiCheck to indicate that the amount collected on the billing day may differ from the mandate payment amount as long as it is less than the maximum collection amount. Must be true when using adjustment category amount/rates. | false |
| debicheck.allow_payment_tracking | N | Boolean | Used by DebiCheck to allow resubmission of a payment should the payment fail on the collection day. The payment will be resubmitted up to a maximum amount of days, or until the payment succeeds whichever comes first. Warning: this resubmitted payment becomes disputable. | true |
| debicheck.payment_tracking_max_days | N | Integer | 1 to 10 Days. Used by payment tracking specified above to defined the maximum amount of days a resubmission is allowed after the billing day. | 4 |
| debicheck.adjustment_category_lookups_id | N | String(32) | Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. | loo_abc123... |
| adjustment_type_lookups_id | N | String(32) | Lookups ID determining the type of adjustment e.g. Rate adjustment | loo_abc123... |
| debicheck.adjustment_rate | N | Decimal | Determines the percentage to increase the DebiCheck payment amount per adjustment category interval. | 5.12345 |
| debicheck.adjustment_amount | N | Decimal | Determines the amount to increase the DebiCheck payment amount per adjustment category interval. Either adjustment rate OR adjustment amount must be used when an adjustment category is specified and both may not be specified at the same time | 0.00 |
| debicheck.approval_window_lookups_id | N | String(32) | Determines how long the user has to approve the DebiCheck mandate. | loo_abc123... |
List
List mandates loaded on the platform.
Path
GET /mandates/list?{params}
Query Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| mandate_status_lookups_id | String(32) | N | Filter for a specific bank account status. Lookups type must be 'mandate_status'. | loo_abc123... |
| customer_id | String(32) | N | Filter for a specific customer id. | cus_abc123... |
| bank_account_id | String(32) | N | Filter for a specific bank account id. | ban_abc123... |
| payment_methods_id | String(32) | N | Filter for a specific payment method id. | pam_abc123... |
| 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 |
Response Body
{
"status": true,
"results": [{
"id": "man_abc123...",
"updated_at": null,
"created_at": "2024-02-27 09:11:23",
"customer_id": "cus_abc123...",
"bank_account_id": "ban_abc123...",
"payment_methods_id": "pam_abc123...",
"mandate_status_lookups_id": "loo_abc123...",
"bank_request_status_lookups_id": "loo_abc123...",
"cancel_reason_lookups_id": "loo_abc123...",
"update_reason_lookups_id": "loo_abc123...",
"amount": "45.00",
"recurring": {
"process_day": 1,
"payment_interval_lookups_id": "loo_abc123...",
"date_release": "2026-05-12"
},
"one-time": {...},
"payment_industry_lookups_id": "loo_abc123...",
"debicheck": {
"contract_reference": "CTC24091900001",
"first_collection_amount": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category_lookups_id": "loo_abc123...",
"adjustment_type_lookups_id": "loo_abc123...",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window_lookups_id": "loo_abc123..."
}
}, ...]
}
Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| id | n/a | String(32) | Record id returned | man_abc123... |
| updated_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When last the record was updated | 2024-02-27 09:11:23 |
| created_at | n/a | Date(YYYY-MM-DD HH:mm:ss) | When this record was created | 2024-02-27 09:11:23 |
| customer_id | Y | String(32) | Customer ID | cus_abc123... |
| bank_account_id | Y | String(32) | Bank Account ID | ban_abc123... |
| payment_methods_id | Y | String(32) | Payment Method ID | pam_abc123... |
| mandate_status_lookups_id | n/a | String(32) | Mandate status lookups ID; found by 'mandate_status' in lookups | loo_abc123... |
| bank_request_status_lookups_id | n/a | String(32) | Bank request status lookups ID applicable to DebiCheck update and cancellation requests. | loo_abc123... |
| cancel_reason_lookups_id | n/a | String(32) | Mandate cancel reason lookups ID; found by 'cancel_reason' in lookups | loo_abc123... |
| update_reason_lookups_id | n/a | String(32) | Mandate update reason lookups ID; found by 'update_reason' in lookups | loo_abc123... |
| amount | Y | Decimal | The amount to be collected on the billing day | 45.00 |
| recurring.process_day | Y | Integer | Calendar day on which the collection is to be made. If you choose 31st and the month only has 30 days the collection will be made on the 30th. | 1 |
| recurring.payment_interval_lookups_id | N | String(32) | Lookups ID relating to how often this collection should be run e.g. monthly | loo_abc123... |
| recurring.date_release | N | Date(YYYY-MM-DD) | When this mandate is to release or complete | 2026-05-01 |
| one-time.process_date | N | Date(YYYY-MM-DD) | Date upon which transaction will be processed once | 2024-09-30 |
| payment_industry_lookups_id | N | String(32) | Lookups ID relating to what type of payment this is for e.g. insurance premium. Used by both EFT debit orders and DebiCheck. | loo_abc123... |
| debicheck.contract_reference | C | String(14) | Required when using DebiCheck. This uniquely identifies the collection. | CTC24091900001 |
| debicheck.first_collection_amount | N | Decimal | Amount to be collected on the very first billing day for DebiCheck. This would be your instalment amount plus any fee which you may require e.g. if your payment amount is R 10.00 and you require a R 5.00 fee to be processed on the first billing run then your first collection amount would be R 15.00. | 50.45 |
| debicheck.first_collection_date | C | Date(YYYY-MM-DD) | When the first collection amount is to be collected | 2024-03-01 |
| debicheck.maximum_collection_amount | Y | Decimal | Required by DebiCheck. This is the maximum collection amount allowed for the mandate. This maximum amount may not be more than 1.5 times the payment amount e.g. if your payment amount is R 10.00 then your maximum collection amount may not be more than R15.00. | 60.00 |
| debicheck.allow_date_adjustment | N | Boolean | Used by DebiCheck to indicate that collections may be made on billing days other than the day specified on the mandate. | true |
| debicheck.allow_variable_amount | N | Boolean | Used by DebiCheck to indicate that the amount collected on the billing day may differ from the mandate payment amount as long as it is less than the maximum collection amount. Must be true when using adjustment category amount/rates. | false |
| debicheck.allow_payment_tracking | N | Boolean | Used by DebiCheck to allow resubmission of a payment should the payment fail on the collection day. The payment will be resubmitted up to a maximum amount of days, or until the payment succeeds whichever comes first. Warning: this resubmitted payment becomes disputable. | true |
| debicheck.payment_tracking_max_days | N | Integer | 1 to 10 Days. Used by payment tracking specified above to defined the maximum amount of days a resubmission is allowed after the billing day. | 4 |
| debicheck.adjustment_category_lookups_id | N | String(32) | Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. | loo_abc123... |
| adjustment_type_lookups_id | N | String(32) | Lookups ID determining the type of adjustment e.g. Rate adjustment | loo_abc123... |
| debicheck.adjustment_rate | N | Decimal | Determines the percentage to increase the DebiCheck payment amount per adjustment category interval. | 5.12345 |
| debicheck.adjustment_amount | N | Decimal | Determines the amount to increase the DebiCheck payment amount per adjustment category interval. Either adjustment rate OR adjustment amount must be used when an adjustment category is specified and both may not be specified at the same time | 0.00 |
| debicheck.approval_window_lookups_id | N | String(32) | Determines how long the user has to approve the DebiCheck mandate. | loo_abc123... |