Account Ledger

The ledger is the immutable list of transactions for and against their respective positions in an account. This allows you to book various fees, payments, adjustments, etc. against an exact invoice or claim. It is possible to book solely against the account itself, but if your use case is to be able to generate clear statements or allocate payments in a targeted manner, we recommend using more exact ledger entries.

Account Ledger Entries

There are 5 types of Account Ledger Entries:

  • Invoice Ledger Entry
  • Fee Ledger Entry
  • Payment Ledger Entry
  • Adjustment Ledger Entry
  • Chargeback Ledger Entry

Invoice Ledger Entry

The Invoice Ledger Entry represents an invoice that the debtor should pay, and any Invoice Ledger Entry is automatically mapped as a Claim inside the system, for example:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE",
    "invoiceDetails": {
        "amount": 10000,
        "dueDate": "2021-08-08",
        "meta": {
            "internalReference": 100
        }
    },
    "context": {}
}]

Note: The context for an Invoice Ledger Entry can contain the productReference in order to explicitly link it to a particular product.

Invoices will become claims

A new claim will automatically be created from the new Invoice Ledger Entry with the reference INVOICE_LEDGER_ENTRY_REFERENCE:

{
  "accountId": "ACCOUNT_REFERENCE",
  "amount": 100000,
  "currency": "EUR",
  "debtor": {
    "contactInformation": {
      "additionalAddresses": [],
      "country": "DE"
    },
    "externalDebtorRef": "EXTERNAL_DEBTOR_REFERENCE",
    "firstName": "FIRST_NAME",
    "lastName": "LAST_NAME"
  },
  "dueDate": "2021-08-08",
  "externalClaimRef": "INVOICE_LEDGER_ENTRY_REFERENCE-2021-08-08",
  "externalDueDate": "2021-08-08",
  "fees": [],
  "meta": {
    "__invoiceLedgerEntry__": {
      "context": {},
      "invoiceDetails": {
        "amount": 100000,
        "createdAt": 1625581534864,
        "dueDate": "2021-08-08"
      },
      "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE",
      "type": "invoice"
    },
    "key1": "value1"
  },
  "totalFees": 0
}

Notes

  • The debtor, currency, and meta fields are extracted from the Account (based on the accountReference)
  • The externalClaimRef is computed based on the ledgerEntryReference and the dueDate of the Invoice Ledger Entry
  • The dueDate and originalDueDate are based on the dueDate from the Invoice Ledger Entry

Fee Ledger Entries

You can add Fees through one or more Fee Ledger Entries. There are two types of fees: an Account Level Fee, and an Invoice Level Fee.

Account Level Fee

To create an Account Level Fee, simply do not set any ledgerEntryReference as part of the context, for example:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "ACCOUNT_FEE_LEDGER_ENTRY_REFERENCE",
    "feeDetails": {
      "amount": 7500
    },
    "context": {}
}]

Because they are not attached to any claim, an Account Level Fee affects the total amount of the Account, but is not reflected in the Claims from that Account.

Invoice Level Fee

To create an Invoice Level Fee the only requirement is to set a ledgerEntryReference as part of the context, for example:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "INVOICE_FEE_LEDGER_ENTRY_REFERENCE",
    "feeDetails": {
      "amount": 7500
    },
    "context": {
      "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE"
    }
}]

Any Fee Ledger Entry is automatically converted as a Fee in the Claim. Using the example from above, the claim created would look like this:

{
  "accountId": "ACCOUNT_REFERENCE",
  "amount": 100000,
  "currency": "EUR",
  "debtor": {
    "contactInformation": {
      "additionalAddresses": [],
      "country": "DE"
    },
    "externalDebtorRef": "EXTERNAL_DEBTOR_REFERENCE",
    "firstName": "FIRST_NAME",
    "lastName": "LAST_NAME"
  },
  "dueDate": "2021-08-08",
  "externalClaimRef": "INVOICE_LEDGER_ENTRY_REFERENCE-2021-08-08",
  "externalDueDate": "2021-08-08",
  "fees": [{
    "name": "INVOICE_LEDGER_ENTRY_REFERENCE",
    "amount": 7500
  }],
  "meta": {
    "__invoiceLedgerEntry__": {
      "context": {},
      "invoiceDetails": {
        "amount": 100000,
        "createdAt": 1625581534864,
        "dueDate": "2021-08-08"
      },
      "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE",
      "type": "invoice"
    },
    "key1": "value1"
  },
  "totalFees": 7500
}

This will be reflected in the Landing Page, and the claim amount will be affected by the new Fee

Adjustment Ledger Entry

If there is an error, if the amount of the invoice needs to be adapted, or if you need to change the fees? The Adjustment Ledger Entry can affect any previous Ledger Entry or the amount (balance) of the account as well.

Ledger Entry Adjustment

To apply an adjustment to a previously created Ledger Entry, we just need to set the context.ledgerEntryReference with the target of the adjustment, for example:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "FEE_ADJUSTMENT_LEDGER_ENTRY_REFERENCE",
    "adjustmentDetails": {
        "amount": -500
    },
    "context": {
        "ledgerEntryReference": "FEE_LEDGER_ENTRY_REFERENCE"
    }
}]

The previous Adjustment Ledger Entry will change the amount of the Fee, which our example would now change as well:

{
  "accountId": "ACCOUNT_REFERENCE",
  "amount": 100000,
  "currency": "EUR",
  "debtor": {
    "contactInformation": {
      "additionalAddresses": [],
      "country": "DE"
    },
    "externalDebtorRef": "EXTERNAL_DEBTOR_REFERENCE",
    "firstName": "FIRST_NAME",
    "lastName": "LAST_NAME"
  },
  "dueDate": "2021-08-08",
  "externalClaimRef": "INVOICE_LEDGER_ENTRY_REFERENCE-2021-08-08",
  "externalDueDate": "2021-08-08",
  "fees": [{
    "name": "INVOICE_LEDGER_ENTRY_REFERENCE",
    "amount": 7000
  }],
  "meta": {
    "__invoiceLedgerEntry__": {
      "context": {},
      "invoiceDetails": {
        "amount": 100000,
        "createdAt": 1625581534864,
        "dueDate": "2021-08-08"
      },
      "ledgerEntryReference": "INVOICE_LEDGER_ENTRY_REFERENCE",
      "type": "invoice"
    },
    "key1": "value1"
  },
  "totalFees": 7000
}

To change the value of the Claim, then the context.ledgerEntryReference should be the Ledger Entry Reference of the Invoice, in this example: INVOICE_LEDGER_ENTRY_REFERENCE

Account Adjustment

To adjust the amount of the account, leave the context object empty:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "ACCOUNT_ADJUSTMENT_LEDGER_ENTRY_REFERENCE",
    "adjustmentDetails": {
        "amount": -500
    },
    "context": {}
}]

This will be reflected in the Account Amount, but it won’t affect any claim that belongs to that specific Account

Note: The adjustments can have a positive or negative amount, that will increase or decrease the Account, Invoice, or Fee amounts respectively.

Payment Ledger Entry

A Payment Ledger Entry represents a decrease of the amount of an Account Adjustment, an Invoice, or a Fee Ledger Entry, therefore it must always have a context.ledgerEntryReference

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "PAYMENT_FEE_LEDGER_ENTRY_REFERENCE",
    "paymentDetails": {
      "amount": 7000,
      "paymentProvider": "trustly",
      "paymentReference": "PAYMENT_REFERENCE",
      "meta": {
        "trackingId": "PROVIDER_TRACKING_ID"
      }
    },
    "context": {
        "ledgerEntryReference": "FEE_LEDGER_ENTRY_REFERENCE"
    }
}]

Note:

  • The ledgerEntryReference must be unique, if a payment creates more than one Payment Ledger Entry is important to have unique names
  • If the Invoice + Fees are paid, the claim associated with the invoice (and their fees) will be considered as Resolved and the Strategy will stop
  • An already paid Invoice should not be adjusted using an Adjustment Ledger Entry, because the strategy associated with that Claim is already in a final state (stopped)

Landing Page Payments

If the payment is through the Landing Page, then the debtor selected the specific claims to pay, therefore the system automatically creates the Payment Ledger Entries pointing to the corresponding Invoices Ledger Entries (and their Fees), any remaining amount is automatically mapped to pay any Account Ledger Entry (Fee or Adjustment) based on the creation time.

Chargeback ledger entries

A Chargeback Ledger Entry represents an increase of the amount of the ledger and must reference a payment, hence it must always have the context.ledgerEntryReference set:

POST /v1/${clientId}/add_account_ledger_entries HTTP/1.1
Content-Type: application/json

[{
    "accountReference": "ACCOUNT_REFERENCE",
    "ledgerEntryReference": "CHARGEBACK_LEDGER_ENTRY_REFERENCE",
    "chargebackDetails": {
      "amount": 7000,
      "meta": {
        "trackingId": "PROVIDER_TRACKING_ID",
        "providerName": "providerName"
      }
    },
    "context": {
        "ledgerEntryReference": "PAYMENT_ENTRY_REFERENCE"
    }
}]

Note:

  • The ledgerEntryReference must be unique
  • The chargeback amount must be greater than or equal to 0
  • Chargebaks will update the amount of the claim

ON THIS PAGE