# How to model tutoring lesson deposits for education AI Source: https://fragment.dev/solutions/tutoring-lesson-deposits ## The workflow this guide solves A learner prepays a specific tutoring lesson. Track confirmed customer funds separately from service allocations and pending refunds. Fragment records the balances; your application approves service completion or refunds and the payment provider executes collections and returns. | System | Responsibility | | --- | --- | | Your application | Approve the business event, amount, and recipient. | | Fragment ledger | Record entries, enforce configured balance conditions, and track balances. | | Payment provider | Execute the transfer and report its outcome. | Teaching outcomes, safeguarding and attendance approval are external. ## Define the source of truth before posting Store the tutoring lesson booking, its approval, and supporting evidence in your application. Bind the record to its source, tenant, and recipient. Preserve the approved amount, record version, and payment status. Give each intended financial effect an immutable operation key and payload fingerprint. A ledger entry records an authorized financial movement. It does not execute an external payment or atomically commit your application database. Use opaque account identifiers and bind them server-side. Fixture identifiers are examples; a balance condition does not authorize a caller. ## Decide whether this ledger model fits Use this model to track prepaid funds, approved service allocations, and refunds against the remaining customer balance. If application records and balances must share one database transaction, consider [the Postgres integration trade-off](/blog/fragment-vs-postgres). Do not treat a deposit as an earned service amount merely because a booking exists. This example uses an operational earned-fee bucket, not a complete revenue-recognition policy. ## Map the business states to money buckets The money path is: confirmed funding → available → case hold → accepted service allocation; unused or credited funds → refund pending → confirmed refund. Fund only after incoming money is confirmed. Reserve the approved case amount. Allocate an accepted delivered amount to operational earned fees. Release the unused hold. If an approved service credit is needed, move it back to customer availability; reserve the external refund before submitting it. The schema declares the following leaf accounts. `:` denotes an instance of a template account; exact posting paths and parameter names are in the downloaded JSON. - `assets/confirmed-cash` - `liabilities/sources:/available` - `liabilities/sources:/cases:/held` - `liabilities/sources:/refunds:/pending` - `income/cases:` All amounts in this example are USD cents encoded as integer strings. The figures below are illustrative test values, not proposed prices, compensation amounts or commercial terms. Token usage, service quantities and exchange rates are outside this example. ## Inspect the allowed entry types ### `tutoring_lesson_deposits_fund` Record a confirmed incoming payment; does not execute a payment ### `tutoring_lesson_deposits_reserve` Reserve customer prepayment for an authorized case ### `tutoring_lesson_deposits_release` Release an unused case hold to available customer funds ### `tutoring_lesson_deposits_complete` Allocate an accepted delivered service amount to operational earned fees ### `tutoring_lesson_deposits_credit_service` Credit an approved service amount back to the customer ### `tutoring_lesson_deposits_reserve_refund` Reserve a customer refund before calling the payment provider ### `tutoring_lesson_deposits_refund_settled` Record a refund only after the payment provider confirms it settled ### `tutoring_lesson_deposits_refund_failed` Release the refund reservation only after definitive failure The available balance prevents reserving more than is funded; the held balance caps completion or release; the per-case earned balance caps service credits. Refund settlement consumes only the matching pending refund. The schema uses strong total-balance updates and postconditions on the relevant unlinked accounts, following the [consistency guide](https://fragment.dev/guides/configure-consistency). It does not impose a complete business state machine or authorize callers. Here is the actual `tutoring_lesson_deposits_reserve` entry definition from this schema: ```json { "type": "tutoring_lesson_deposits_reserve", "description": "Reserve customer prepayment for an authorized case", "lines": [ { "key": "line_1", "account": { "path": "liabilities/sources:{{source_id}}/available" }, "amount": "-{{amount}}" }, { "key": "line_2", "account": { "path": "liabilities/sources:{{source_id}}/cases:{{case_id}}/held" }, "amount": "{{amount}}" } ], "conditions": [ { "account": { "path": "liabilities/sources:{{source_id}}/available" }, "postcondition": { "totalBalance": { "gte": "0" } } } ] } ``` ## Walk through the expected balances Start with a fresh empty test ledger. Read the steps in order. The replay step deliberately repeats the funding operation key and payload; it must leave balances unchanged. Every rejected operation must also leave all balances unchanged. ### Step 1: fund [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-1-fund) Amount parameters, in cents: amount=1000. Expected outcome: `posted`. Expected result: The confirmed cash balance increases from 0 to 1,000 USD cents. The available funds balance increases from 0 to 1,000 USD cents. Entry: `tutoring_lesson_deposits_fund`. Posted changes (USD cents): - `assets/confirmed-cash`: +1000 - `liabilities/sources:1/available`: +1000 Balances after this step (USD cents): - `assets/confirmed-cash`: 1000 - `liabilities/sources:1/available`: 1000 ### Step 2: fund [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-2-fund) Amount parameters, in cents: amount=1000. Expected outcome: `replay`. Expected result: This retry reuses the original operation key and payload. No new entry is posted, so all balances stay unchanged. Entry: `tutoring_lesson_deposits_fund`. Posted changes (USD cents): No new entry posted. Balances unchanged. Balances after this step (USD cents): - `assets/confirmed-cash`: 1000 - `liabilities/sources:1/available`: 1000 ### Step 3: reserve [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-3-reserve) Amount parameters, in cents: amount=700. Expected outcome: `posted`. Expected result: The available funds balance decreases from 1,000 to 300 USD cents. The held funds balance increases from 0 to 700 USD cents. Entry: `tutoring_lesson_deposits_reserve`. Posted changes (USD cents): - `liabilities/sources:1/available`: -700 - `liabilities/sources:1/cases:1/held`: +700 Balances after this step (USD cents): - `liabilities/sources:1/available`: 300 - `liabilities/sources:1/cases:1/held`: 700 ### Step 4: reserve [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-4-reserve) Amount parameters, in cents: amount=400. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `tutoring_lesson_deposits_reserve`. Posted changes (USD cents): No new entry posted. Balances unchanged. Balances after this step (USD cents): - `liabilities/sources:1/available`: 300 - `liabilities/sources:1/cases:1/held`: 700 ### Step 5: complete [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-5-complete) Amount parameters, in cents: amount=500. Expected outcome: `posted`. Expected result: The held funds balance decreases from 700 to 200 USD cents. The income balance increases from 0 to 500 USD cents. Entry: `tutoring_lesson_deposits_complete`. Posted changes (USD cents): - `liabilities/sources:1/cases:1/held`: -500 - `income/cases:1`: +500 Balances after this step (USD cents): - `liabilities/sources:1/cases:1/held`: 200 - `income/cases:1`: 500 ### Step 6: complete [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-6-complete) Amount parameters, in cents: amount=201. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `tutoring_lesson_deposits_complete`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 7: credit_service [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-7-credit_service) Amount parameters, in cents: amount=100. Expected outcome: `posted`. Expected result: The income balance decreases from 500 to 400 USD cents. The available funds balance increases from 300 to 400 USD cents. Entry: `tutoring_lesson_deposits_credit_service`. Posted changes (USD cents): - `income/cases:1`: -100 - `liabilities/sources:1/available`: +100 Balances after this step (USD cents): - `income/cases:1`: 400 - `liabilities/sources:1/available`: 400 ### Step 8: credit_service [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-8-credit_service) Amount parameters, in cents: amount=401. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `tutoring_lesson_deposits_credit_service`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 9: release [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-9-release) Amount parameters, in cents: amount=200. Expected outcome: `posted`. Expected result: The held funds balance decreases from 200 to 0 USD cents. The available funds balance increases from 400 to 600 USD cents. Entry: `tutoring_lesson_deposits_release`. Posted changes (USD cents): - `liabilities/sources:1/cases:1/held`: -200 - `liabilities/sources:1/available`: +200 Balances after this step (USD cents): - `liabilities/sources:1/cases:1/held`: 0 - `liabilities/sources:1/available`: 600 ### Step 10: release [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-10-release) Amount parameters, in cents: amount=1. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `tutoring_lesson_deposits_release`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 11: reserve_refund [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-11-reserve_refund) Amount parameters, in cents: amount=200. Expected outcome: `posted`. Expected result: The available funds balance decreases from 600 to 400 USD cents. The pending refunds balance increases from 0 to 200 USD cents. Entry: `tutoring_lesson_deposits_reserve_refund`. Posted changes (USD cents): - `liabilities/sources:1/available`: -200 - `liabilities/sources:1/refunds:1/pending`: +200 Balances after this step (USD cents): - `liabilities/sources:1/available`: 400 - `liabilities/sources:1/refunds:1/pending`: 200 ### Step 12: refund_failed [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-12-refund_failed) Amount parameters, in cents: amount=50. Expected outcome: `posted`. Expected result: The available funds balance increases from 400 to 450 USD cents. The pending refunds balance decreases from 200 to 150 USD cents. Entry: `tutoring_lesson_deposits_refund_failed`. Posted changes (USD cents): - `liabilities/sources:1/available`: +50 - `liabilities/sources:1/refunds:1/pending`: -50 Balances after this step (USD cents): - `liabilities/sources:1/available`: 450 - `liabilities/sources:1/refunds:1/pending`: 150 ### Step 13: refund_settled [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-13-refund_settled) Amount parameters, in cents: amount=150. Expected outcome: `posted`. Expected result: The pending refunds balance decreases from 150 to 0 USD cents. The confirmed cash balance decreases from 1,000 to 850 USD cents. Entry: `tutoring_lesson_deposits_refund_settled`. Posted changes (USD cents): - `liabilities/sources:1/refunds:1/pending`: -150 - `assets/confirmed-cash`: -150 Balances after this step (USD cents): - `liabilities/sources:1/refunds:1/pending`: 0 - `assets/confirmed-cash`: 850 ### Step 14: refund_settled [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-14-refund_settled) Amount parameters, in cents: amount=1. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `tutoring_lesson_deposits_refund_settled`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 15: reserve [Link to this step](https://fragment.dev/solutions/tutoring-lesson-deposits#step-15-reserve) Amount parameters, in cents: amount=0. Expected outcome: `input_rejected`. Expected result: The application rejects these parameters before posting an entry. No balances change. Entry: `tutoring_lesson_deposits_reserve`. Posted changes (USD cents): No new entry posted. Balances unchanged. The account paths above match [the scenario file](/examples/vertical-ai/education--tutoring-lesson-deposits/scenarios.json). A snapshot lists the balances checked at that point; it does not assert that all other balances are zero. The included schema scene contains the accepted entries; the separate fixture file contains replay and rejection cases too. Some fixtures divide a reserved outgoing amount into a definitively failed portion and a settled portion. Your application must represent those as separately identified external sub-operations with exact amounts. This is an illustrative recovery sequence, not a claim that a given payment API supports partial failure on one request. ## Validate the schema and integrate a tool Download [schema.json](/examples/vertical-ai/education--tutoring-lesson-deposits/schema.json) and [the application contract](/examples/vertical-ai/education--tutoring-lesson-deposits/application-contract.json). Use the [shared tool guide](/api-reference/ledger-cli-commands) for installation and current official references. From the directory containing your reviewed schema: ```bash fragment verify-schema --path schema.json --json fragment gen-graphql --path=schema.json --output=queries.graphql ``` Choose the official SDK for your application's language and generate the schema-specific client as documented. For MCP, connect the intended workspace and confirm the target project before editing, simulation or deployment. Tool names can vary across server versions; enumerate the connected server instead of assuming a universal tool list. After the confirmed funding step, this is an example variable object for the first business allocation: ```json { "ik": "replace-with-stable-business-operation-key", "entry": { "ledger": { "ik": "replace-with-confirmed-test-ledger" }, "type": "tutoring_lesson_deposits_reserve", "typeVersion": 1, "parameters": { "source_id": "1", "case_id": "1", "amount": "700" } } } ``` Use it with the [documented AddLedgerEntry mutation](/examples/vertical-ai/AddLedgerEntry.graphql). Replace the test-ledger and operation-key placeholders with confirmed values; the other identifiers and amounts must match your authorized test case. [The complete accepted request sequence](/examples/vertical-ai/education--tutoring-lesson-deposits/requests.json) is provided as review data, not as an automatic execution script. Handle returned error results as well as transport failures. ## Enforce the application-side input contract The schema's balancing and nonnegative postconditions do not reject every invalid signed input. Validate these rules before posting, using the downloaded contract as the exact reference: ### `tutoring_lesson_deposits_fund` positive integers: amount ### `tutoring_lesson_deposits_reserve` positive integers: amount ### `tutoring_lesson_deposits_release` positive integers: amount ### `tutoring_lesson_deposits_complete` positive integers: amount ### `tutoring_lesson_deposits_credit_service` positive integers: amount ### `tutoring_lesson_deposits_reserve_refund` positive integers: amount ### `tutoring_lesson_deposits_refund_settled` positive integers: amount ### `tutoring_lesson_deposits_refund_failed` positive integers: amount Authorize the exact source, case and recipient; check the current approval version; and reject a command that conflicts with a terminal domain outcome. A new approval revision is a new business decision. A duplicate delivery of the same revision is a retry, with the same operation identity. ## What happens if a payment fails or its outcome is unknown? Keep funds reserved while the payment outcome is unknown. Release only the amount confirmed as definitively failed; record settlement only after provider confirmation. For a timed-out ledger request, retry the same operation key and payload to avoid posting twice. 1. Persist an authorized command and an outbox record before requesting an effect. Keep its ledger key, payload fingerprint, case version and provider operation identity durable. 2. Reserve the relevant available amount before requesting an outgoing payment. If the ledger request times out, recover using the same operation key and payload; do not invent a second operation because the first response was lost. 3. Submit the provider action according to that provider's idempotency and retry rules. Keep its identifier bound to the exact pending reservation. This guide supplies no provider-specific retention guarantee. 4. If the provider outcome is unknown, leave the amount reserved and reconcile it. An elapsed timer is not proof of failure. A definitive failed sub-operation can release its own amount; a confirmed settlement can consume its own amount. 5. Deduplicate callbacks and reject mismatched or stale case/payee/amount associations. Keep terminal operation decisions immutable and post authorized adjustments separately. 6. Reconcile `assets/confirmed-cash` against the actual external records. These schemas use a manually modeled cash account. A [linked-account reconciliation integration](https://fragment.dev/guides/reconcile-payments) is an additional implementation step, with separate unlinked buckets for conditional authorization. ## Exercise the industry-specific edges - Cancel the tutoring lesson booking after part of the funds has been allocated; refund only the amount authorized by policy. - Change the tutoring lesson booking price after funds are reserved; authorize an adjustment instead of rewriting the original entry. - Test the boundary for this particular workflow: teaching outcomes, safeguarding and attendance approval are external. The application should route the decision to the appropriate domain system rather than treating the ledger balance as authority. - Submit two competing commands that individually fit the current balance but together exceed it. In a live test ledger, verify that accepted total allocation stays within the available amount and that rejected commands have no effect. - Crash after reservation but before your application stores the response. Recover the recorded operation instead of crediting or debiting the case twice. ## Acceptance before using this with real money The originating schema passed the local Fragment parser and the earlier offline model fixtures. This written guide does not establish live API, concurrency, callback recovery or provider correctness. Before release, have a domain reviewer accept the stated boundaries, run the full fixture sequence in a fresh test ledger, compare actual balances with the expected snapshots, and test real retry/reorder/unknown-outcome recovery using controlled test operations. Also verify that one tenant cannot choose another tenant's source or case, that nonpositive or inconsistent amounts are rejected by the application, and that every posted movement has durable approval and payment evidence. Record the exact schema version and result traces. Publication and agent-discovery evaluation are separate from this integration acceptance. ## Related education workflows - [Tutor lesson marketplace](/solutions/tutor-lesson-marketplace) - [Training instructor payouts](/solutions/training-instructor-payouts) - [Training expense reimbursements](/solutions/training-expense-reimbursements) - [Course cohort prepayments](/solutions/tuition-payments) ## Sources and companion files - [Quickstart: schema, SDK and API setup](https://fragment.dev/guides/quickstart) - [Posting entries: parameter strings and idempotency](https://fragment.dev/guides/post-ledger-entries) - [Consistency: strong balance conditions and linked-account restrictions](https://fragment.dev/guides/configure-consistency) - [Payment reconciliation](https://fragment.dev/guides/reconcile-payments) - [CLI reference](https://fragment.dev/api-reference/ledger-cli-commands) - [MCP reference](https://fragment.dev/api-reference/mcp) - [SDK reference](https://fragment.dev/api-reference/ledger-sdks) - [Schema](/examples/vertical-ai/education--tutoring-lesson-deposits/schema.json) - [Expected results](/examples/vertical-ai/education--tutoring-lesson-deposits/scenarios.json) - [Request variables](/examples/vertical-ai/education--tutoring-lesson-deposits/requests.json) - [Application contract](/examples/vertical-ai/education--tutoring-lesson-deposits/application-contract.json)