H. How to model medical transport provider payouts for healthcare AI
The workflow this guide solves
A completed transport is approved for payment. Record the approved obligation against confirmed funds, reserve the payout, and track settlement or definitive failure. FRAGMENT records balances; your application approves the obligation and the payment provider executes the transfer.
| 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. |
Medical necessity, benefits eligibility and transport evidence are external.
Define the source of truth before posting
Store the medical transport invoice, 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 approved obligations backed by a funded pool, including payout reservations and settlement. If application records and balances must share one database transaction, consider the Postgres integration trade-off. The approved bucket represents an operational obligation backed by the funded pool. It is not an actuarial reserve, credit facility, payroll engine or automatic authorization decision.
Map the business states to money buckets
The money path is: confirmed prefunding → available pool → approved case payable → payout pending → confirmed payout; definitive failure returns the reserved amount to approved availability.
Record confirmed prefunding. Allocate only an externally approved case amount to the correct payee. Cancel an unpaid approved amount only when authorized. Reserve an approved amount before calling the payout provider. Record settlement or definitive failure against that exact reservation.
The schema declares the following leaf accounts. :<id> denotes an instance of a template account; exact posting paths and parameter names are in the downloaded JSON.
- assets
- confirmed-cash
- liabilities
- sources:<id>
- available
- payees:<id>
- cases:<id>
- approved
- payouts:<id>
- pending
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
Fund
Record a confirmed incoming payment; does not execute a payment
Approve
Allocate prefunded money to an approved case payable
Cancel Approval
Return an unpaid approved amount to the funded pool
Reserve Payout
Reserve an approved payable before calling the payout provider
Payout Settled
Record confirmed external payout settlement
Payout Failed
Release reservation only after definitive external payout failure
The source balance caps allocations; the approved balance caps cancellation and payout reservation; the pending balance caps settlement or failure release. Confirmed cash must also remain nonnegative when a payout settles. The schema uses strong total-balance updates and postconditions on the relevant unlinked accounts, following the consistency guide. It does not impose a complete business state machine or authorize callers.
Here is the actual medical_transport_provider_payouts_approve entry definition from this schema:
{
"type": "medical_transport_provider_payouts_approve",
"description": "Allocate prefunded money to an approved case payable",
"lines": [
{
"key": "line_1",
"account": {
"path": "liabilities/sources:{{source_id}}/available"
},
"amount": "-{{amount}}"
},
{
"key": "line_2",
"account": {
"path": "liabilities/payees:{{payee_id}}/cases:{{case_id}}/approved"
},
"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
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.
- assets/confirmed-cash
- 1000
- liabilities/sources:1/available
- 1000
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.
- assets/confirmed-cash
- 1000
- liabilities/sources:1/available
- 1000
Step 3: approve
Amount parameters, in cents: amount=700. Expected outcome: posted.
Expected result: The available funds balance decreases from 1,000 to 300 USD cents. The approved payables balance increases from 0 to 700 USD cents.
- liabilities/sources:1/available
- 300
- liabilities/payees:1/cases:1/approved
- 700
Step 4: approve
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.
- liabilities/sources:1/available
- 300
- liabilities/payees:1/cases:1/approved
- 700
Step 5: cancel_approval
Amount parameters, in cents: amount=100. Expected outcome: posted.
Expected result: The available funds balance increases from 300 to 400 USD cents. The approved payables balance decreases from 700 to 600 USD cents.
- liabilities/sources:1/available
- 400
- liabilities/payees:1/cases:1/approved
- 600
Step 6: reserve_payout
Amount parameters, in cents: amount=400. Expected outcome: posted.
Expected result: The approved payables balance decreases from 600 to 200 USD cents. The pending payouts balance increases from 0 to 400 USD cents.
- liabilities/payees:1/cases:1/approved
- 200
- liabilities/payees:1/cases:1/payouts:1/pending
- 400
Step 7: reserve_payout
Amount parameters, in cents: amount=300. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
- liabilities/payees:1/cases:1/approved
- 200
- liabilities/payees:1/cases:1/payouts:1/pending
- 400
Step 8: payout_failed
Amount parameters, in cents: amount=100. Expected outcome: posted.
Expected result: The approved payables balance increases from 200 to 300 USD cents. The pending payouts balance decreases from 400 to 300 USD cents.
- liabilities/payees:1/cases:1/approved
- 300
- liabilities/payees:1/cases:1/payouts:1/pending
- 300
Step 9: payout_settled
Amount parameters, in cents: amount=300. Expected outcome: posted.
Expected result: The confirmed cash balance decreases from 1,000 to 700 USD cents. The pending payouts balance decreases from 300 to 0 USD cents.
- assets/confirmed-cash
- 700
- liabilities/payees:1/cases:1/payouts:1/pending
- 0
- liabilities/payees:1/cases:1/approved
- 300
Step 10: payout_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.
- assets/confirmed-cash
- 700
- liabilities/payees:1/cases:1/payouts:1/pending
- 0
Step 11: cancel_approval
Amount parameters, in cents: amount=301. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
Step 12: approve
Amount parameters, in cents: amount=-1. Expected outcome: input_rejected.
Expected result: The application rejects these parameters before posting an entry. No balances change.
The account paths above match the scenario file. 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 and the application contract. Use the shared tool guide for installation and current official references. From the directory containing your reviewed schema:
fragment verify-schema --path schema.json --json
fragment gen-graphql --path=schema.json --output=queries.graphqlChoose 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:
{
"ik": "replace-with-stable-business-operation-key",
"entry": {
"ledger": {
"ik": "replace-with-confirmed-test-ledger"
},
"type": "medical_transport_provider_payouts_approve",
"typeVersion": 1,
"parameters": {
"source_id": "1",
"case_id": "1",
"payee_id": "1",
"amount": "700"
}
}
}Use it with the documented AddLedgerEntry mutation. 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 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:
| Entry | Input requirements |
|---|---|
medical_transport_provider_payouts_fund | positive integers: amount |
medical_transport_provider_payouts_approve | positive integers: amount |
medical_transport_provider_payouts_cancel_approval | positive integers: amount |
medical_transport_provider_payouts_reserve_payout | positive integers: amount |
medical_transport_provider_payouts_payout_settled | positive integers: amount |
medical_transport_provider_payouts_payout_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.
- 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.
- 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.
- 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.
- 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.
- Deduplicate callbacks and reject mismatched or stale case/payee/amount associations. Keep terminal operation decisions immutable and post authorized adjustments separately.
- Reconcile
assets/confirmed-cashagainst the actual external records. These schemas use a manually modeled cash account. A linked-account reconciliation integration is an additional implementation step, with separate unlinked buckets for conditional authorization.
Exercise the industry-specific edges
- Submit the same medical transport invoice under two operation keys; the application must reject the duplicate obligation.
- Revise the approved medical transport invoice amount while a payout is pending; reconcile the reservation before applying an adjustment.
- Test the boundary for this particular workflow: medical necessity, benefits eligibility and transport evidence 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.