Financial Transactions Report

GET /v2/finplus/debtmanagement/financialtransactions

This report provides a comprehensive view of transactions, offering the ability to group data by family/parent while also allowing for further breakdowns per learner using the per_learner parameter. When per_learner is specified, the family/parent object is extended to include learner-specific transaction details. The API supports flexible filtering options, such as date ranges, category IDs, debtor codes, learners, and accountable persons.

The possible transaction types and transaction categories can be looked up using the Get Transaction Type(s) and Get Transaction Category(s) API calls.

Pagination

The response data includes a meta object that contains pagination-specific metadata. You can use the following query parameters to control pagination:

• limit: This parameter allows you to override the default limit of records returned, up to the max_allowed_limit specified in the response's meta object.

• cursor: If the meta object contains a next_cursor field, it indicates that more records are available. To fetch the next set of records, include the cursor parameter in your request with the value of next_cursor. If the next_cursor field is not present, it means there are no more records to retrieve.

• reverse_order: This parameter can be used to reverse the order in which the data is returned, useful for fetching the latest records first.

Request Headers

Name	Type	Description
HTTP-X-USERNAME*	String	As provided by d6
HTTP-X-PASSWORD*	String	As provided by d6
HTTP-X-SCHOOLID*	Integer	The unique identifier of the school for which the data is being queried.

Query Parameters

Name	Type	Description
all_accounts	Boolean	Whether to include all accounts
per_learner	Boolean	Whether to include a break-down of transactions per learner
debtor_code	Integer	To filter on a specific Debtor Code
learner_id	Integer	To filter on a specific Learner ID
accountable_person_id	Integer	To filter on a specific Accountable Person ID
category_id	Integer	To filter on a specific Category ID
start_date	String	The start date for filtering transactions (format: YYYY-MM-DD)
end_date	String	The end date for filtering transactions (format: YYYY-MM-DD). The start_date is required when specifying an end date.
cursor	String	To retrieve the next group of items (if any)
limit	Integer	To override the default limit of records returned (up to the max_allowed_limit provided in the response metadata).
reverse_order	Boolean	To reverse the order the data is returned in

Response Examples

Success: Per family and parent (200 OK)

Status: 200 OK

{
    "data": [
        {
            "debtor_code": "1001",
            "accountable_person_id": "40",
            "transactions": [
                {
                    "category_id": null,
                    "category_name": null,
                    "transaction_date": "2024-04-01",
                    "transaction_type_id": null,
                    "transaction_type_name": null,
                    "transaction_reference": null,
                    "transaction_description": "Opening balance",
                    "part_of_base_fee": null,
                    "debit_amount": "17200.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "17200.00"
                },
                {
                    "category_id": "1",
                    "category_name": "School Fees",
                    "transaction_date": "2024-04-01",
                    "transaction_type_id": "14",
                    "transaction_type_name": "Debtor Invoice",
                    "transaction_reference": "663",
                    "transaction_description": "Invoice - School Fees Jordan Smith - 00002 Apr2024",
                    "part_of_base_fee": "1",
                    "debit_amount": "2000.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "19200.00"
                },
                {
                    "category_id": "6",
                    "category_name": "Hostel Fees",
                    "transaction_date": "2024-04-01",
                    "transaction_type_id": "14",
                    "transaction_type_name": "Debtor Invoice",
                    "transaction_reference": "872",
                    "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00002 Apr2024",
                    "part_of_base_fee": "0",
                    "debit_amount": "1000.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "20200.00"
                },
                {
                    "category_id": "1",
                    "category_name": "School Fees",
                    "transaction_date": "2024-05-01",
                    "transaction_type_id": "14",
                    "transaction_type_name": "Debtor Invoice",
                    "transaction_reference": "682",
                    "transaction_description": "Invoice - School Fees Jordan Smith - 00002 May2024",
                    "part_of_base_fee": "1",
                    "debit_amount": "2000.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "22700.00"
                },
                {
                    "category_id": "6",
                    "category_name": "Hostel Fees",
                    "transaction_date": "2024-05-01",
                    "transaction_type_id": "14",
                    "transaction_type_name": "Debtor Invoice",
                    "transaction_reference": "891",
                    "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00002 May2024",
                    "part_of_base_fee": "0",
                    "debit_amount": "1000.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "23700.00"
                }
            ]
        },
        {
            "debtor_code": "1002",
            "accountable_person_id": "3",
            "transactions": [
                {
                    "category_id": null,
                    "category_name": null,
                    "transaction_date": "2024-04-01",
                    "transaction_type_id": null,
                    "transaction_type_name": null,
                    "transaction_reference": null,
                    "transaction_description": "Opening balance",
                    "part_of_base_fee": null,
                    "debit_amount": "21700.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "21700.00"
                },
                {
                    "category_id": "1",
                    "category_name": "School Fees",
                    "transaction_date": "2024-04-01",
                    "transaction_type_id": "14",
                    "transaction_type_name": "Debtor Invoice",
                    "transaction_reference": "662",
                    "transaction_description": "Invoice - School Fees Nic Webster - 00001 Apr2024",
                    "part_of_base_fee": "1",
                    "debit_amount": "2000.00",
                    "credit_amount": "0.00",
                    "accumulated_balance": "23700.00"
                }
            ]
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }
}

Success: Per learner (200 OK)

Status: 200 OK

{
    "data": [
        {
            "debtor_code": "1001",
            "accountable_person_id": "40",
            "learners": [
                {
                    "learner_id": "1",
                    "learner_first_name": "Jordan",
                    "learner_last_name": "Smith",
                    "transactions": [
                        {
                            "category_id": null,
                            "category_name": null,
                            "transaction_date": "2024-04-01",
                            "transaction_type_id": null,
                            "transaction_type_name": null,
                            "transaction_reference": null,
                            "transaction_description": "Opening balance",
                            "part_of_base_fee": null,
                            "debit_amount": "21700.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "21700.00"
                        },
                        {
                            "category_id": "1",
                            "category_name": "School Fees",
                            "transaction_date": "2024-04-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "662",
                            "transaction_description": "Invoice - School Fees Jordan Smith - 00001 Apr2024",
                            "part_of_base_fee": "1",
                            "debit_amount": "2000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "23700.00"
                        },
                        {
                            "category_id": "6",
                            "category_name": "Hostel Fees",
                            "transaction_date": "2024-04-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "871",
                            "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00001 Apr2024",
                            "part_of_base_fee": "0",
                            "debit_amount": "1000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "24700.00"
                        },
                        {
                            "category_id": "1",
                            "category_name": "School Fees",
                            "transaction_date": "2024-05-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "681",
                            "transaction_description": "Invoice - School Fees Jordan Smith - 00001 May2024",
                            "part_of_base_fee": "1",
                            "debit_amount": "2000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "27200.00"
                        },
                        {
                            "category_id": "6",
                            "category_name": "Hostel Fees",
                            "transaction_date": "2024-05-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "890",
                            "transaction_description": "Invoice - Hostel Fees Jordan Smith - 00001 May2024",
                            "part_of_base_fee": "0",
                            "debit_amount": "1000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "28200.00"
                        }
                    ]
                }
            ]
        },
        {
            "debtor_code": "1002",
            "accountable_person_id": "3",
            "learners": [
                {
                    "learner_id": "3",
                    "learner_first_name": "Nick",
                    "learner_last_name": "Webster",
                    "transactions": [
                        {
                            "category_id": null,
                            "category_name": null,
                            "transaction_date": "2024-04-01",
                            "transaction_type_id": null,
                            "transaction_type_name": null,
                            "transaction_reference": null,
                            "transaction_description": "Opening balance",
                            "part_of_base_fee": null,
                            "debit_amount": "17200.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "17200.00"
                        },
                        {
                            "category_id": "1",
                            "category_name": "School Fees",
                            "transaction_date": "2024-04-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "663",
                            "transaction_description": "Invoice - School Fees Nick Webster - 00002 Apr2024",
                            "part_of_base_fee": "1",
                            "debit_amount": "2000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "19200.00"
                        },
                        {
                            "category_id": "1",
                            "category_name": "School Fees",
                            "transaction_date": "2024-05-01",
                            "transaction_type_id": "14",
                            "transaction_type_name": "Debtor Invoice",
                            "transaction_reference": "682",
                            "transaction_description": "Invoice - School Fees Nick Webster - 00002 May2024",
                            "part_of_base_fee": "1",
                            "debit_amount": "2000.00",
                            "credit_amount": "0.00",
                            "accumulated_balance": "22700.00"
                        }
                    ]
                }
            ]
        }
    ],
    "meta": {
        "limit": 10,
        "max_allowed_limit": 50,
        "cursor": "eyJpZCI6MjU0NiwiX2JhY2t3YXJkIjpmYWxzZX0"
    }

}

Validation Error (400 Bad Request)

Description: When validation failed for one or more fields

Status: 400 Bad Request

{
    "success": false,
    "message": "Validation Failed",
    "validation_errors": {
        "accountable_person_id": "The Accountable person id must be integer",
        "start_date": "The Start date is not valid date format. Expected format is 'Y-m-d'."
    }
}

Code Samples

PHP

<?php

// API Credentials
$api_username = 'your_username';
$api_password = 'your_password';
$school_id = 'your_school_id';

// Base API endpoint
$base_url = 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/financialtransactions';

// Query parameters (customize as needed)
$query_params = [
    'all_accounts'          => 1, // To include all accounts (including left learners and zero-balance accounts)
    'per_learner'           => 1, // To group by learner
    'category_id'           => '',
    'debtor_code'           => '1001',
    'learner_id'            => '',
    'accountable_person_id' => '',
    'start_date'            => '',
    'end_date'              => '',
    // Pagination controls
    'limit'                 => 50,
    'reverse_order'         => 1,
    'cursor'                => 'eyJ2YWx1ZSI6IjcxIiwiX2JhY2t3YXJkIjp0cnVlfQ'
];

// Build the full request URL
$url = $base_url . '?' . http_build_query(array_filter($query_params));

// Initialize cURL
$curl = curl_init();

// Set cURL options
curl_setopt_array($curl, [
    CURLOPT_URL            => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,  // Prevents hanging requests
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "HTTP-X-USERNAME: $api_username",
        "HTTP-X-PASSWORD: $api_password",
        "HTTP-X-SCHOOLID: $school_id",
        "Accept: application/json"
    ],
]);

// Execute request
$response = curl_exec($curl);

// Check for errors
if (curl_errno($curl)) {
    throw new Exception('cURL Error: ' . curl_error($curl));
}

// Close cURL
curl_close($curl);

// Output the response
header('Content-Type: application/json');
echo $response;

cURL

curl --request GET 'https://integrate.d6plus.co.za/api/v2/finplus/debtmanagement/financialtransactions?per_learner=1&all_accounts=1' \
     --header 'HTTP-X-USERNAME: your_username' \
     --header 'HTTP-X-PASSWORD: your_password' \
     --header 'HTTP-X-SCHOOLID: the_school_id'