Money In
Collections
Process one-time and recurring collections across multiple methods including EFT Debit Orders, DebiCheck and Registered Mandates. Handle collection creation, status tracking, refunds, and webhook notifications.
Used with EFT Debit Order, DebiCheck and Registered Mandates payment methods to create one-time or recurring collections.
Submit
Submit a new collection request for processing.
WARNING
When submitting DebiCheck / Registered Mandate collections with a new mandate you need to retrieve the mandate after submission and ensure that the client has accepted the mandate before any collections will run.
DebiCheck customers have to approve the mandates themselves whereas Registered Mandates only need to be approved by the bank. EFT Debit Order mandates do not require approval.
You can re-submit failed DebiCheck mandates when using the TT1 approval window (for DebiCheck payment methods with the provider bank set to ABSA); otherwise you will have to create a new mandate with a new contract reference.
Company business bank accounts can not be processed via DebiCheck payment methods. EFT Debit Order or Registered Mandate payment methods (RM payment methods provided by ABSA) must be used for business accounts. Nedbank provided RM payment methods do not support company business accounts yet.
Take note of payment method date adjustment rules before selecting first collection or starting dates, for example with DebiCheck / Registered Mandates you can not set both your first collection date and collection starting date to Sunday if the payment method has rule COLLECT_ON_PREVIOUS_BUSINESS_DAY, as the payment method automatically shifts your collection date to Friday for this rule. If the rule is set to COLLECT_ON_COLLECTION_DAY you do not need to worry about this clause. See payment methods.
Also take note that for DebiCheck / Registered Mandates the first collection amount is independent from the instalment amount and that if you set your first collection date to the same date as your collection starting date you will be running two collections on the same day, one for the first collection amount and one for the instalment amount. Normally you would set your collection starting date one interval after the DebiCheck / Registered Mandate first collection date.
Path
POST /collections/submit
Request Body
Note:
- Parameters under
debicheckandregistered_mandatesare conditional based on the payment method chosen.
{
"batch_reference": "RFR23011",
"records": [{
// either pass the customer_id or the customer object
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
// create a new customer
"customer": {
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "9004014800083",
"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,
},
// either pass the bank_account_id or the bank_account object
// must be linked to customer_id when used
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
// create a new bank account
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"is_tax": false, // true - adds 15% VAT
// Total mandate and collection amounts are calculated based on the items provided
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn",
"description": "",
"price": 45.00, // price excluding VAT
"qty": 1
}, ...],
// either pass the mandate_id or the mandate object
// must be linked to bank_account_id when used
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
// create a new mandate
"mandate": {
"reference": "ABC123",
"contract_reference": "CTC24091900001",
"payment_industry": "ACCOUNT_REPAYMENT",
// required for recurring collections
"recurring": {
"process_day": 1,
"date_release": "2026-05-12"
},
// required for one-time collections
"one_time": {
"process_date": "2024-10-25"
},
// required if Payment Method is for DebiCheck
"debicheck": {
"first_collection_date": "2024-10-16",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
"adjustment_category": "ANNUALLY", // only allowed when 'allow variable amount' is set to true
"adjustment_type": "RATE",
"adjustment_rate": "5.12345",
"adjustment_amount": "0.00",
"approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2",
"mandate_authentication_code": "12345678" // only used with DebiCheck TT3 approval windows
},
// required if Payment Method is for Registered Mandates
"registered_mandate": {
"first_collection_date": "2024-10-16",
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4,
},
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
// create a recurring collection
"recurring": {
// can be different from mandate if allow 'allow_date_adjustment' is true with DebiCheck for example
"process_day": 1,
// When using the date adjustment rule on the payment method (e.g. collect on previous business day) then make sure this date is after the first collection date of the mandate.
"date_start": "2024-10-01",
"date_end": "2025-09-30",
},
// this could also be used to create a one-time collection from a recurring mandate (re-using the mandate)
"one_time": {
"process_date": "2024-10-25",
// transaction reference for one-time collections
"transaction_reference": "INV0045",
},
},
// optional: provide this input if you want invoices to be created when collections run
"invoice": {
"due_days": 30,
"memo": "My custom invoice memo",
"footer": "My custom invoice footer",
"email_invoice": true
}
}, {
...
}]
}
Request Parameters
Field | Required | Type | Description | Example |
|---|---|---|---|---|
| batch_reference | N | String(128) | Custom API reference number you may assign to this collection that will also reflect on subsequent transactions. | RFR23011 |
| *.customer_id | C | String(32) | Customer id, either the customer_id or customer object is required | cus_Fjim5EFyD3mUcXWcaoOkP |
| *.customer.reference | Y | String(35) | Reference to identify a specific customer | CLN240919000001 |
| *.customer.company_name | Y | 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. Only applies to EFT DO payment methods and RM payment methods provided by ABSA. | Superior Meteor Corp |
| *.customer.person_name | Y | String(32) | Name of the person to be collected from | John |
| *.customer.person_surname | Y | String(32) | Surname of the person to be collected from | Doe |
| *.customer.client_type | N | ENUM | For use with Nedbank provided payment methods. Defaults to Resident individual / Domestic company. (DOMESTIC_COMPANY,FINANCIAL_INSTITUTION,FOREIGN_COMPANY,NONRESIDENT_INDIVIDUAL,RESIDENT_INDIVIDUAL). | RESIDENT_INDIVIDUAL |
| *.customer.id_type | C | ENUM | Required field for DebiCheck / RM. Note: Company Registration Number type lookup only applies when using 'company_name'. (COMPANY_REGISTRATION_NUMBER,PASSPORT_NUMBER,SOUTH_AFRICAN_ID,TEMPORARY_RESIDENCE). | SOUTH_AFRICAN_ID |
| *.customer.id_number | C | String(14) | Required field for DebiCheck / RM. ID number relating to the ID type | 9004014800083 |
| *.customer.email | Y | String(128) | Valid email address of the person to be collected from. | johndoe@mail.com |
| *.customer.contact_number | N | String(16) | Mobile contact number of the person to be collected from. Must include the area code. Required for 'DebiCheck TT1 realtime approval within 3 minutes' approval windows. | +27831234567 |
| *.customer.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 |
| *.customer.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 |
| *.customer.city_or_town | N | String(64) | City/Town where address lines 1 and 2 are located in. | Pretoria |
| *.customer.postal_code | N | Integer | Postal code related to address lines 1 and 2. | 1285 |
| *.bank_account_id | C | String(32) | Bank account id, either the bank_account_id or bank_account object is required. Must be linked to the customer_id when used. | ban_6cPkvUpiFRgO07ChKgEPi |
| *.bank_account.bank_account_holder_name | C | String(30) | Bank account holder name for the bank account to be collected from | J DOE |
| *.bank_account.bank_account_number | C | String(17) | Bank account number to be collected from | 10004291601 |
| *.bank_account.bank_account_type | C | ENUM | (CHEQUE_OR_CURRENT,SAVINGS,TRANSMISSION) | CHEQUE_OR_CURRENT |
| *.bank_account.bank_name | C | ENUM | Make sure to check the available bank accounts for the selected payment method first (GET /lookups/bank_name/pam_123456abcd). (ABSA_BANK_LIMITED,ABSAITHALA,ACCESS_BANK,AFRICAN_BANK,AFRICAN_BANK_BUSINESS_GRINDROD,ALBARAKA_BANK,BANK_WINDHOEK_BEPERK,BANK_ZERO,BIDVEST_BANK,BIDVEST_BANK_LIMITED,BNP_PARIBAS,CAPITEC_BUSINESS,CAPITEC_PERSONAL,DISCOVERY_BANK_LTD,ENL_MUTUAL_BANK,FBC_FIDELITY_BANK_LTD,FINBOND_EPE,FINBOND_MUTUAL_BANK,FIRST_NATIONAL_BANK_LESOTHO,FIRST_NATIONAL_BANK_NAMIBIA,FIRST_NATIONAL_BANK_SWAZILAND,FIRSTRAND_BANK,FNB_FIRST_NATIONAL_BANK,HABIB_OVERSEAS_BANK_LIMITED,HSBC_BANK,INVESTEC_BANK_LIMITED,JP_MORGAN,NEDBANK,NEDBANK_LESOTHO_LIMITED,NEDBANK_NAMIBIA,NEDBANK_SWAZILAND_LIMITED,OLYMPUS_MOBILE,OM_BANK_LIMITED,PEOPLE_BANK_LTD_INC_PEP_BANK,PEOPLES_BANK_LTD_INC_NBS,PERMANENT_BANK,RMB_RAND_MERCHANT_BANK,SA_POST_BANK_POST_OFFICE,SOCIETE_GENERAL_JHB_BRANCH,STANDARD_BANK_NAMIBIA,STANDARD_BANK_SA_LTD,STANDARD_BANK_SWAZILAND,STANDARD_CHARTERED_BANK_SA,STANDARD_LESOTHO_BANK_LTD,SWAZILAND_DEV_AND_SAVINGS_BANK,TYME_BANK_LIMITED,UBANK_LTD,UNIBANK_LIMITED,VBS_MUTUAL_BANK) | ABSA_BANK_LIMITED |
| *.bank_account.bank_branch_code | C | Integer | Universal bank branch code for the account number | 632005 |
| *.is_tax | N | Boolean | true - Adds 15% VAT to the total amount. | false |
| *.items | Y | Array | Items purchased by this collection. Total mandate and collection amounts are calculated based on items. | |
| *.items. *.product_id | C | String(32) | Line item product id, see products API. Only MONTHLY RECURRING, YEARLY RECURRING and ONE_TIME products are allowed. Only DebiCheck / RM payment methods allow combining one-time with recurring products, the one-time products will feed into the first collection amount and the recurring products will feed into the instalment amount. | pro_MsAXh25ajSIv4s6k52vQn |
| *.items. *.description | N | String(256) | Line item description | Good for exercise |
| *.items. *.price | C | Decimal | Line item price. Price excluding VAT (if taxed). | 45.00 |
| *.items. *.qty | C | Integer | Line item quantity | 1 |
| *.mandate_id | C | String(32) | Mandate id, either the mandate_id or mandate object is required. Must be linked to the bank_account_id when used. | pam_BX4HNZjMMI-tt8_KWyxAq |
| *.mandate.reference | N | String(256) | Optional custom reference number for the mandate | ABC123 |
| *.mandate.recurring.process_day | C | 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 |
| *.mandate.recurring.date_release | N | Date(YYYY-MM-DD) | When this mandate is to cease / when the contract ends | 2026-05-12 |
| *.mandate.one_time.process_date | C | Date(YYYY-MM-DD) | Date upon which collection will be processed once | 2024-09-30 |
| *.mandate.payment_industry | N | ENUM | (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 |
| *.mandate.contract_reference | C | String(14) | This uniquely identifies the mandate with the bank and will show on bank statements. | CTC24091900001 |
| *.mandate.debicheck.first_collection_date | C | Date(YYYY-MM-DD) | When the one-time products items are to be billed. WARNING: If this date is the same as the collection starting date then 2 collections will be attempted on the same day, one for the first collection amount and one for the instalment amount. This first collection date and amount is independent from the collection date start and instalment amount. First collections require a connected payment before they will run, creating a mandate alone will not run a DebiCheck first collection amount. Normally the first collection date would be one interval before the collection starting date. | 2024-10-16 |
| *.mandate.debicheck.allow_date_adjustment | N | Boolean | Indicates that collections may be made on billing days other than the day specified on the mandate. | true |
| *.mandate.debicheck.allow_variable_amount | N | Boolean | Indicates that the amount collected on the billing day may be changed. This flag must be true if you intend on using the adjustment category amount/rates (increases). | false |
| *.mandate.debicheck.allow_payment_tracking | N | Boolean | Allow automated resubmission of failed collections. Warning: the resubmitted collection becomes disputable. | true |
| *.mandate.debicheck.payment_tracking_max_days | N | Integer | 1 to 10 Days. If the collection failed on the billing day the bank will automatically re-submit failed collections each successive day until the max tracking day count is reached or the collection succeeds. | 4 |
| *.mandate.debicheck.adjustment_category | N | ENUM | Used to increase the DebiCheck mandate instalment amount per specified interval e.g. increase instalment amount by R 10.00 every year. (ANNUALLY,BIANNUALLY,NEVER,QUARTERLY). See increase API. | NEVER |
| *.mandate.debicheck.adjustment_type | N | ENUM | Amount or rate as a percentage. (AMOUNT,RATE) | AMOUNT |
| *.mandate.debicheck.adjustment_rate | N | Decimal | Determines the percentage to increase the instalment amount per adjustment category interval e.g 5.12345% per year | 5.12345 |
| *.mandate.debicheck.adjustment_amount | N | Decimal | Determines the amount to increase the instalment amount by, 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 |
| *.mandate.debicheck.approval_window | N | ENUM | Determines how long the user has to approve the DebiCheck mandate. (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 | C | String(8) | MAC_TT3_MESSAGE_AUTHENTICATION_CODE_CARD_AND_PIN 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 |
| *.mandate.registered_mandate.first_collection_date | C | Date(YYYY-MM-DD) | When the one-time products items are to be billed. WARNING: If this date is the same as the collection starting date then 2 collections will be attempted on the same day, one for the first collection amount and one for the instalment amount. This first collection date and amount is independent from the collection date start and instalment amount. First collections require a connected payment before they will run, creating a mandate alone will not run a Registered Mandates first collection amount. Normally the first collection date would be one interval before the collection starting date. | 2024-10-16 |
| *.mandate.registered_mandate.allow_date_adjustment | N | Boolean | Indicates that collections may be made on billing days other than the day specified on the mandate. | true |
| *.mandate.registered_mandate.allow_variable_amount | N | Boolean | Indicates that the amount collected on the billing day may be changed. | false |
| *.mandate.registered_mandate.allow_payment_tracking | N | Boolean | Allow automated resubmission of failed collections. Warning: the resubmitted collection becomes disputable. | true |
| *.mandate.registered_mandate.payment_tracking_max_days | N | Integer | 1 to 10 Days. If the collection failed on the billing day the bank will automatically re-submit failed collections each successive day until the max tracking day count is reached or the collection succeeds. | 4 |
| *.collection.payment_methods_id | Y | String(32) | ID of the payment method to be used for this collection | pam_BX4HNZjMMI-tt8_KWyxAq |
| *.collection.recurring.process_day | C | 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. Can differ from the mandate, in the case of DebiCheck you could specify 'allow_date_adjustment' and then define a different process day here | 1 |
| *.collection.recurring.date_start | C | Date | Date to start recurring collections. When using a date adjustment rule with a DebiCheck / Registered Mandate payment methods you need to make sure that this starting date is after (or on - if you wish to run 2 collections the same day) the first collection date e.g. setting both your first collection date and starting date to a Sunday will not work with the COLLECT_ON_PREVIOUS_BUSINESS_DAY rule because the payment starting date will be shifted to Friday which is then before the first collection date Sunday. | 2024-10-01 |
| *.collection.recurring.date_end | C | Date | Date to end recurring collections, leave blank to stop manually | 2025-09-30 |
| *.collection.one_time.process_date | C | Date(YYYY-MM-DD) | Date upon which collection will be processed once. Could also be used with a recurring mandate to create manually submitted batches. | 2024-09-30 |
| *.collection.one_time.transaction_reference | N | String(32) | Unique reference for transactions | INV-001234 |
| *.invoice | N | Object | Exclude this input if you do not wish invoices to be generated for collections. | |
| *.invoice.due_days | N | Integer | Defaults to 30 days. Due days reflected on the invoice | 30 |
| *.invoice.memo | N | String | Optional invoice memo | Private client |
| *.invoice.footer | N | String | Optional invoice footer | Help Line: 083 123 4567 |
| *.invoice.email_invoice | N | Boolean | true - Send an invoice email to the customer when the collection generates a paid/unpaid transaction. false - Only generate the invoice. | true |
Response Body
The response follows the same format as the list response
{
"status": true,
"records": [{
"collection_id": "col_7epIhJUFSH9c7OKVZpJ8e",
...
"collection_status": "RUNNING",
...
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"customer": {
...
},
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"bank_account": {
...
},
"is_tax": false,
"items": [{
...
"price": 45.00,
...
}, ...],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"mandate": {
...
"amount": "45.00",
"recurring": {
...
},
"one_time": {
...
},
"debicheck": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
...
},
"registered_mandate": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
...
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"amount_excl": "45.00",
"recurring": {
...
},
"one_time": {
...
},
},
"invoice": {
...
}
}, ...]
}
Examples
EFT Debit Order Controlled Recurring Collections
Below is an example for controlling recurring mandate batch submissions yourself with EFT Debit Orders:
{
"batch_reference": "RFR23011",
"records": [{
"customer": {
"reference": "CLN240919000001",
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
},
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 16
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900002"
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-01-16",
"transaction_reference": "INV0045"
},
},
}]
}
Subsequent submissions might look like this:
{
"batch_reference": "RFR23021",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-02-16",
"transaction_reference": "INV0046",
},
},
}]
}
EFT Debit Order Automated Recurring Collections
Below is an example of submitting an automated recurring EFT Debit Order where the customer and mandate details are not already on the system. The customer and bank details will be saved and could be re-used in future collections. These collections will automatically be scheduled and submitted based on the chosen payment interval (and payment method date adjustment rule).
{
"batch_reference": "RFR23011",
"records": [{
"customer": {
"reference": "CLN240919000001",
"person_name": "John",
"person_surname": "Doe",
"email": "johndoe@mail.com",
"contact_number": "+27831234567",
},
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 1
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900002"
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"recurring": {
"process_day": 1,
"date_start": "2026-01-01",
"date_end": "2026-09-30",
},
},
}]
}
EFT Debit Order Fixed One-Time Collections
Below is an example of an EFT Debit Order collection that will only be executed once.
{
"batch_reference": "RFR25056",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // one-time product
"price": 45.00,
"qty": 1
}],
"mandate": {
"one_time": {
"process_date": "2026-05-16"
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900002"
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-05-16",
"transaction_reference": "INV0021"
},
}
}, {
...
}]
}
DebiCheck Controlled Recurring Collections
Below is an example of how to submit a recurring DebiCheck mandate where you control the batch submissions yourself.
{
"batch_reference": "RFR25051",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 1,
"date_release": "2028-12-15"
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"debicheck": {
"allow_date_adjustment": true,
"allow_variable_amount": false,
"allow_payment_tracking": false,
"approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-01-01",
"transaction_reference": "INV0045",
},
}
}, {
...
}]
}
Subsequent submissions will look like this:
{
"batch_reference": "RFR25061",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-02-01",
"transaction_reference": "INV0046",
},
}
}, {
...
}]
}
DebiCheck Automated Recurring Collections
Below collections will be scheduled and submitted automatically on a monthly or yearly basis (depending on the payment interval you choose).
{
"batch_reference": "RFR25052",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // one-time product
"price": 15.00,
"qty": 1
}, {
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // monthly recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 1
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"debicheck": {
"first_collection_date": "2026-01-01", // Runs R 15.00
"allow_date_adjustment": true,
"allow_variable_amount": true, // required when using adjustment category
"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"
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"recurring": {
"process_day": 1,
"date_start": "2026-02-01", // Runs R 45.00
"date_end": "2027-02-20",
},
}
}, {
...
}]
}
DebiCheck Fixed One-Time Collections
Below collection will only be executed once.
{
"batch_reference": "RFR25053",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // one-time product
"price": 45.00,
"qty": 1
}],
"mandate": {
"one_time": {
"process_date": "2026-05-16"
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"debicheck": {
"approval_window": "BATCH_TT2_APPROVE_BY_19H00_ON_DAY_2"
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-05-16",
"transaction_reference": "INV0031",
},
}
}, {
...
}]
}
Registered Mandate Controlled Recurring Collections
Below is an example of how to submit a recurring Registered Mandate where you control the batch submissions yourself.
{
"batch_reference": "RFR25051",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 1
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"registered_mandate": {
"allow_date_adjustment": true,
"allow_variable_amount": false,
"allow_payment_tracking": false
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-01-01",
"transaction_reference": "INV0045"
},
}
}, {
...
}]
}
Subsequent submissions will look like this:
{
"batch_reference": "RFR25061",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-02-01",
"transaction_reference": "INV0046"
},
}
}, {
...
}]
}
Registered Mandate Automated Recurring Collections
Below collections will be scheduled and submitted automatically on a monthly or yearly basis (depending on the payment interval you choose).
{
"batch_reference": "RFR25052",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // one-time product
"price": 15.00,
"qty": 1
}, {
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate": {
"recurring": {
"process_day": 1
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"registered_mandate": {
"first_collection_date": "2026-01-01", // Runs R 15.00
"allow_date_adjustment": true,
"allow_variable_amount": true,
"allow_payment_tracking": true,
"payment_tracking_max_days": 4
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"recurring": {
"process_day": 1,
"date_start": "2026-02-01", // Runs R 45.00
"date_end": "2027-02-15",
},
}
}, {
...
}]
}
Registered Mandate Fixed One-Time Collections
Below collection will only be executed once.
{
"batch_reference": "RFR25053",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // one-time product
"price": 45.00,
"qty": 1
}],
"mandate": {
"one_time": {
"process_date": "2026-05-16"
},
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001"
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"one_time": {
"process_date": "2026-05-16",
"transaction_reference": "INV0031"
},
}
}, {
...
}]
}
Invoice Example
{
"batch_reference": "RFR23011",
"records": [{
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"is_tax": true, // true - adds 15% VAT
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn", // recurring product
"price": 45.00,
"qty": 1
}],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"recurring": {
"process_day": 1,
"date_start": "2026-01-01"
},
},
"invoice": {
"due_days": 30,
"memo": "My custom invoice memo",
"footer": "My custom invoice footer",
"email_invoice": true
}
}]
}
Update Collections Details
Update the details of an existing collections record. To update the customer, bank account or mandate use the relevant API call.
WARNING
You can not convert a recurring collection to a one-time collection or vice versa.
amountchanges will only reflect on new transactions created. If a transaction is already in the process of being sent to the bank (for this collection) the amount of that transaction will not get updated.
date_startandprocess_datecan not be amended if a transaction has already been logged for this collection.
process_daycan not be changed when using a DebiCheck / Registered Mandate payment method with a collection that does not specifyallow_date_adjustment.This update won't affect the connected mandate and it is your responsibility to make sure your collection details are corrected when amending mandates. To amend a mandate.
Path
POST /collections/update
Request Body
Note:
- Optional variables can be cleared by passing in
null.
{
"records": [{
"collection_id": "col_7epIhJUFSH9c7OKVZpJ8e",
"collection_status": "RUNNING",
"is_tax": false, // true - adds 15% VAT
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn",
"description": "",
"price": 45.00, // price excluding VAT
"qty": 1
}, ...],
"recurring": {
"date_start": "2026-01-01",
"date_end": "2027-09-30",
"process_day": 1
},
"one_time": {
"process_date": "2026-01-01",
},
// optional: provide this input if you want invoices to be created when collections run
"invoice": {
"due_days": 30,
"memo": "My custom invoice memo",
"footer": "My custom invoice footer",
"email_invoice": true
}
}, {
...
}]
}
Updating Only the Status
{
"records": [{
"collection_id": "col_7epIhJUFSH9c7OKVZpJ8e",
"collection_status": "PAUSED"
}, {
...
}]
}
Request Parameters
Field | Required | Can be Cleared | Type | Description | Example |
|---|---|---|---|---|---|
| *.collection_id | Y | - | String(32) | Collection record ID | col_7epIhJUFSH9c7OKVZpJ8e |
| *.collection_status | N | N | ENUM | If provided will change the status of the collection (leave blank to keep same status). (PAUSED,RUNNING,STOPPED). WARNING: STOPPED status will permanently disable the collection. | RUNNING |
| *.is_tax | N | Y | Boolean | true - Adds 15% VAT to the collection amount. | false |
| *.items | N | N | Array | Only updates the payment amounts (and mandate first collection amount excl), to change the mandate amounts see. This input will overwrite all items stored in the collection, you can not change line items individually, therefore make sure to include your one-time products as well (if applicable). | |
| *.items. *.product_id | C | N | String(32) | Line item product id, see products API. Only MONTHLY RECURRING, YEARLY RECURRING and ONE_TIME products are allowed. Only DebiCheck / RM payment methods allow combining one-time with recurring products, the one-time products will feed into the first collection amount and the recurring products will feed into the instalment amount. | pro_MsAXh25ajSIv4s6k52vQn |
| *.items. *.description | N | Y | String(256) | Line item description | Good for exercise |
| *.items. *.price | C | N | Decimal | Line item price. Price excluding VAT (if taxed). | 45.00 |
| *.items. *.qty | C | N | Integer | Line item quantity | 1 |
| *.recurring.date_start | N | N | Date(YYYY-MM-DD) | Date to start recurring collections | 2026-01-01 |
| *.recurring.date_end | N | Y | Date(YYYY-MM-DD) | Date to end recurring collections, leave blank to stop manually | 2027-09-30 |
| *.recurring.process_day | N | 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. If a transaction has already been submitted this month then the new process day will only be used in next month's submission. | 1 |
| *.one_time.process_date | N | N | Date(YYYY-MM-DD) | Date upon which collection will be processed once. Only allowed for one-time collections coupled to recurring mandates. One-time collections coupled to one-time mandates need to be paused/stopped and re-created for changes to the process date. | 2026-01-01 |
| *.invoice | N | Y | Object | Set this input to null to cancel invoice generation or leave undefined if invoices were never set up for this collection. | |
| *.invoice.due_days | N | Y | Integer | Defaults to 30 days. Due days reflected on the invoice | 30 |
| *.invoice.memo | N | Y | String | Optional invoice memo | Private client |
| *.invoice.footer | N | Y | String | Optional invoice footer | Help Line: 083 123 4567 |
| *.invoice.email_invoice | N | Y | Boolean | true - Send an invoice email to the customer when the collection generates a paid/unpaid transaction. false - Only generate the invoice. | true |
Response Body
The response follows the same format as the list response
{
"status": true,
"records": [{
"collection_id": "col_7epIhJUFSH9c7OKVZpJ8e",
...
"collection_status": "RUNNING",
...
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"customer": {
...
},
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"bank_account": {
...
},
"is_tax": false,
"items": [{
...
"price": 45.00,
...
}, ...],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"mandate": {
...
"amount": "45.00",
"recurring": {
...
},
"one_time": {
...
},
"debicheck": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
...
},
"registered_mandate": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
...
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"amount_excl": "45.00",
"recurring": {
...
},
"one_time": {
...
},
},
"invoice": {
...
}
}, ...]
}
List
List current one-time or recurring collections loaded on the platform.
Path
GET /collections/list?{params}
Query Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| collection_status | ENUM | N | Filter for a specific collection status. (CANCELLED,COMPLETED,NO_REPLY,PAUSED,PENDING,REJECTED,RUNNING,STOPPED). | RUNNING |
| bank_account_status | ENUM | N | Filter for a specific bank account status. (ACTIVE,ARCHIVED,DISABLED). | ACTIVE |
| customer_status | ENUM | N | Filter for a specific customer status. (ACTIVE,ARCHIVED,DISABLED) | ACTIVE |
| 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 |
| collection_interval | ENUM | N | (MONTHLY,YEARLY). | MONTHLY |
| customer_id | String(32) | N | Filter for a specific customer id. | cus_Fjim5EFyD3mUcXWcaoOkP |
| bank_account_id | String(32) | N | Filter for a specific bank account id. | ban_6cPkvUpiFRgO07ChKgEPi |
| mandate_id | String(32) | N | Filter for a specific mandate id. | man_z394ohSi6Wxvpb5pcZvFJ |
| collection_id | String(32) | N | Filter for a specific collection id. | col_7epIhJUFSH9c7OKVZpJ8e |
| payment_methods_id | String(32) | N | Filter for a specific payment method id. | pam_BX4HNZjMMI-tt8_KWyxAq |
| date_created_start | Date(YYYY-MM-DD) | N | Filter for records that have a created date after this date specified. | 2024-09-13 |
| date_created_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,
"records": [{
"collection_id": "col_7epIhJUFSH9c7OKVZpJ8e",
"deleted_at": null,
"updated_at": "2024-02-02 15:00:45",
"created_at": "2024-02-02 15:00:45",
"batch_reference": "RFR23011",
"collection_status": "RUNNING",
"collection_failed_at": "2024-02-03 15:00:45",
"collection_failed_at_reason": "No such account",
"customer_id": "cus_Fjim5EFyD3mUcXWcaoOkP",
"customer": {
"reference": "CLN240919000001",
"company_name": null,
"person_name": "John",
"person_surname": "Doe",
"client_type": "RESIDENT_INDIVIDUAL",
"id_type": "SOUTH_AFRICAN_ID",
"id_number": "9004014800083",
"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,
},
"bank_account_id": "ban_6cPkvUpiFRgO07ChKgEPi",
"bank_account": {
"bank_account_holder_name": "J DOE",
"bank_account_number": "04047527520",
"bank_account_type": "CHEQUE_OR_CURRENT",
"bank_name": "ABSA_BANK_LIMITED",
"bank_branch_code": 632005
},
"is_tax": false,
"items": [{
"product_id": "pro_MsAXh25ajSIv4s6k52vQn",
"name": "Monthly Membership",
"description": "",
"price": 45.00,
"qty": 1
}, ...],
"mandate_id": "man_z394ohSi6Wxvpb5pcZvFJ",
"mandate": {
"reference": "ABC123",
"payment_industry": "ACCOUNT_REPAYMENT",
"contract_reference": "CTC24091900001",
"amount": "45.00",
"recurring": {
"process_day": 1,
"collection_interval": "MONTHLY",
"date_release": "2026-05-12"
},
"one_time": {
"process_date": "2024-10-25"
},
"debicheck": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "50.45",
"first_collection_date": "2024-10-16",
"maximum_collection_amount": "60.00",
"allow_date_adjustment": true,
"allow_variable_amount": false,
"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"
},
"registered_mandate": {
"first_collection_amount": "50.45",
"first_collection_amount_excl": "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,
}
},
"collection": {
"payment_methods_id": "pam_BX4HNZjMMI-tt8_KWyxAq",
"amount": "45.00",
"amount_excl": "45.00",
"recurring": {
"process_day": 1,
"date_start": "2024-10-01",
"date_end": "2025-09-30",
},
"one_time": {
"process_date": "2024-10-25",
"transaction_reference": "INV0045"
},
},
"invoice": {
"due_days": 30,
"memo": "My custom invoice memo",
"footer": "My custom invoice footer",
"email_invoice": true
}
}, ...]
}
Electronic Mandates
Hosted web pages that new customers can use to signup with or existing customers can use to add collections to their account.
Payouts
Send money to customer bank accounts and manage outbound transfers. Create single or batch payouts with real-time status tracking, beneficiary management, and comprehensive transaction reporting.