Using Ledgers
Overview
When you create a card product, Highnote creates ledgers for your financial accounts based on the card product vertical.
Ledgers have a LedgerName, description, and a normalBalance that is determined by the ledger category.
For example, a CASH ledger has a category of ASSETS and a normalBalance of DEBIT.
For a full list of ledger names, see LedgerName in the API Reference.
A ledger is made up of the following foundational concepts:
| Concept | Definition |
|---|---|
| Normal balance | The expected balance of a ledger |
| Financial event | Any event that impacts the balance of a financial account |
| Ledger entry | A record of a financial event, resulting in a change in a financial account's balance |
| Account balance | The current balance of a ledger, reflecting all financial events |
Account balances show all financial events for a given ledger. When an individual financial event occurs, it results in a ledger entry. Each ledger entry reflects the change in account balance. Refer to the following example for a breakdown of this process:
- Funds are transferred from an external bank account into a Highnote financial account.
- The funds transfer results in a ledger entry in the financial account's
CASHledger, reflecting the account balance. - When transactions are made using a payment card, the
AUTHORIZATIONledger reflects pending authorizations and holds on the account. - After a transaction clears, the
AVAILABLE_CASHledger reflects the money available to spend in a financial account.
Account balances
Account balances reflect the current balance of a ledger based on financial events, based on the following:
- Represented by a single positive number
- The direction of the balance, either
DEBITorCREDIT - The account's normal balance
If the account balance and normal balance agree, the balance is interpreted as positive. If the balance of a ledger and the normal balance disagree, the balance is interpreted as negative. The following example using a CASH ledger outlines how account balances and normal balances are reflected. CASH ledgers have a normal balance of DEBIT:
- If a
CASHledger has a $1000 debit balance, the balance is positive. This means the account balance is $1000 because the normal balance for aCASHledger is debit. - If a
CASHledger has a $1000 credit balance, the balance is negative. In this case, the account balance and normal balance disagree, meaning there is -$1000 in the account.
Highnote's ledger system is based on account principles, with cash and activity being represented independently. This means that account balances provide a snapshot for a point in time, rather than reflecting pending or available balances. Pending or available balances can be calculated across ledgers if desired.
Use cases
Ledgers and financial events can be used to create account statements, display account balances, and show money movement statuses. Refer to the following table for the objects used to create each use case:
| Use case | Objects |
|---|---|
| Transaction feed without account balance | FinancialAccountActivity |
| Account statement with balance | FinancialAccountActivity for pending and Ledger for posted |
| Money movement status | FinancialAccountActivity |
Find all ledgers for your organization
Use the following query to list all ledgers for your organization. The query returns each ledger's normalBalance, creditBalance, and debitBalance:
FindOrganization
Query
query FindOrganization($id: ID!) {
node(id: $id) {
... on Organization {
accounts {
edges {
node {
id
ledgers {
id
name
normalBalance
asOf
debitBalance {
value
currencyCode
}
creditBalance {
value
currencyCode
}
}
}
}
}
}
}
}
Variables
{
"id": "ORGANIZATION_ID"
}
Result
{
"data": {
"node": {
"id": "ORGANIZATION_ID",
"accounts": {
"edges": [
{
"id": "ACCOUNT_ID",
"ledgers": [
{
"id": "LEDGER_ID",
"name": "CASH",
"normalBalance": "DEBIT",
"asOf": "2021-08-06T16:12:39.735Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "AVAILABLE_CASH",
"normalBalance": "CREDIT",
"asOf": "2021-08-06T16:12:39.735Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "UNCOLLECTED_FUNDS",
"normalBalance": "DEBIT",
"asOf": "2021-08-06T16:25:21.280Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "NETWORK_PAYABLE",
"normalBalance": "CREDIT",
"asOf": "2021-08-06T16:25:21.280Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "NETWORK_RECEIVABLE",
"normalBalance": "DEBIT",
"asOf": "2021-08-06T16:25:21.280Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "INTERCHANGE_REVENUE",
"normalBalance": "CREDIT",
"asOf": "2021-08-06T16:25:21.280Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
},
{
"id": "LEDGER_ID",
"name": "NETWORK_EXPENSE",
"normalBalance": "CREDIT",
"asOf": "2021-08-06T16:25:21.280Z",
"debitBalance": {
"value": 0,
"currencyCode": "USD"
},
"creditBalance": {
"value": 0,
"currencyCode": "USD"
}
}
]
}
]
}
}
}
}
Operation for ledger entries
Use the following query to find a ledger and its associated ledger entries:
FindLedger
Query
query FindLedger($id: ID!) {
node(id: $id) {
... on Ledger {
id
name
ledgerEntries(first: 1) {
edges {
node {
__typename
id
amount {
value
}
journalEntry {
credits {
amount {
value
}
}
debits {
amount {
value
}
}
}
}
}
}
}
}
}
Variables
{
"id": "LEDGER_ID"
}
Result
{
"data": {
"node": {
"id": "LEDGER_ID",
"name": "AVAILABLE_CASH",
"ledgerEntries": {
"edges": [
{
"node": {
"__typename": "CreditLedgerEntry",
"id": "LEDGER_ID",
"amount": {
"value": 1000
},
"journalEntry": {
"credits": [
{
"amount": {
"value": 1000
}
}
],
"debits": [
{
"amount": {
"value": 1000
}
}
]
}
}
}
]
}
}
}
}