Finance - SwitchTransact Docs

Introduction

The finance API calls are used to get and create quotes, invoices, credit notes, sales, purchase orders and other financial data.

Get Finance Document List

This API will retrieve a list of all the financial documents like quotes, invoices, credit notes, sales and purchase orders.

Path
`POST` `/finance/documents/{people\|company}/list/{record_id\|public_id}`

Response:

{
    "records": [
        {
            "id": "950f3632-436d-4c5e-9e11-b1eeca3af651",
            "document_number": "INV00000004303",
            "date_issue": "2024-02-28T00:00:00.000Z",
            "date_due": "2024-03-28T00:00:00.000Z",
            "amount_excl": "600.00",
            "amount_incl": "600.00",
            "amount_tax": "0.00",
            "total_discount": "0.00",
            "unique_id": "012328f5faab2e238a321435f6ad5a4527eeeda322920758f9fd5fb5a563c95a",
            "created_at": "2024-02-28T08:30:22.642Z",
            "type_lookups_id": "02347884-d1c9-4726-a30a-0d30e6564ece",
            "payment_status_lookups_id": "bea388ba-508e-4ef4-9c9d-a052b3bf505e",
            "cancelled_at": null,
            "status_lookups_id": "fac17da9-f873-4afc-8ee0-c9c807cf9fda",
            "type_title": "Invoice",
            "status_title": "Sent",
            "status_class": "success",
            "payment_status_title": "Outstanding",
            "payment_status_class": "warning",
            "currency": "ZAR",
            "transaction_reference": null,
            "transactions_id": null,
            "name": "Invoice",
            "path": "invoices"
        },
        ...
    ]
}

All lookup values can be found under: Lookups API

Error Response:

{
    "status": false,
    "error": "Not authorized to make this API call. Requesting Read on General."
}

When you get this API response ensure that under the API keys section your API Key has the correct permissions: API Keys

Create a document

This API will create a finance document record on SwitchTransact.

Path
`POST` `/finance/documents/{invoice\|quote\|sales-order\|purchase-order\|credit-note}/create`

JSON Body:

{
    "accounts_currencies_id": "cddbc163-86b0-41f7-8539-d41ce9a9ef76",
    "amount_types_lookups_id": "512e1290-3df5-4782-b5ac-9b0ffbeb8afa",
    "amount_discount": "0.00",
    "companies_id": "{companies record_id}",
    "people_id": "{people record_id}",
    "items": [
        {
            "discount": 0.00,
            "product_id": null,
            "product_text": "Test description for product",
            "price": "31.00",
            "unit": "p/a",
            "qty": 1,
            "account_id": "{ optional: people record id if it is linked to a line item }"
        },
        ...
    ]
}

All lookup values can be found under: Lookups API

Success Response:

{
    "recordId": "{GUID record id}",
    "uniqueId": "{Public ID string}"
    "record": {
      ...
    }
}

Error Response:

{
    "error": "Not authorized to make this API call. Requesting Read on General."
}

List Payment Methods

List the payment methods available. All lookup values can be found under: Lookups API

Path
`GET` `/finance/payment/methods`

Success Response:

{
    "status": true,
    "records": [{
        "id": "{unique record_id}",
        "is_active": true,
        "pre_process_days": 10,
        "item_limit": "20000.00",
        "warning_limit": "10000.00",
        "abbreviated_name": "TST FUND",
        "is_test": false,
        "process_lookups_id": "ed8560ec-4ee2-422e-89b6-2e768ad09839",
        "is_default": true,
        "bank_reference": "TSTF",
        "is_enable_invoice_payment": true,
        "subscriptions_document_type_lookups_id": "02347884-d1c9-4726-a30a-0d30e6564ece",
        "companies_subscriptions_email_messages_templates_id": "{messages_templates record_id}",
        "companies_subscriptions_sms_messages_templates_id": "{messages_templates record_id}",
        "companies_subscriptions_email_paid_messages_templates_id": "{messages_templates record_id}",
        "companies_subscriptions_sms_paid_messages_templates_id": "{messages_templates record_id}",
        "people_subscriptions_email_messages_templates_id": "{messages_templates record_id}",
        "people_subscriptions_sms_messages_templates_id": "{messages_templates record_id}",
        "people_subscriptions_email_paid_messages_templates_id": "{messages_templates record_id}",
        "people_subscriptions_sms_paid_messages_templates_id": "{messages_templates record_id}",
        "is_send_finance_documents": true,
        "is_generate_subscription_document_on_failure": false
    }, ...]
}

Field	Type	Description	Options	Example
id	string	Unique ID associated with the payment method and used in other API calls	UUID	"{unique record_id}"
is_active	boolean	If this payment method is considered to be active	true, false	true
pre_process_days	integer	Amount of days batch accounts are generated in advance		10
item_limit	decimal	Maximum amount a subscription product may cost using this payment method		20000.00
warning_limit	decimal	Subscription product amounts above this amount is considered to be a warning		10000.00
abbreviated_name	string	Short name for this payment method		"TST FUND"
is_test	boolean	If this payment method is in the testing phase or not	true, false	false
process_lookups_id	string	Lookups ID of the process type for this payment method	UUID	"ed8560ec-4ee2-422e-89b6-2e768ad09839"
is_default	boolean	If this payment method is considered to be the default	true, false	true
bank_reference	string	Bank reference used on statements by this payment method (if applicable, used by automatic payments)		"TSTF"
is_enable_invoice_payment	boolean	Allows payments of invoices from the web page	true, false	true
subscriptions_document_type_lookups_id	string	Default document type used on automatically created subscriptions	UUID	"02347884-d1c9-4726-a30a-0d30e6564ece"
companies_subscriptions_email_messages_templates_id	string	Default email template ID populated on automatically created subscriptions for companies	UUID	"{messages_templates record_id}"
companies_subscriptions_sms_messages_templates_id	string	Default SMS template ID populated on automatically created subscriptions for companies	UUID	"{messages_templates record_id}"
companies_subscriptions_email_paid_messages_templates_id	string	Default email template ID populated on automatically created subscriptions for companies with (paid transactions)	UUID	"{messages_templates record_id}"
companies_subscriptions_sms_paid_messages_templates_id	string	Default SMS template ID populated on automatically created subscriptions for companies (with paid transactions)	UUID	"{messages_templates record_id}"
people_subscriptions_email_messages_templates_id	string	Default email template ID populated on automatically created subscriptions for people	UUID	"{messages_templates record_id}"
people_subscriptions_sms_messages_templates_id	string	Default SMS template ID populated on automatically created subscriptions for people	UUID	"{messages_templates record_id}"
people_subscriptions_email_paid_messages_templates_id	string	Default email template ID populated on automatically created subscriptions for people (with paid transactions)	UUID	"{messages_templates record_id}"
people_subscriptions_sms_paid_messages_templates_id	string	Default SMS template ID populated on automatically created subscriptions for people (with paid transactions)	UUID	"{messages_templates record_id}"
is_send_finance_documents	boolean	When a subscription is automatically created if the finance documents send setting should be checked	true, false	true
is_generate_subscription_document_on_failure	boolean	When a subscription is automatically created if the finance documents generate on unpaid setting should be checked	true, false	false

List Cards

List the cards loaded by a person/company All lookup values can be found under: Lookups API

Path
`GET` `/finance/cards/{people record_id\|companies record_id}`

Success Response:

{
    "status": true,
    "records": [{
        "id": "{unique record_id}",
        "people_id": "{people record_id}",
        "companies_id": "{companies record_id}",
        "card_name": "J DOE",
        "card_nickname": "My Visa card",
        "card_number_obfuscated": "**** **** **** 1234",
        "is_default": true,
        "is_active": true,
        "card_expire_date": "YYYY-MM-DD",
        "payment_methods_id": "{payment_methods record_id}",
        "status_lookups_id": "0fb2eadd-2963-4a04-b3ac-35d0168127d9"
    }, ...]
}

Field	Type	Description	Options	Example
id	string	Unique ID of the cards record and used in other API calls	UUID	"{unique record_id}"
people_id	string	People ID associated with the card	UUID	"{people record_id}"
companies_id	string	Company ID associated with the card	UUID	"{companies record_id}"
card_name	string	Card name		"J DOE"
card_nickname	string	Nickname given to the card (display purposes only)		"My Visa card"
card_number_obfuscated	string	Obfuscated card number		"** ** 1234"
is_default	boolean	If this card is considered to be the default	true, false	true
is_active	boolean	If this card is considered to be active	true, false	true
card_expire_date	date	Date when the card expires	"YYYY-MM-DD"	2025-09-01
payment_methods_id	string	Payment method ID associated with the card	UUID	"{payment_methods record_id}"
status_lookups_id	string	Status lookups ID of the card	UUID	"0fb2eadd-2963-4a04-b3ac-35d0168127d9"

List Products

List the products available. All lookup values can be found under: Lookups API

Path
`GET` `/finance/products`

Success Response:

{
    "status": true,
    "records": [{
        "id": "{unique record_id}",
        "name": "Gold member",
        "unique_id": "GM",
        "unit_name": "membership",
        "unit_label": "p/m",
        "accounting_code": "G1234",
        "price": "245.55",
        "is_fixed_price": false,
        "pricing_lookups_id": "1e694821-3e85-46b0-9da1-4d26980616f3",
        "interval_sequence": 1,
        "interval_time_lookups_id": "241be562-fc68-4769-8c2c-014e3da5a2c3",
        "default_accounts_tax_id": "{accounts_tax record_id}",
        "is_active": true,
        "is_fixed_quantity": false,
        "default_quantity": 1,
        "accounts_currencies_id": "{accounts_currencies record_id}",
        "is_membership_product": true,
        "description": "monthly gold membership",
        "entry_class_lookups_id": "a57e1fcc-aae7-4b0b-9256-7c8e2729109d"
    }, ...]
}

Field	Type	Description	Options	Example
id	string	Unique ID of the product and used in other API calls	UUID	"{unique record_id}"
name	string	Name given to the product		"Gold member"
unique_id	string	Unique ID given to the product		"GM"
unit_name	string	Unit name of the product		"membership"
unit_label	string	Unit label of the product		"p/m"
accounting_code	string	Accounting code of the product		"G1234"
price	decimal	Price of the product		245.55
is_fixed_price	boolean	true - price may not be changed in subscription products	true, false	false
pricing_lookups_id	string	Pricing type lookups ID	UUID	"1e694821-3e85-46b0-9da1-4d26980616f3"
interval_sequence	integer	Interval of the product (how often it would run e.g. once a month, every second month etc)		1
interval_time_lookups_id	string	Interval time lookups ID of the product e.g. monthly	UUID	"241be562-fc68-4769-8c2c-014e3da5a2c3"
default_accounts_tax_id	string	Accounts tax ID associated with this product	UUID	"{accounts_tax record_id}"
is_active	boolean	If this product is considired to be active	true, false	true
is_fixed_quantity	boolean	true - quantity may not be changed in subscription products	true, false	false
default_quantity	integer	Deault quantity of this product		1
accounts_currencies_id	string	Account currency ID associated with this product	UUID	"{accounts_currencies record_id}"
is_membership_product	boolean	true - if this product counts towards membership paid up status	true, false	true
description	string	Description of the product		"monthly gold membership"
entry_class_lookups_id	string	Bank entry class associated with this product e.g. account repayment, charitable payment etc.	UUID	"a57e1fcc-aae7-4b0b-9256-7c8e2729109d"

Banking Details

These API calls allow for manipulating banking details. All lookup values can be found under: Lookups API

Create

Path
`POST` `/finance/banking/details/create`

JSON Body:

{
    "account_name": "J Doe",
    "account_number": "10004291601",
    "branch_code": "051001",
    "bank_lookups_id": "b6db0d6f-e6fe-4671-8803-f3cb34f9b417",
    "account_type_lookups_id": "57e2ad24-7f2d-4f8e-853c-11a1e3a229ab",
    "is_active": true,
    "companies_id": "{companies record_id}",
    "people_id": "{people record_id}"
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
account_name	string	R	Bank account holder name	max 30 characters, alpha numeric with spaces	J Doe
account_number	integer	R	Bank account number	max 17 digits	10004291601
branch_code	integer	R	Universal branch code of the associated bank	Max 6 digits	051001
bank_lookups_id	String	R	Lookups ID of the associated bank	UUID, Lookups type 'Bank' and category 'BankAccounts'	b6db0d6f-e6fe-4671-8803-f3cb34f9b417
account_type_lookups_id	string	R	Lookups ID of the bank account type	UUID, Lookups type 'Type' and category 'BankAccounts'	57e2ad24-7f2d-4f8e-853c-11a1e3a229ab
is_active	boolean	O	If this bank account is currently active	defaults to false	true
companies_id	String	C - either people id or companies id must be defined	ID of the associated company	UUID	"{companies record_id}"
people_id	String	C - either people id or companies id must be defined	ID of the associated person	UUID	"{people record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Error, account fields are not correct",
    "errors": {
        "account_name": {
            "message": "account name is required",
            "rule": "required"
        }
    }
}

View

Path
`GET` `/finance/banking/details/{banking_details record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the banking details returned upon create	UUID	"{banking_details record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        "account_name": "J Doe",
        "account_number": "10004291601",
        "branch_code": "051001",
        "bank_lookups_id": "b6db0d6f-e6fe-4671-8803-f3cb34f9b417",
        "account_type_lookups_id": "57e2ad24-7f2d-4f8e-853c-11a1e3a229ab",
        "accounts_currencies_id": "cddbc163-86b0-41f7-8539-d41ce9a9ef76",
        "is_active": true,
        "companies_id": "{companies record_id}",
        "people_id": "{people record_id}"
    }
}

Field	Type	Description	Options	Example
record	Object	Details of the record in question
record .account_name	string	Bank account holder name	max 30 characters, alpha numeric with spaces	J Doe
record .account_number	integer	Bank account number	max 17 digits	10004291601
record .branch_code	integer	Universal branch code of the associated bank	Max 6 digits	051001
record .bank_lookups_id	String	Lookups ID of the associated bank	UUID	b6db0d6f-e6fe-4671-8803-f3cb34f9b417
record .account_type_lookups_id	string	Lookups ID of the bank account type	UUID	57e2ad24-7f2d-4f8e-853c-11a1e3a229ab
record .is_active	boolean	If this bank account is currently active	defaults to false	true
record .companies_id	String	ID of the associated company	UUID	"{companies record_id}"
record .people_id	String	ID of the associated person	UUID	"{people record_id}"

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Edit

Path
`POST` `/finance/banking/details/edit/{banking_details record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the banking details returned upon create	UUID	"{banking_details record_id}"

JSON Body:

{
    "account_name": "J Doe",
    "account_number": "10004291601",
    "branch_code": "051001",
    "bank_lookups_id": "b6db0d6f-e6fe-4671-8803-f3cb34f9b417",
    "account_type_lookups_id": "57e2ad24-7f2d-4f8e-853c-11a1e3a229ab",
    "is_active": true,
    "companies_id": "{companies record_id}",
    "people_id": "{people record_id}",
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
account_name	string	R	Bank account holder name	max 30 characters, alpha numeric with spaces	J Doe
account_number	integer	R	Bank account number	max 17 digits	10004291601
branch_code	integer	R	Universal branch code of the associated bank	Max 6 digits	051001
bank_lookups_id	String	R	Lookups ID of the associated bank	UUID, Lookups type 'Bank' and category 'BankAccounts'	b6db0d6f-e6fe-4671-8803-f3cb34f9b417
account_type_lookups_id	string	R	Lookups ID of the bank account type	UUID, Lookups type 'Type' and category 'BankAccounts'	57e2ad24-7f2d-4f8e-853c-11a1e3a229ab
is_active	boolean	O	If this bank account is currently active	defaults to false	true
companies_id	String	C - either people id or companies id must be defined	ID of the associated company	UUID	"{companies record_id}"
people_id	String	C - either people id or companies id must be defined	ID of the associated person	UUID	"{people record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Error, account fields are not correct",
    "errors": {
        "account_name": {
            "message": "account name is required",
            "rule": "required"
        }
    }
}

Delete

Path
`DELETE` `/finance/banking/details/delete/{banking_details record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the banking details returned upon create	UUID	"{banking_details record_id}"

Success Response:

{
    "status": true,
    "message": "Record has been removed"
}

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Subscriptions

These API calls allow for manipulating subscription details. All lookup values can be found under: Lookups API

Create

Path
`POST` `/finance/subscriptions/create`

JSON Body:

{
    "companies_id": "{companies record_id}",
    "people_id": "{people record_id}",
    "date_start": "YYYY-MM-DD",
    "date_end": null,
    "billing_day": 31,
    "is_send_finance_documents": true,
    "default_payment_methods_id": "{payment_methods record_id}",
    "document_type_lookups_id": "02347884-d1c9-4726-a30a-0d30e6564ece",
    "document_email_template_lookups_id": "{messages_templates record_id}",
    "document_paid_email_template_lookups_id": "{messages_templates record_id}",
    "document_sms_template_lookups_id": "{messages_templates record_id}",
    "document_paid_sms_template_lookups_id": "{messages_templates record_id}",
    "bank_accounts_id": "{bank_accounts record_id}",
    "cards_id": "{cards record_id}",
    "status_lookups_id": "735702fe-623b-49ea-89ff-90faf5dc4a22",
    "memo": "some memo about the subscription",
    "is_generate_document_on_failure": true,

    "debicheck_client_reference": "CL000001",
    "debicheck_contract_reference": "CT000001",
    "debicheck_debtor_full_name": "J DOE",
    "debicheck_debtor_ultimate_name": null,
    "debicheck_maximum_collection_amount": 150,
    "debicheck_authentication_instrument_lookups_id": "e278a5ba-25e6-40ce-a06d-a1c80c28fbc0",
    "debicheck_debit_value_type_lookups_id": "b2d59897-cd97-4a35-b38e-b6072f94f16d",
    "debicheck_adjustment_category_lookups_id": "3b712f6b-841a-4ba9-b638-1c8e46943061",
    "debicheck_adjustment_rate": 5.00000,
    "debicheck_adjustment_amount": null,
    "debicheck_is_tracking_enabled": true,
    "debicheck_tracking_period": 5,
    "debicheck_is_allow_date_adjustment": true,
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
companies_id	string	C - either people id or companies id must be provided	Company ID linked to the subscription	UUID	"{companies record_id}"
people_id	string	C - either people id or companies id must be provided	People ID linked to the subscription	UUID	"{people record_id}"
date_start	date	R	Starting date of the subscription	"YYYY-MM-DD"	2024-09-01
date_end	date	O	When the subscription is to stop running	"YYYY-MM-DD"	2025-09-01
billing_day	integer	R	Calendar day on which subscription is to run	1 to 31	24
default_payment_methods_id	string	R	Payment method ID associated with this subscription	UUID	"{payment_methods record_id}"
bank_accounts_id	string	C - required with bank related payment methods	ID of bank accounts record to be used	UUID	"{bank_accounts record_id}"
cards_id	string	C - required with card related payment methods	ID of cards record to be used	UUID	"{cards record_id}"
status_lookups_id	string	R	Current status lookups ID of the subscription	UUID, lookups type 'Status' and category 'Subscriptions'	"735702fe-623b-49ea-89ff-90faf5dc4a22"
memo	string	O	Memo to be attached to the subscription	max 2048 characters	"some memo about the subscription"
is_generate_document_on_failure	boolean	O	Generate unpaid finance documents if a transaction is logged as unpaid	ture, false	true
document_type_lookups_id	string	O	Type of document to generate upon payment	Defaults to none, only 'invoices' are allowed for automatic payment methods, manual payment methods allow both 'invoices' and 'sales orders'	"02347884-d1c9-4726-a30a-0d30e6564ece"
is_send_finance_documents	boolean	O	true - send out the finance document, false - only gnerate the finance document	true, false	true
document_email_template_lookups_id	string	C - either email or sms template ID must be provided if send finance documents is true	Email message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_email_template_lookups_id	string	O	Email message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
document_sms_template_lookups_id	string	C - either email or sms template ID must be provided if send finance documents is true	SMS message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_sms_template_lookups_id	string	O	SMS message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
debicheck_client_reference	string	C - Required if DebiCheck payment provider	Debicheck client reference number	May only contain letters and numbers	"CL000001"
debicheck_contract_reference	string	C - Required if DebiCheck payment provider	Debicheck contract reference number	Must be unique per submission and contain only letters and numbers, with a maximum of 14 characters	""CT000001""
debicheck_debtor_full_name	string	C - Required if DebiCheck payment provider	Name of the Debtor as indicated at the bank		"J DOE"
debicheck_debtor_ultimate_name	string	O	Ultimate name of the debtor (if applicable)		"Doe Associates"
debicheck_maximum_collection_amount	decimal	C - Required if DebiCheck payment provider	Maximum collection amount (per instalment) allowed for the mandate in ZAR.	This value may not exceed 1.5 times the instalment amount.	150.25
debicheck_authentication_instrument_lookups_id	string	C - Required if DebiCheck payment provider	Host to Host: takes up to 2 hours to send out but has maximum approval window. Realtime: sent out immediately, 3 minute acceptance window. Authentication will be sent to bank registered cell number. Realtime Delayed: sent out immediately, approval window until 20:30. Realtime Exact: sent out immediately, 3 minute acceptance window. Rejected if debtor cell number does not match the bank registered cell number.	UUID	"e278a5ba-25e6-40ce-a06d-a1c80c28fbc0"
debicheck_debit_value_type_lookups_id	string	C - Required if DebiCheck payment provider	Fixed: collection amount may not change. Variable: collection amount may increase.	UUID	"b2d59897-cd97-4a35-b38e-b6072f94f16d"
debicheck_adjustment_category_lookups_id	string	C - Required if debit value type is not fixed	The interval/category at which adjustments are performed	UUID - If the Adjustment category is set, either an adjustment rate or amount must be specified. Both may not be specified at the same time	"3b712f6b-841a-4ba9-b638-1c8e46943061"
debicheck_adjustment_rate	decimal	C - Required if adjustment category is used	Installment % increase per adjustment interval	Up to 5 decimal places is allowed	5.00000
debicheck_adjustment_amount	decimal	C - Required if adjustment category is used	Instalment amount increase in ZAR value per adjustment interval	Amount in ZAR	15.45
debicheck_is_tracking_enabled	boolean	O	If debtor has given authority to track the account in the event of a collection failure	true/false	true
debicheck_tracking_period"	integer	C - Required if tracking is enabled	Bank can monitor the account for up to 10 days and as soon as money comes in the collection can be re-submitted. Transaction becomes disputable if successfully collected on another day due to tracking.	1 to 10	5
debicheck_is_allow_date_adjustment	boolean	O	Set to true to allow all transactions to be processed irrespective of the collection date	true/false	true

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Please complete the fields below",
    "errors": {
        "billing_day": {
            "message": "billing day is required",
            "rule": "required"
        }
    }
}

View

Path
`GET` `/finance/subscriptions/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription returned upon create	UUID	"{subscriptions record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        "companies_id": "{companies record_id}",
        "people_id": "{people record_id}",
        "date_start": "YYYY-MM-DD",
        "date_end": null,
        "billing_day": 31,
        "is_send_finance_documents": true,
        "default_payment_methods_id": "{payment_methods record_id}",
        "document_type_lookups_id": "02347884-d1c9-4726-a30a-0d30e6564ece",
        "document_email_template_lookups_id": "{messages_templates record_id}",
        "document_paid_email_template_lookups_id": "{messages_templates record_id}",
        "document_sms_template_lookups_id": "{messages_templates record_id}",
        "document_paid_sms_template_lookups_id": "{messages_templates record_id}",
        "bank_accounts_id": "{bank_accounts record_id}",
        "cards_id": "{cards record_id}",
        "status_lookups_id": "735702fe-623b-49ea-89ff-90faf5dc4a22",
        "memo": "some memo about the subscription",
        "is_generate_document_on_failure": true,

        "debicheck_client_reference": "CL000001",
        "debicheck_contract_reference": "CT000001",
        "debicheck_debtor_full_name": "J DOE",
        "debicheck_debtor_ultimate_name": null,
        "debicheck_maximum_collection_amount": 150,
        "debicheck_authentication_instrument_lookups_id": "e278a5ba-25e6-40ce-a06d-a1c80c28fbc0",
        "debicheck_debit_value_type_lookups_id": "b2d59897-cd97-4a35-b38e-b6072f94f16d",
        "debicheck_adjustment_category_lookups_id": "3b712f6b-841a-4ba9-b638-1c8e46943061",
        "debicheck_adjustment_rate": 5.00000,
        "debicheck_adjustment_amount": null,
        "debicheck_is_tracking_enabled": true,
        "debicheck_tracking_period": 5,
        "debicheck_is_allow_date_adjustment": true,
        "debicheck_mandate" : { ... },
    }
}

R/C/O Required/Conditional/Optional

Field	Type	Description	Options	Example
companies_id	string	Company ID linked to the subscription	UUID	"{companies record_id}"
people_id	string	People ID linked to the subscription	UUID	"{people record_id}"
date_start	date	Starting date of the subscription	"YYYY-MM-DD"	2024-09-01
date_end	date	When the subscription is to stop running	"YYYY-MM-DD"	2025-09-01
billing_day	integer	Calendar day on which subscription is to run	1 to 31	24
default_payment_methods_id	string	Payment method ID associated with this subscription	UUID	"{payment_methods record_id}"
bank_accounts_id	string	ID of bank accounts record to be used	UUID	"{bank_accounts record_id}"
cards_id	string	ID of cards record to be used	UUID	"{cards record_id}"
status_lookups_id	string	Current status lookups ID of the subscription	UUID, lookups type 'Status' and category 'Subscriptions'	"735702fe-623b-49ea-89ff-90faf5dc4a22"
memo	string	Memo to be attached to the subscription	max 2048 characters	"some memo about the subscription"
is_generate_document_on_failure	boolean	Generate unpaid finance documents if a transaction is logged as unpaid	ture, false	true
document_type_lookups_id	string	Type of document to generate upon payment	Defaults to none, only 'invoices' are allowed for automatic payment methods, manual payment methods allow both 'invoices' and 'sales orders'	"02347884-d1c9-4726-a30a-0d30e6564ece"
is_send_finance_documents	boolean	true - send out the finance document, false - only gnerate the finance document	true, false	true
document_email_template_lookups_id	string	Email message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_email_template_lookups_id	string	Email message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
document_sms_template_lookups_id	string	SMS message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_sms_template_lookups_id	string	SMS message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
debicheck_client_reference	string	Debicheck client reference number	May only contain letters and numbers	"CL000001"
debicheck_contract_reference	string	Debicheck contract reference number	Must be unique per submission and contain only letters and numbers, with a maximum of 14 characters	""CT000001""
debicheck_debtor_full_name	string	Name of the Debtor as indicated at the bank		"J DOE"
debicheck_debtor_ultimate_name	string	Ultimate name of the debtor (if applicable)		"Doe Associates"
debicheck_maximum_collection_amount	decimal	Maximum collection amount (per instalment) allowed for the mandate in ZAR.	This value may not exceed 1.5 times the instalment amount.	150.25
debicheck_authentication_instrument_lookups_id	string	Host to Host: takes up to 2 hours to send out but has maximum approval window. Realtime: sent out immediately, 3 minute acceptance window. Authentication will be sent to bank registered cell number. Realtime Delayed: sent out immediately, approval window until 20:30. Realtime Exact: sent out immediately, 3 minute acceptance window. Rejected if debtor cell number does not match the bank registered cell number.	UUID	"e278a5ba-25e6-40ce-a06d-a1c80c28fbc0"
debicheck_debit_value_type_lookups_id	string	Fixed: collection amount may not change. Variable: collection amount may increase.	UUID	"b2d59897-cd97-4a35-b38e-b6072f94f16d"
debicheck_adjustment_category_lookups_id	string	The interval/category at which adjustments are performed	UUID - If the Adjustment category is set, either an adjustment rate or amount must be specified. Both may not be specified at the same time	"3b712f6b-841a-4ba9-b638-1c8e46943061"
debicheck_adjustment_rate	decimal	Installment % increase per adjustment interval	Up to 5 decimal places is allowed	5.00000
debicheck_adjustment_amount	decimal	Instalment amount increase in ZAR value per adjustment interval	Amount in ZAR	15.45
debicheck_is_tracking_enabled	boolean	If debtor has given authority to track the account in the event of a collection failure	true/false	true
debicheck_tracking_period	integer	Bank can monitor the account for up to 10 days and as soon as money comes in the collection can be re-submitted. Transaction becomes disputable if successfully collected on another day due to tracking.	1 to 10	5
debicheck_is_allow_date_adjustment	boolean	Set to true to allow all transactions to be processed irrespective of the collection date	true/false	true
debicheck_mandate	json	All DebiCheck details as submitted to the bank		Mostly contains the same details as submit details as well as some running logs of debicheck events

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Edit

Path
`POST` `/finance/subscriptions/edit/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription returned upon create	UUID	"{subscriptions record_id}"

JSON Body:

{
    "companies_id": "{companies record_id}",
    "people_id": "{people record_id}",
    "date_start": "YYYY-MM-DD",
    "date_end": null,
    "billing_day": 31,
    "is_send_finance_documents": true,
    "default_payment_methods_id": "{payment_methods record_id}",
    "document_type_lookups_id": "02347884-d1c9-4726-a30a-0d30e6564ece",
    "document_email_template_lookups_id": "{messages_templates record_id}",
    "document_paid_email_template_lookups_id": "{messages_templates record_id}",
    "document_sms_template_lookups_id": "{messages_templates record_id}",
    "document_paid_sms_template_lookups_id": "{messages_templates record_id}",
    "bank_accounts_id": "{bank_accounts record_id}",
    "cards_id": "{cards record_id}",
    "status_lookups_id": "735702fe-623b-49ea-89ff-90faf5dc4a22",
    "memo": "some memo about the subscription",
    "is_generate_document_on_failure": true,

    "debicheck_client_reference": "CL000001",
    "debicheck_contract_reference": "CT000001",
    "debicheck_debtor_full_name": "J DOE",
    "debicheck_debtor_ultimate_name": null,
    "debicheck_maximum_collection_amount": 150,
    "debicheck_authentication_instrument_lookups_id": "e278a5ba-25e6-40ce-a06d-a1c80c28fbc0",
    "debicheck_debit_value_type_lookups_id": "b2d59897-cd97-4a35-b38e-b6072f94f16d",
    "debicheck_adjustment_category_lookups_id": "3b712f6b-841a-4ba9-b638-1c8e46943061",
    "debicheck_adjustment_rate": 5.00000,
    "debicheck_adjustment_amount": null,
    "debicheck_is_tracking_enabled": true,
    "debicheck_tracking_period": 5,
    "debicheck_is_allow_date_adjustment": true,
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
companies_id	string	C - either people id or companies id must be provided	Company ID linked to the subscription	UUID	"{companies record_id}"
people_id	string	C - either people id or companies id must be provided	People ID linked to the subscription	UUID	"{people record_id}"
date_start	date	R	Starting date of the subscription	"YYYY-MM-DD"	2024-09-01
date_end	date	O	When the subscription is to stop running	"YYYY-MM-DD"	2025-09-01
billing_day	integer	R	Calendar day on which subscription is to run	1 to 31	24
default_payment_methods_id	string	R	Payment method ID associated with this subscription	UUID	"{payment_methods record_id}"
bank_accounts_id	string	C - required with bank related payment methods	ID of bank accounts record to be used	UUID	"{bank_accounts record_id}"
cards_id	string	C - required with card related payment methods	ID of cards record to be used	UUID	"{cards record_id}"
status_lookups_id	string	R	Current status lookups ID of the subscription	UUID, lookups type 'Status' and category 'Subscriptions'	"735702fe-623b-49ea-89ff-90faf5dc4a22"
memo	string	O	Memo to be attached to the subscription	max 2048 characters	"some memo about the subscription"
is_generate_document_on_failure	boolean	O	Generate unpaid finance documents if a transaction is logged as unpaid	ture, false	true
document_type_lookups_id	string	O	Type of document to generate upon payment	Defaults to none, only 'invoices' are allowed for automatic payment methods, manual payment methods allow both 'invoices' and 'sales orders'	"02347884-d1c9-4726-a30a-0d30e6564ece"
is_send_finance_documents	boolean	O	true - send out the finance document, false - only gnerate the finance document	true, false	true
document_email_template_lookups_id	string	C - either email or sms template ID must be provided if send finance documents is true	Email message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_email_template_lookups_id	string	O	Email message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
document_sms_template_lookups_id	string	C - either email or sms template ID must be provided if send finance documents is true	SMS message template ID to be used upon payment	UUID	"{messages_templates record_id}"
document_paid_sms_template_lookups_id	string	O	SMS message template ID to be used when the payment reflects as 'paid'	UUID	"{messages_templates record_id}"
debicheck_client_reference	string	C - Required if DebiCheck payment provider	Debicheck client reference number	May only contain letters and numbers	"CL000001"
debicheck_contract_reference	string	C - Required if DebiCheck payment provider	Debicheck contract reference number	Must be unique per submission and contain only letters and numbers, with a maximum of 14 characters	""CT000001""
debicheck_debtor_full_name	string	C - Required if DebiCheck payment provider	Name of the Debtor as indicated at the bank		"J DOE"
debicheck_debtor_ultimate_name	string	O	Ultimate name of the debtor (if applicable)		"Doe Associates"
debicheck_maximum_collection_amount	decimal	C - Required if DebiCheck payment provider	Maximum collection amount (per instalment) allowed for the mandate in ZAR.	This value may not exceed 1.5 times the instalment amount.	150.25
debicheck_authentication_instrument_lookups_id	string	C - Required if DebiCheck payment provider	Host to Host: takes up to 2 hours to send out but has maximum approval window. Realtime: sent out immediately, 3 minute acceptance window. Authentication will be sent to bank registered cell number. Realtime Delayed: sent out immediately, approval window until 20:30. Realtime Exact: sent out immediately, 3 minute acceptance window. Rejected if debtor cell number does not match the bank registered cell number.	UUID	"e278a5ba-25e6-40ce-a06d-a1c80c28fbc0"
debicheck_debit_value_type_lookups_id	string	C - Required if DebiCheck payment provider	Fixed: collection amount may not change. Variable: collection amount may increase.	UUID	"b2d59897-cd97-4a35-b38e-b6072f94f16d"
debicheck_adjustment_category_lookups_id	string	C - Required if debit value type is not fixed	The interval/category at which adjustments are performed	UUID - If the Adjustment category is set, either an adjustment rate or amount must be specified. Both may not be specified at the same time	"3b712f6b-841a-4ba9-b638-1c8e46943061"
debicheck_adjustment_rate	decimal	C - Required if adjustment category is used	Installment % increase per adjustment interval	Up to 5 decimal places is allowed	5.00000
debicheck_adjustment_amount	decimal	C - Required if adjustment category is used	Instalment amount increase in ZAR value per adjustment interval	Amount in ZAR	15.45
debicheck_is_tracking_enabled	boolean	O	If debtor has given authority to track the account in the event of a collection failure	true/false	true
debicheck_tracking_period"	integer	C - Required if tracking is enabled	Bank can monitor the account for up to 10 days and as soon as money comes in the collection can be re-submitted. Transaction becomes disputable if successfully collected on another day due to tracking.	1 to 10	5
debicheck_is_allow_date_adjustment	boolean	O	Set to true to allow all transactions to be processed irrespective of the collection date	true/false	true

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Please complete the fields below",
    "errors": {
        "billing_day": {
            "message": "billing day is required",
            "rule": "required"
        }
    }
}

Delete

Path
`DELETE` `/finance/subscriptions/delete/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription returned upon create	UUID	"{subscriptions record_id}"

Success Response:

{
    "status": true,
    "message": "Record has been removed"
}

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Subscriptions Products

These API calls allow for manipulating subscription product details. All lookup values can be found under: Lookups API

Create

Path
`POST` `/finance/subscriptions/products/create`

JSON Body:

{
    "people_id": "{paying for people record_id|null}",
    "subscriptions_id": "{subscriptions record_id}",
    "products_id": "{products record_id}",
    "amount": "100.25",
    "quantity": 1,
    "agents_id": "{agents records_id}",
    "projects_id": "{projects records_id}",
    "branches_id": "{branches records_id}",
    "is_active": true,
    "once_off_start": "{Once off product start date YYYY-MM-DD}"
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
people_id	string	O	Person being paid for on behalf of someone else. Leave null if paying for self	UUID	"{people record_id}"
subscriptions_id	string	R	Subscription ID to link this subscription product to	UUID	"{subscriptions record_id}"
products_id	string	R	Product ID being paid for	UUID	"{products record_id}"
amount	decimal	R	Amount being paid, in base currency e.g. 100.25 ZAR	greater than 0	"100.25"
quantity	integer	R	Amount of products being paid for, amount will be multiplied by the quantity for the total amount to be paid on the subscription	Greater than 0	1
agents_id	string	O	Agent ID related to the sale	UUID	"{agents records_id}"
projects_id	string	O	Project ID related to the sale	UUID	"{projects records_id}"
branches_id	string	O	Branches ID related to the sale	UUID	"{branches records_id}
is_active	boolean	O	If this subscription product is considered to be active	defaults to false	true
once_off_start	date	C - required if the products ID belongs to a once off product	When the once off product is to be billed	"YYYY-MM-DD"	"2024-09-01"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Please complete the fields below",
    "errors": {
        "subscriptions_id": {
            "message": "subscriptions id is required",
            "rule": "required"
        }
    }
}

View

Path
`GET` `/finance/subscriptions/products/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription product returned upon create	UUID	"{subscriptions_products record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        "people_id": "{paying for people record_id|null}",
        "subscriptions_id": "{subscriptions record_id}",
        "products_id": "{products record_id}",
        "amount": "100.25",
        "quantity": 1,
        "agents_id": "{agents records_id}",
        "projects_id": "{projects records_id}",
        "branches_id": "{branches records_id}",
        "is_active": true,
        "once_off_start": "{Once off product start date YYYY-MM-DD}"
    }
}

Field	Type	Description	Options	Example
people_id	string	Person being paid for on behalf of someone else. Leave null if paying for self	UUID	"{people record_id}"
subscriptions_id	string	Subscription ID to link this subscription product to	UUID	"{subscriptions record_id}"
products_id	string	Product ID being paid for	UUID	"{products record_id}"
amount	decimal	Amount being paid, in base currency e.g. 100.25 ZAR	greater than 0	"100.25"
quantity	integer	Amount of products being paid for, amount will be multiplied by the quantity for the total amount to be paid on the subscription	Greater than 0	1
agents_id	string	Agent ID related to the sale	UUID	"{agents records_id}"
projects_id	string	Project ID related to the sale	UUID	"{projects records_id}"
branches_id	string	Branches ID related to the sale	UUID	"{branches records_id}
is_active	boolean	If this subscription product is considered to be active	defaults to false	true
once_off_start	date	When the once off product is to be billed	"YYYY-MM-DD"	"2024-09-01"

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Edit

Path
`POST` `/finance/subscriptions/products/edit/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription product returned upon create	UUID	"{subscriptions_products record_id}"

JSON Body:

{
    "people_id": "{paying for people record_id|null}",
    "subscriptions_id": "{subscriptions record_id}",
    "products_id": "{products record_id}",
    "amount": "100.25",
    "quantity": 1,
    "agents_id": "{agents records_id}",
    "projects_id": "{projects records_id}",
    "branches_id": "{branches records_id}",
    "is_active": true,
    "once_off_start": "{Once off product start date YYYY-MM-DD}"
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
people_id	string	O	Person being paid for on behalf of someone else. Leave null if paying for self	UUID	"{people record_id}"
subscriptions_id	string	R	Subscription ID to link this subscription product to	UUID	"{subscriptions record_id}"
products_id	string	R	Product ID being paid for	UUID	"{products record_id}"
amount	decimal	R	Amount being paid, in base currency e.g. 100.25 ZAR	greater than 0	"100.25"
quantity	integer	R	Amount of products being paid for, amount will be multiplied by the quantity for the total amount to be paid on the subscription	Greater than 0	1
agents_id	string	O	Agent ID related to the sale	UUID	"{agents records_id}"
projects_id	string	O	Project ID related to the sale	UUID	"{projects records_id}"
branches_id	string	O	Branches ID related to the sale	UUID	"{branches records_id}
is_active	boolean	O	If this subscription product is considered to be active	defaults to false	true
once_off_start	date	C - required if the products ID belongs to a once off product	When the once off product is to be billed	"YYYY-MM-DD"	"2024-09-01"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Please complete the fields below",
    "errors": {
        "subscriptions_id": {
            "message": "subscriptions id is required",
            "rule": "required"
        }
    }
}

Delete

Path
`DELETE` `/finance/subscriptions/products/delete/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the subscription product returned upon create	UUID	"{subscriptions_products record_id}"

Success Response:

{
    "status": true,
    "message": "Record has been removed"
}

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Batches

These API calls allow for manipulating batches details. All lookup values can be found under: Lookups API

Create

Path
`POST` `/finance/batches/create`

JSON Body:

{
    "accounts_reference": "TST230824",
    "date_start": "YYYY-MM-DD",
    "date_end": "YYYY-MM-DD",
    "payment_methods_id": "{payment_methods record_id}"
}

R/C/O Required/Conditional/Optional

Field	Type	R/C/O	Description	Options	Example
accounts_reference	String	R	Reference to be used on statements	Max 8 characters	"TST230824"
date_start	date	R	Starting date of the batch	"YYYY-MM-DD", must be 1 day after the last batch end date	"2024-09-01"
date_end	date	R	End date of the batch	"YYYY-MM-DD", must be within the same month of the starting date	"2024-09-15"
payment_methods_id	string	R	Payment method to be used for generating this batch	UUID	"{payment_methods record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        ...
    }
}

Error Response:

{
    "status": false,
    "error": "Please complete the fields below",
    "errors": {
        "date_start": {
            "message": "date start is required",
            "rule": "required"
        }
    }
}

View

Path
`GET` `/finance/batches/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the batch returned upon create	UUID	"{batches record_id}"

Success Response:

{
    "status": true,
    "record": {
        "id": "{unique record_id}",
        "accounts_reference": "TST230824",
        "date_start": "YYYY-MM-DD",
        "date_end": "YYYY-MM-DD",
        "payment_methods_id": "{payment_methods record_id}",
        "status_lookups_id": "b024d7ae-b3cf-4edc-ad35-6bc455b1937a"
    }
}

Field	Type	Description	Options	Example
accounts_reference	String	Reference to be used on statements	Max 8 characters	"TST230824"
date_start	date	Starting date of the batch	"YYYY-MM-DD", must be 1 day after the last batch end date	"2024-09-01"
date_end	date	End date of the batch	"YYYY-MM-DD", must be within the same month of the starting date	"2024-09-15"
payment_methods_id	string	Payment method to be used for generating this batch	UUID	"{payment_methods record_id}"
status_lookups_id	string	Status lookups ID for the batch	UUID	"b024d7ae-b3cf-4edc-ad35-6bc455b1937a"

Error Response:

{
    "status": false,
    "error": "Record ID could not be found"
}

Delete

Path
`DELETE` `/finance/batches/delete/{record_id}`

Query Parameter:

Field	Type	Description	Options	Example
record_id	String	Unique ID of the batch returned upon create	UUID	"{batches record_id}"

Success Response:

{
    "status": true,
    "message": "Record scheduled for removal"
}

Error Response:

{
    "status": false,
    "error": "Only created, verified, verification failed or rejected batches may be deleted"
}

Forms

General Forms API documentation

Lists

General Lists API documentation