Data modelsBanking

Direct debits

The standing charges against an account — who charges, how much, how often

View as Markdown

Where it lives: at direct_debits in the Financial Position, and on its own from the direct debits endpoint.

Direct debits are the fastest read on somebody’s fixed commitments. Rent, utilities, insurance, subscriptions, loan instalments at other institutions — each with the creditor that charges it and the history of what was actually taken. It is the same information you could mine out of a year of transactions, already grouped by who is charging.

A SEPA direct debit authorization, with its recent charges and supporting documents.
idstringRequiredformat: "object-id"
Product ID for the current execution. It may change between executions.
product"direct_debit"Required
sub_family"direct_debit:sepa"Required
fetch_datestringRequiredformat: "datetime"
Date this product was fetched.
accountobjectRequired
The customer's account the debit is charged to.
statusenumRequired
Status of the direct debit authorization.
Allowed values:
customer_segmentenumRequired
Whether the account belongs to a personal or a business relationship.
beneficiaryobjectRequired
Who collects the debit.
payerobjectRequired
Who pays the debit.
transactionslist of objectsRequired
Recent charges of this debit, as reported by the bank.
debit_referencestringOptional

Mandate/debit reference, as the bank reports it.

attachmentslist of objectsOptionalDefaults to []

Supporting documents of the debit — e.g. the receipt of the most recent charge. Each entry's id downloads the file through the execution's attachments endpoint.

Status

Allowed values:

A cancelled or returned mandate is worth as much as an active one: a returned charge is an unpaid commitment, which is exactly what an affordability check is looking for.

The charges themselves

One charge of the direct debit: when it was issued and paid, and for how much.

statusenumRequired
Status of this charge.
issue_datestringOptionalformat: "datetime"
Date the charge was issued.
payment_datestringOptionalformat: "datetime"
Date the charge was paid.
conceptstringOptional
Concept of the charge, as the bank reports it.
amountobjectOptional
Amount of the charge.

beneficiary is the creditor. Grouping mandates by it gives you a monthly commitment profile — housing, utilities, insurance, credit — without categorising a single transaction.