Issuing Digital Claims & Invoices

What you will build.

Create a fictional invoice DEMO-INV-01 for 10,000 minor units and record a 4,000-unit payment. Then introduce a disputed obligation and a corrected document version. The exercise teaches reconciliation; it does not establish a legally enforceable claim or transfer rights.

Your working record

Create a private worksheet with columns for the source reference, observed state, responsible system, observation time, expected result and unresolved issue. Use the same fictional case throughout the steps; do not paste live personal or financial records into this exercise.

1. 01Separate the obligation from its representation
2. 02Reconcile a partial payment
3. 03Preserve dispute and correction state
4. 04Prepare the accounting handoff

Run the example before changing it.

Inspect the baseline record below. Download and read the complete JavaScript file before running it. It uses only Node’s built-in test and assertion modules; there is no package installation, account connection or secret to configure.

{
  "dueMinor": 10000,
  "paidMinor": 10000,
  "disputed": false,
  "approvedVersion": "I2",
  "recordVersion": "I2"
}

Save it as issuing-digital-claims-and-invoices.mjs. Open a terminal in that folder and run:

node --version
node --test issuing-digital-claims-and-invoices.mjs

Expected result: four passing tests and zero failures. These tests verify the teaching classifier only. They do not verify a production integration, security boundary or financial outcome.

// Hybrid-Chain offline teaching model: issuing-digital-claims-and-invoices
// Fictional fields/states; NOT an API client, authorization system or production implementation.
// No network calls, credentials, payments or file writes. Review before running.
// Requires Node.js 22+. Run: node --test issuing-digital-claims-and-invoices.mjs
import test from 'node:test';
import assert from 'node:assert/strict';

export function inspect(record) {
  if (record.disputed) return 'DISPUTED';
  if (record.approvedVersion !== record.recordVersion) return 'VERSION_REVIEW_REQUIRED';
  if (record.paidMinor < record.dueMinor) return 'PARTIAL_PAYMENT';
  return 'PAYMENT_RECORDED_FOR_REVIEW';
}

const baseline = {
  "dueMinor": 10000,
  "paidMinor": 10000,
  "disputed": false,
  "approvedVersion": "I2",
  "recordVersion": "I2"
};
const cases = [
  {
    "name": "payment recorded",
    "patch": {},
    "expected": "PAYMENT_RECORDED_FOR_REVIEW"
  },
  {
    "name": "partial receipt",
    "patch": {
      "paidMinor": 4000
    },
    "expected": "PARTIAL_PAYMENT"
  },
  {
    "name": "disputed obligation",
    "patch": {
      "disputed": true
    },
    "expected": "DISPUTED"
  },
  {
    "name": "old invoice reference",
    "patch": {
      "recordVersion": "I1"
    },
    "expected": "VERSION_REVIEW_REQUIRED"
  }
];

for (const example of cases) {
  test(example.name, () => {
    assert.equal(inspect({...baseline, ...example.patch}), example.expected);
  });
}

Know what the tests demonstrate

payment recorded

PAYMENT_RECORDED_FOR_REVIEW

partial receipt

PARTIAL_PAYMENT

disputed obligation

DISPUTED

old invoice reference

VERSION_REVIEW_REQUIRED

Now change one fixture at a time. If you change a case’s input without changing its expected result, the test should fail. Read the actual-versus-expected difference and use the walkthrough to decide whether your rule or your expectation needs correcting. Keep an unchanged copy for comparison.

Work through the case, step by step.

1. 01

   Separate the obligation from its representation

   Do this

   1. Record DEMO-INV-01, the source agreement, due amount and currency.
   2. Add separate references for the invoice version and any digital representation.
   3. Specify who can see the underlying commercial terms and who can issue a correction.

   Expected result

   The digital record points to an obligation managed by the creditor's actual agreement and accounting process.

   If your result is different

   Do not publish customer names or contract terms in public metadata simply to make the references easier to read.

2. 02

   Reconcile a partial payment

   Do this

   1. Run the baseline with dueMinor=10000 and paidMinor=10000, then change paidMinor to 4000.
   2. Confirm PARTIAL_PAYMENT rather than PAID and record the remaining 6000 minor units in the worksheet.
   3. Keep the provider reference and observation time beside the amount so a later update can be reconciled.

   Expected result

   A partial receipt remains visibly different from full payment and can be explained using exact units.

   If your result is different

   Do not mix currencies or floating-point calculations; use the precision and representation required by the actual contract.

3. 03

   Preserve dispute and correction state

   Do this

   1. Set disputed=true and confirm DISPUTED takes precedence over the payment label.
   2. Restore the fixture and change recordVersion from I2 to I1; expect VERSION_REVIEW_REQUIRED.
   3. Keep a correction link from the old reference to the new one instead of deleting history.

   Expected result

   A paid amount does not erase a dispute, and an old digital reference does not silently become the corrected invoice.

   If your result is different

   If your UI only supports paid/unpaid, add a separate dispute indicator and version reference before integrating delivery or transfer.

4. 04

   Prepare the accounting handoff

   Do this

   1. Save the four test outcomes and the invoice, agreement, payment and correction references.
   2. Document where overpayment, refunds, credit notes and assignment of rights would be handled; this small model does not implement them.
   3. Use Data Vault to plan private source access while keeping only permitted evidence references in shared views.

   Expected result

   The handoff gives an accountant enough context to review the case without claiming that tokenization validates the debt.

   If your result is different

   Escalate legal enforceability and assignment questions to the creditor's advisers; neither this exercise nor an integrity proof answers them.

Review what you produced.

Save the worksheet, unmodified test output, one deliberately failing case and the explanation of its fix. A useful result includes an unresolved item with an owner; it is not just a screenshot of four green tests.

Map the model to actual systems.

The creditor owns the agreement, debtor identity checks, invoice calculation, corrections, dispute handling, and collection process. Qualified advisers must determine the appropriate legal structure.

For each worksheet field, name the owning system, exact current operation, permission and error behavior. Put “not available” next to any missing operation and assign a dependency owner. Do not substitute the teaching classifier for that missing integration.

Open the current API reference and inspect each operation’s request, response, scope and implementation status. Code examples on this page are local models only; they do not call those operations.

Before a real deployment, the responsible organization must obtain appropriate legal, compliance and security review. The tutorial does not determine licensing, eligibility, entitlement enforceability or financial suitability.

Take the next technical step.

Use your worksheet and failing-case notes in the next walkthrough. Keep the same reference trail so you can see which assumptions become actual observations—and which remain dependencies.

Need help with access or an unavailable integration? Contact the team with a redacted error and the guide step. Never send credentials or private records.