Mandates - Kwik Docs

Used to create (DebiCheck / Registered Mandate: authenticate), edit (DebiCheck / Registered Mandate: 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.

WARNING
Customers that are using the Company Registration Number ID type can only be assigned with Registered Mandate (RM) payment methods where the provider bank is ABSA or EFT DO payment methods.
DebiCheck customers have to approve the mandates themselves whereas Registered Mandates only need to be approved by the bank.
Company business bank accounts can not be processed via DebiCheck payment methods. EFT Debit Order or Registered Mandate (RM payment methods with provider bank as ABSA) payment methods must be used for business bank accounts.

Create

API call to create (DebiCheck / Registered Mandate: authenticate) new mandates(s) as single or batch records.

DebiCheck customers will have to approve the mandate from their phone. Registered Mandates customers will be authenticated with the bank and do not need any approval, likewise EFT customers do not need any approval either.

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 / Registered Mandates
    "mandate_status": "ACTIVE",
    "reference": "ABC123",
    "amount": "45.00",
    // required for recurring payments
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    // used with one-time payments
    "one-time": {
      "process_date": "2024-10-25"
    },
    // required if Payment method is DebiCheck, Registered mandates or EFT Debit Order
    "payment_industry": "ACCOUNT_REPAYMENT",
    // required if Payment Method is DebiCheck / Registered Mandates
    "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": "ANNUALLY",
      "adjustment_type": "RATE",
      "adjustment_rate": "5.12345",
      "adjustment_amount": "0.00",
      // not applicable to registered mandates
      "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2",
      // Used with DebiCheck TT3
      "mandate_authentication_code": "12345678"
    },
    "debitorder": {
      // Optional but recommended field for EFT Debit Order payment Methods
      "contract_reference": "CTC24091900002"
    }
  }]
}

Example: One-time EFT Debit Order

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "mandate_status": "ACTIVE",
    "amount": "45.00",
    "one-time": {
      "process_date": "2025-06-25"
    },
    "payment_industry": "ACCOUNT_REPAYMENT"
  }]
}

Example: Recurring EFT Debit Order

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "mandate_status": "ACTIVE",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    "payment_industry": "ACCOUNT_REPAYMENT"
  }]
}

Example: One-time DebiCheck

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "amount": "45.00",
    "one-time": {
      "process_date": "2025-06-25"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "debicheck": {
      "contract_reference": "CTC24091900002",
      "maximum_collection_amount": "60.00",
      "allow_payment_tracking": true,
      "payment_tracking_max_days": 4,
      "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
    }
  }]
}

Example: Recurring DebiCheck

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "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": "ANNUALLY",
      "adjustment_type": "RATE",
      "adjustment_rate": "5.12345",
      "adjustment_amount": "0.00",
      "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
    }
  }]
}

Example: Recurring DebiCheck TT3

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "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": "ANNUALLY",
      "adjustment_type": "RATE",
      "adjustment_rate": "5.12345",
      "adjustment_amount": "0.00",
      "approval_window": "MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN",
      "mandate_authentication_code": "12345678"
    }
  }]
}

Example: One-time Registered Mandate

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "amount": "45.00",
    "one-time": {
      "process_date": "2025-06-25"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "debicheck": {
      "contract_reference": "CTC24091900002",
      "maximum_collection_amount": "60.00",
      "allow_payment_tracking": true,
      "payment_tracking_max_days": 4
    }
  }]
}

Example: Recurring Registered Mandate

{
  "records": [{
    "customer_id": "cus_abc123...",
    "bank_account_id": "ban_abc123...",
    "payment_methods_id": "pam_abc123...",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "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": "ANNUALLY",
      "adjustment_type": "RATE",
      "adjustment_rate": "5.12345",
      "adjustment_amount": "0.00"
    }
  }]
}

Response Body

{
    "status": true,
    "results": [{
        "id": "man_abc123...",
        "reference": "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": "ACTIVE",
        "amount": "45.00",
        "recurring": {
          "process_day": 1,
          "payment_interval": "MONTHLY",
          "date_release": "2026-05-12"
        },
        "one-time": {...},
        "payment_industry": "ACCOUNT_REPAYMENT",
        "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": "ANNUALLY",
          "adjustment_type": "RATE",
          "adjustment_rate": "5.12345",
          "adjustment_amount": "0.00",
          "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
        },
        "debitorder": {
          "contract_reference": "CTC24091900002"
        }
    }, ...]
}

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	n/a	ENUM	DebiCheck payment status is always 'created' on mandate submission until feedback is received. (`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`)	ACTIVE
reference	N	String(256)	Optional customer reference number	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	N	ENUM	How often this collection should be run. (`MONTHLY`,`YEARLY`).	MONTHLY
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	N	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`)	ACCOUNT_REPAYMENT
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 first collection date. Make sure to have a running payment connected to the mandate to receive this first collection amount.	50.45
debicheck.first_collection_date	C	Date(YYYY-MM-DD)	When the first collection amount is to be collected. If this date is the same as the payment starting date then 2 collections will be attempted on the same day. This first collection date is independent from the payment first collection.	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. Used with re-presented (arrears) collections.	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	N	ENUM	Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. (`ANNUALLY`,`BIANNUALLY`,`NEVER`,`QUARTERLY`)	ANNUALLY
adjustment_type	N	ENUM	Amount or rate as a percentage. (`AMOUNT`,`RATE`)	RATE
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	N	ENUM	Determines how long the user has to approve the DebiCheck mandate. Does NOT apply to Registered Mandates (RM). (`BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2`,`DELAYED_REAL_TIME_TT1_APPROVE_BY_20H00_ON_THE_SAME_DAY`,`MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_CELLPHONE_MUST_MATCH_BANK`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_SENT_TO_BANK_CELLPHONE`).	BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2
*.mandate.debicheck.mandate_authentication_code	N	String(8)	TT3 mandates only, this is a Message Authentication Code (MAC) used for Card Present (CP) or Card Not Present (CNP) authentication for mandate initiation using card and PIN (TT3).	12345678
debitorder.contract_reference	N	String(14)	Recommended. Leave blank to generate automatically. This uniquely identifies the debit order payment and will show in the bank statements.	CTC24091900002

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

WARNING
An 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",
    "reference": "ABC123",
    // 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": "ACCOUNT_REPAYMENT",
    "mandate_status": "ACTIVE"
  }]
}

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
reference	N	String(256)	Optional custom reference number	ABC123
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	N	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`).	ACCOUNT_REPAYMENT
debit_order.mandate_status	N	ENUM	Only allowed to be changed for EFT debit orders. (`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`).	ACTIVE

Response Body

{
    "status": true,
    "results": [{
        "id": "man_abc123...",
        "updated_at": null,
        "reference": "ABC123",
        "created_at": "2024-02-27 09:11:23",
        "customer_id": "cus_abc123...",
        "bank_account_id": "ban_abc123...",
        "payment_methods_id": "pam_abc123...",
        "mandate_status": "ACTIVE",
        "amount": "45.00",
        "recurring": {
          "process_day": 1,
          "payment_interval": "MONTHLY",
          "date_release": "2026-05-12"
        },
        "one-time": {...},
        "payment_industry": "ACCOUNT_REPAYMENT"
    }, ...]
}

Response Parameters

Field	Required	Type	Description	Example
id	n/a	String(32)	Record id returned	man_abc123...
reference	N	String(256)	Optional customer reference number	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	n/a	ENUM	(`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`)	ACTIVE
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	N	ENUM	How often this collection should be run. (`MONTHLY`,`YEARLY`).	MONTHLY
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	N	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`).	ACCOUNT_REPAYMENT

Update DebiCheck / Registered Mandates

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

Activate

Activate the DebiCheck mandate after being archived. This will ultimately restore the mandate status the current status the bank reflects. Archiving is not a DebiCheck feature, it is a soft status available for convenience.

Path

POST /mandates/debicheck/update/activate

Body

{
  "records": [{
    "id": "man_abc123..."
  }]
}

Re-submit

WARNING
TT1 (approval_window) DebiCheck mandates only.

Only applicable to DebiCheck mandates created by a payment method with the provider bank set to ABSA. Resubmit the created mandate that has returned the 'no reply' status within the last 5 calendar days. You are limited to 4 re-submissions after that you have to create a new mandate.

Path

POST /mandates/debicheck/update/resubmit

Body

{
  "records": [{
    "id": "man_abc123..."
  }]
}

Cancel

Cancel/stop the DebiCheck mandate / Registered Mandate.

DebiCheck Path

POST /mandates/debicheck/update/cancel

Registered Mandate Path

POST /mandates/rm/update/cancel

WARNING
The cancel reason will show immediately on the record but the status will not be updated until a response is received from the bank.

Body

{
  "records": [{
    "id": "man_abc123...",
    "cancel_reason": "CONTRACT_EXPIRED"
  }]
}

WARNING
One-time DebiCheck mandates / Registered Mandates can not be changed and you will have to cancel the mandate and create a new mandate if you wish to change it.
The payment interval of recurring mandates can not be changed after creation so make sure it is correct on creation.
When updating DebiCheck mandates depending on the fields that you want to update you either perform an update or a re-auth. An update will send the customer a notification whereas a re-auth has to be approved by the customer before the new changes can come into effect. The 'action' column below to indicate an update or re-auth is only a guideline based on ABSA TT2 DebiCheck provided mandates. The requirements of update / re-auth differs between DebiCheck mandates provided by ABSA and those provided by Nedbank and there is also a difference between the requirements for a TT1 and a TT2 mandate; therefore only provide the fields you wish to change.
Make sure to update your connected payments accordingly AFTER the DebiCheck mandate amendment has been approved. In most cases it is best to pause the old payment and create a new payment.
Avoid changing mandates when a collection is pending at the bank otherwise you could violate the mandate rules and result in the collection being rejected on the day of payment.

DebiCheck Example: Recurring

{
  "records": [{
    "id": "man_abc123...",
    "reference": "ABC123",
    
    // Required when action is UPDATE
    "update_reason": "REQUESTED_BY_CUSTOMER",

    // 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": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2",
    // Used with DebiCheck TT3
    "mandate_authentication_code": "12345678",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "date_release": "2026-05-12"
    },
    "payment_industry": "ACCOUNT_REPAYMENT",
    "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": "ANNUALLY",
    "adjustment_type": "RATE",
    "adjustment_rate": "5.12345",
    "adjustment_amount": "0.00"
  }]
}

Request Parameters

Field	Required	DebiCheck Action	Type	Description	Example
id	Y	n/a	String(32)	Record id to update	man_abc123...
reference	N	String(256)	Optional custom reference number	ABC123
cancel_reason	N	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_THE_CREDITOR`,`CONTRACT_EXPIRED`,`MANDATE_CANCELLATION_DUE_TO_FRAUD`,`MANDATE_CANCELLED_DUE_TO_EARLY_SETTLEMENT`)	CONTRACT_EXPIRED
update_reason	Y	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_INITIATING_PARTY`,`REQUESTED_BY_CUSTOMER`)	REQUESTED_BY_CUSTOMER
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	N	update	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`).	ACCOUNT_REPAYMENT
approval_window	Y	n/a	ENUM	If mandate init was TT1 then the amend window must also be TT1 (same applies for TT2 and TT3). Determines how long the user has to approve the DebiCheck mandate update. Only used if a field is contained that requires re-auth. Does NOT apply to Registered Mandates. (`BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2`,`DELAYED_REAL_TIME_TT1_APPROVE_BY_20H00_ON_THE_SAME_DAY`,`MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_CELLPHONE_MUST_MATCH_BANK`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_SENT_TO_BANK_CELLPHONE`).	BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2
mandate_authentication_code	C - Required with TT3	n/a	String(8)	Mandate authentication code used with TT3 solutions (Card and PIN).	12345678
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 first collection date. Make sure to have a running payment connected to the mandate to receive this first collection amount.	50.45
first_collection_date	N	re-auth	Date(YYYY-MM-DD)	When the first collection amount is to be collected. If this date is the same as the payment starting date then 2 collections will be attempted on the same day. This first collection date is independent from the payment first collection.	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. . Used with re-presented (arrears) collections.	60.00
adjustment_category	N	update	ENUM	Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. (`ANNUALLY`,`BIANNUALLY`,`NEVER`,`QUARTERLY`).	ANNUALLY
adjustment_type	N	update	ENUM	Amount or rate as a percentage. (`AMOUNT`,`RATE`)	RATE
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...",
        "reference": "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": "ACTIVE",
        "bank_request_status": "UPDATE_PENDING",
        "cancel_reason": "CONTRACT_EXPIRED",
        "update_reason": "REQUESTED_BY_CUSTOMER",
        "amount": "45.00",
        "recurring": {
          "process_day": 1,
          "payment_interval": "MONTHLY",
          "date_release": "2026-05-12"
        },
        "one-time": {...},
        "payment_industry": "ACCOUNT_REPAYMENT",
        "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": "ANNUALLY",
          "adjustment_type": "RATE",
          "adjustment_rate": "5.12345",
          "adjustment_amount": "0.00",
          "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
        }
    }, ...]
}

Response Parameters

Field	Required	Type	Description	Example
id	n/a	String(32)	Record id returned	man_abc123...
reference	N	String(256)	Optional custom reference number	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	n/a	ENUM	(`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`)	ACTIVE
bank_request_status	n/a	ENUM	Applicable to DebiCheck update and cancellation requests. (`CANCELLATION_ACCEPTED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`UPDATE_ACCEPTED`,`UPDATE_PENDING`,`UPDATE_REJECTED`).	UPDATE_PENDING
cancel_reason	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_THE_CREDITOR`,`CONTRACT_EXPIRED`,`MANDATE_CANCELLATION_DUE_TO_FRAUD`,`MANDATE_CANCELLED_DUE_TO_EARLY_SETTLEMENT`)	CONTRACT_EXPIRED
update_reason	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_INITIATING_PARTY`,`REQUESTED_BY_CUSTOMER`)	REQUESTED_BY_CUSTOMER
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	N	ENUM	How often this collection should be run. (`MONTHLY`,`YEARLY`).	MONTHLY
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	N	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`).	ACCOUNT_REPAYMENT
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 first collection date. Make sure to have a running payment connected to the mandate to receive this first collection amount.	50.45
debicheck.first_collection_date	C	Date(YYYY-MM-DD)	When the first collection amount is to be collected. If this date is the same as the payment starting date then 2 collections will be attempted on the same day. This first collection date is independent from the payment first collection.	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. Used with re-presented (arrears) collections.	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	N	ENUM	Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. (`ANNUALLY`,`BIANNUALLY`,`NEVER`,`QUARTERLY`).	ANNUALLY
adjustment_type	N	ENUM	Amount or rate as a percentage. (`AMOUNT`,`RATE`)	RATE
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	N	ENUM	Determines how long the user has to approve the DebiCheck mandate. Does NOT apply to Registered Mandates. (`BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2`,`DELAYED_REAL_TIME_TT1_APPROVE_BY_20H00_ON_THE_SAME_DAY`,`MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_CELLPHONE_MUST_MATCH_BANK`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_SENT_TO_BANK_CELLPHONE`).	BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2

Field	Type	Required	Description	Example
mandate_status	ENUM	N	Filter for a specific mandate status. (`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`).	ACTIVE
approval_window	ENUM	N	Filter for a specific approval window. Lookups type must be 'approval_window'. Does NOT apply to Registered Mandates. (`BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2`,`DELAYED_REAL_TIME_TT1_APPROVE_BY_20H00_ON_THE_SAME_DAY`,`MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_CELLPHONE_MUST_MATCH_BANK`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_SENT_TO_BANK_CELLPHONE`).	BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2
customer_id	String(32)	N	Filter for a specific customer id.	cus_abc123...
mandate_id	String(32)	N	Filter for a specific mandate id.	man_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...",
    "reference": "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": "ACTIVE",
    "message": "",
    "bank_request_status": "UPDATE_PENDING",
    "cancel_reason": "CONTRACT_EXPIRED",
    "update_reason": "REQUESTED_BY_CUSTOMER",
    "amount": "45.00",
    "recurring": {
      "process_day": 1,
      "payment_interval": "MONTHLY",
      "date_release": "2026-05-12"
    },
    "one-time": {...},
    "payment_industry": "ACCOUNT_REPAYMENT",
    "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": "ANNUALLY",
      "adjustment_type": "RATE",
      "adjustment_rate": "5.12345",
      "adjustment_amount": "0.00",
      "approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
    },
    "debitorder": {
      "contract_reference": "CTC24091900002",
      "documents_history": [{
        "created_at": "2025-10-07T06:44:57.697Z",
        "document_url": "https://staging.app.kwik.co.za/1.0/mandates/download?key=mandates/acc_N0Rys3kQcYMLgS52XPMRa/mandate_MANHOD2510070844572665.pdf"
      }, ...]
    }
  }, ...]
}

Parameters

Field	Required	Type	Description	Example
id	n/a	String(32)	Record id returned	man_abc123...
reference	N	String(256)	Optional custom reference number	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	n/a	ENUM	(`ACTIVE`,`ARCHIVED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`DISABLED`,`GENERATED`,`NO_REPLY`,`PENDING`,`REJECTED`,`SUSPENDED`)	ACTIVE
message	n/a	String	Message related to the mandate status if applicable	some rejection reason
bank_request_status	n/a	ENUM	Applicable to DebiCheck update and cancellation requests. (`CANCELLATION_ACCEPTED`,`CANCELLATION_PENDING`,`CANCELLATION_REJECTED`,`CANCELLATION_SUCCESSFUL`,`UPDATE_ACCEPTED`,`UPDATE_PENDING`,`UPDATE_REJECTED`).	UPDATE_PENDING
cancel_reason	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_THE_CREDITOR`,`CONTRACT_EXPIRED`,`MANDATE_CANCELLATION_DUE_TO_FRAUD`,`MANDATE_CANCELLED_DUE_TO_EARLY_SETTLEMENT`)	CONTRACT_EXPIRED
update_reason	n/a	ENUM	(`CANCELLATION_OR_AMENDMENT_REQUESTED_BY_INITIATING_PARTY`,`REQUESTED_BY_CUSTOMER`)	REQUESTED_BY_CUSTOMER
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	N	ENUM	How often this collection should be run. (`MONTHLY`,`YEARLY`).	MONTHLY
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	N	ENUM	Used by both EFT debit orders and DebiCheck. (`ACCOUNT_REPAYMENT`,`BOND_REPAYMENT`,`CHARITABLE_OR_RELIGIOUS_CONTRIBUTIONS`,`H_P__REPAYMENT`,`INSURANCE_PREMIUM`,`LOAN_REPAYMENT_OTHER_THAN_MORTGAGE`,`MEDICAL_AID_FUND_CONTRIBUTION`,`PENSION_FUND_CONTRIBUTION`,`RENT_PROPERTY`,`RENTALLEASE_OTHER_THAN_PROPERTY`,`SERVICE_CHARGE_MAINTENANCE`,`SERVICE_CHARGE_VARIABLE_AMOUNTS`,`UNIT_TRUST_PURCHASE`).	ACCOUNT_REPAYMENT
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 first collection date. Make sure to have a running payment connected to the mandate to receive this first collection amount.	50.45
debicheck.first_collection_date	C	Date(YYYY-MM-DD)	When the first collection amount is to be collected. If this date is the same as the payment starting date then 2 collections will be attempted on the same day. This first collection date is independent from the payment first collection.	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. Used with re-presented (arrears) collections.	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	N	ENUM	Used by DebiCheck to adjust the mandate payment amount per specified interval e.g. increase payment amount by R 10.00 every year. (`ANNUALLY`,`BIANNUALLY`,`NEVER`,`QUARTERLY`).	ANNUALLY
adjustment_type	N	ENUM	Amount or rate as a percentage. (`AMOUNT`,`RATE`)	RATE
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	N	ENUM	Determines how long the user has to approve the DebiCheck mandate. Does NOT apply to Registered Mandates. (`BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2`,`DELAYED_REAL_TIME_TT1_APPROVE_BY_20H00_ON_THE_SAME_DAY`,`MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_CELLPHONE_MUST_MATCH_BANK`,`REAL_TIME_TT1_APPROVE_WITHIN_120_SECONDS_SENT_TO_BANK_CELLPHONE`).	BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2
debitorder.contract_reference	N	String(14)	This uniquely identifies the debit order payment and will show in the bank statements.	CTC24091900002
debitorder.documents_history	N	Object	List of mandate PDF documents created
debitorder.documents_history.created_at	N	Date(ISO)	ISO timestamp when the document was created	2025-10-07T06:44:57.697Z
debitorder.documents_history.document_url	N	String	Private URL link to download the document. Make a GET request to this URL with authorization headers included (to test you can use POSTMAN for example).	https://staging.app.kwik.co.za/1.0/mandates/download?key=mandates/acc_N0Rys3kQcYMLgS52XPMRa/mandate_MANHOD2510070844572665.pdf

Cards

Retrieve a list of cards stored in the PCI DSS Level 1 vault

Orders

Manage order records including product details, pricing, discounts, taxes, and line items. Create, update, retrieve, and delete orders for payment processing and checkout sessions.