Anaya Wallet

Part of the Anaya Care Handbook — the source of truth for how the product must behave. When the product needs to change, change this document first, then make the system match it.

Implementation status — this module is specified but not yet built. Every rule below is 🚧 Spec only until the feature ships and this page is audited against the code. Legend: ✅ In code · ⚠️ Partial · 🚧 Spec only (not yet built).

What this covers

This page governs the Anaya Wallet: a per-client prepaid balance, and the payment rail that fills it — the money that actually moves underneath the fund-request flow on Essential Needs (NEED-18 – NEED-23). Essential Needs owns the conversation — the care provider asks the agency, the agency asks the family, receipts close the loop. The Wallet owns the money — collecting it from the responsible party, settling it to the agency, drawing it down as requests are approved, and reconciling it against receipts.

Today, without the platform, the agency buys a client's essential needs out of its own pocket and chases the family for reimbursement afterwards — and where the agency does not front it, the care provider standing in the store does. The Wallet exists to end that: the family's money arrives before anyone shops, and where it has not, the shortfall is recorded as something the agency is owed rather than lost in somebody's inbox.

There is one model, not two. A client has a wallet with a balance. The responsible party tops it up; approved fund requests draw it down; receipts correct the difference. Funding a single request on its own is not a separate mechanism — it is simply a top-up sized to that request, which is what an agency will do for a household that buys rarely. A household that shops weekly tops up once a month instead of answering a payment screen every week.

Key terms

• Anaya Wallet — a client's prepaid balance, held by the agency and recorded by the platform, that approved fund requests draw against.
• Wallet balance — what the wallet is worth right now: everything paid in, less everything drawn out. It can be negative.
• Top-up — a payment that adds money to a client's wallet. It settles to the agency, never to Anaya.
• Receivable — a negative balance: money the agency has already spent on the client's behalf that the family has not paid for yet.
• Fund request — defined under Essential Needs. The itemized, priced list the responsible party approves or declines. The Wallet is what makes that approval move money.
• Responsible party — the Care Circle member who approves fund requests, pays the top-ups behind them, and can see the balance and the full transaction history. Maps to the Representative role.
• Payment method — the card the responsible party pays a top-up with. Cards only to begin with; bank transfer (ACH) is a later addition.
• Connected account — the agency's own account at the fintech partner, with its own balance and its own bank details. Every top-up settles there, not into an Anaya account.
• Payout account — the agency's verified bank account behind the connected account, which the fintech partner pays out to.
• Merchant of record — the party a payment legally belongs to. For every Wallet payment that is the agency: it holds the money, it issues the refunds, and it carries the chargebacks.
• Platform fee — Anaya's percentage of each top-up, taken by the fintech partner as an application fee at the moment the payment settles. Set platform-wide, defaulting to nothing, and fixed on each transaction when it is raised.
• Settlement — money arriving in the agency's connected account.
• Confirmation — the fintech partner's own message, sent to the platform after the fact, saying a payment succeeded. It is the only thing allowed to credit a wallet.
• Reconciliation — comparing a closed request's receipted actual spend against the amount drawn from the wallet, and correcting the difference on the ledger.
• Underspend / overspend — the difference between the approved estimate drawn up front and the actual receipted total.
• Ledger — the platform's append-only record of every movement in and out of a wallet, each entry carrying the balance it produced, reconcilable line by line against the fintech partner's own record.
• Minor units — whole cents. Every amount on this page is stored and moved that way; nothing is ever a fraction of a cent.
• Off-platform deposit — money the family handed the agency outside the platform — cash, a bank transfer, a cheque — recorded on the wallet so the balance stays true.
• Manual adjustment — a ledger entry agency management posts by hand with a reason: a correction, a goodwill credit, or a deposit received off-platform.
• Balance minimum — the agreed threshold below which the wallet raises a low-balance alert.
• Unused funds — the balance left over when care services end, returned to the responsible party.
• Revolving fund — the earlier name for exactly this: a balance topped up in advance that purchase requests draw against. It is no longer a future concept; it is the wallet.
• Digital receipt — the proof-of-purchase image or document stored against a purchase, per NEED-3.
• Fintech partner — the external payments provider that moves the money, holds it in flight, and carries the money-transmitter licensing. The platform itself never holds or disburses funds. The selected partner is Stripe, with each agency onboarded as its own merchant.

How it works

Filling the wallet

A top-up is raised against one client, for an amount somebody chose — a month of groceries, a single request's total, whatever the household and the agency have agreed. The payment is collected on an embedded payment form inside the Anaya dashboard: the card details go straight to the fintech partner's own hosted fields and never reach Anaya's servers.

The charge is raised on the agency's behalf, by the agency. Each agency is its own merchant at the fintech partner, so the money moves from the payer into the agency's account and its own bank details, in one hop. Anaya's cut is taken by the partner at the same moment as an application fee — a percentage of the top-up, set platform-wide, defaulting to nothing, and stamped onto the transaction when it is raised so a later change to the rate can never reach back into money already in flight.

In this first version the payment screen lives on the dashboard, which only agency staff can reach: representatives are served by the mobile app, and the app has no essential-needs surface yet. So a v1 top-up is staff-assisted — agency staff open the payment screen and the responsible party's card is entered into it. That is a real limitation, not a design preference, and giving the family a screen of their own is the first thing to fix.

Nothing is credited because a browser said the payment worked. A browser can be closed mid-redirect, lied to, or simply wrong. The wallet is credited only when the fintech partner tells the platform, in its own message sent after the fact, that the money moved — and that message is processed once per event no matter how many times it arrives, because payment providers deliberately re-send confirmations they are not sure landed.

Spending it

The chain starts on Essential Needs: a care provider bundles Needed items into an essential-needs request, agency management reviews and approves it, and that approval becomes a fund request to the client's responsible party — an itemized, priced list with a total. The responsible party must explicitly approve it; nothing is drawn on submission. Approval and payment both need a live connection — the Wallet is a connectivity-dependent feature and is blocked entirely in offline mode.

On approval the request's total is drawn from that client's wallet, and the request becomes shoppable: the provider buys the items, marks each purchased with its receipt and actual cost per NEED-3, and the request closes showing estimated against actual spend.

A drawdown is never refused for want of funds. If the balance does not cover the request, the balance goes negative and the difference is an agency receivable — the agency has fronted the money, exactly as it does today, with the one difference that the platform now knows about it and says so to both the agency and the family. Hiding that number, or clamping it at zero, would recreate the invisible reimbursement chase this module exists to end.

Because the drawn amount is an estimate and the receipts are the truth, every closed request reconciles. An underspend restores the difference to the balance; an overspend draws the extra, taking the balance negative if that is where it lands. Money leaves the system back to a card only in two places: when care ends and unused funds are returned, or when the responsible party asks for their money back.

Why a stored balance was forbidden, and what changed

This page previously ruled a stored balance out entirely, and the reasoning was sound: holding a customer's money for future, unspecified use is money transmission, and it needs licensing in nearly every US state. That reasoning carried an assumption — that the platform would be the one holding the money.

The chosen architecture removes the assumption rather than arguing with the law. Each agency is its own merchant at the fintech partner, with its own account and its own bank details, and every top-up is a direct charge that lands in the agency's balance. Anaya never takes custody of a single cent: the fintech partner is the money transmitter, as it always was, and the agency is the merchant of record — it holds the funds, it issues the refunds, and it carries the disputes.

So the number on a client's wallet is not money Anaya is holding. It is Anaya's ledger of a prepayment the agency holds on that client's behalf — the same obligation an agency would otherwise keep in a spreadsheet, or in nobody's head at all. WALLET-12's core prohibition survives untouched and unweakened: the platform must never hold client funds. What is revised is only the conclusion that was drawn from it — that no balance may therefore exist.

The reversal has costs worth stating plainly. The agency now carries an obligation it must be able to account for, and a family's money can sit with an agency for weeks before it is spent. An agency that stops trading owes that money back, and nothing in the platform can make it pay. A family's recourse if a topped-up wallet is never spent is a conversation with the agency, or a dispute raised with their card issuer against the agency — not a refund button Anaya can press, because Anaya never had the money. The old design had none of those problems, because it moved money one purchase at a time; it also asked a family to answer a payment screen every single week, which is the friction that kept the whole module unused.

Rules

1. WALLET-1 — The system must never draw down a client's wallet without a submitted fund request and the responsible party's explicit approval of it, and must never take a payment from anyone who has not authorized that payment on the screen collecting it. A submitted-but-unapproved request must move no money. (🚧 Spec only)
2. WALLET-2 — The Wallet requires active connectivity. The system must block every Wallet transaction in offline mode and require connectivity to be restored before it can proceed. (🚧 Spec only)
3. WALLET-3 — The system must notify the responsible party for every fund request. (🚧 Spec only)
4. WALLET-4 — A digital receipt must be stored against every purchase made with Wallet funds, per NEED-3, and a request cannot close until every item is receipted or removed. (🚧 Spec only)
5. WALLET-5 — A client's current wallet balance and its full transaction history must be visible to the responsible party at all times, including while the balance is negative. (🚧 Spec only)
6. WALLET-6 — The system must raise a low-balance alert to agency management and the responsible party when a client's wallet balance falls to or below the agreed minimum, early enough that a top-up can happen before the next shop rather than after it fails. (🚧 Spec only)
7. WALLET-7 — A fund request that exceeds the available balance must never be refused for that reason alone. The system must let the approval through, take the balance negative per WALLET-21, state plainly that it has done so, and prompt the responsible party for a top-up. (🚧 Spec only)
8. WALLET-8 — When the responsible party does not respond to a fund request, the system must send a reminder, and the request must expire after a defined period. An expired request must never draw down a wallet. (🚧 Spec only)
9. WALLET-9 — A failed payment must leave nothing half-done — no partial credit, and no drawdown against money that never arrived — and the system must offer a retry. A wallet must never be left in a state where the money moved but the ledger did not, or the reverse. (🚧 Spec only)
10. WALLET-10 — A top-up must be payable by credit or debit card at minimum. Any further method the fintech partner supports — bank transfer (ACH) above all — must settle into the same agency account under the same rules, and must never route a client's money differently. (🚧 Spec only)
11. WALLET-11 — When care services end, the system must return any unused wallet balance to the responsible party, and must settle a negative balance explicitly — collected or written off, with a ledger entry either way. A closing wallet must never be silently zeroed. (🚧 Spec only)
12. WALLET-12 — The platform must never hold client funds. Every top-up must settle directly into the agency's own verified payout account at the fintech partner, with the agency as the merchant of record carrying its own refunds and disputes. A wallet balance is the platform's ledger of a prepayment the agency holds on the client's behalf, never platform custody of money, and money-transmitter licensing must rest entirely with the fintech partner. (🚧 Spec only)
13. WALLET-13 — A top-up must settle into the agency's connected account at the fintech partner, and approving a fund request must draw that request's approved total from the client's wallet. Money moves once, from the payer to the agency; the platform's part is the record of it. (🚧 Spec only)
14. WALLET-14 — Every drawdown must be tied to exactly one fund request and must be idempotent: a retry, a duplicate submission, or a resumed workflow must never debit a wallet twice for the same request. (🚧 Spec only)
15. WALLET-15 — A top-up payment that fails must leave the wallet uncredited — never credited-but-unpaid — and must notify both whoever raised it and the responsible party. (🚧 Spec only)
16. WALLET-16 — A closed request must reconcile its receipted actual spend against the amount drawn: an underspend must restore the difference to the client's wallet balance as a correcting entry, and an overspend must draw the extra and prompt a top-up. The difference must never be quietly dropped or left only in the item history. (🚧 Spec only)
17. WALLET-17 — Every money movement must be recorded in an append-only ledger, each entry reconcilable against the fintech partner's own record. A ledger entry must never be edited or deleted; a correction is a new entry. (🚧 Spec only)
18. WALLET-18 — Funds must settle only into a verified payout account belonging to the agency. The platform must never route a client's funds to an individual care provider's personal account. (🚧 Spec only)
19. WALLET-19 — A care provider must never be asked to spend their own money. A request may be handed to a care provider to shop only when the money for it is with the agency — from the client's wallet where the balance covers it, or from the agency's own funds where management has knowingly accepted the receivable under WALLET-21. A shortfall is the agency's to carry, never the care provider's. (🚧 Spec only)
20. WALLET-20 — A client has exactly one wallet, and it belongs to the agency that serves them. A balance must never be shared between clients, pooled across a household, or follow a client from one agency to another. (🚧 Spec only)
21. WALLET-21 — Approving a fund request must draw the wallet down even when the balance does not cover it, taking the balance below zero. A negative balance is an agency receivable — money the agency has fronted on the client's behalf — and must be surfaced plainly to agency management and to the responsible party. It must never be hidden, netted away, or clamped at zero. (🚧 Spec only)
22. WALLET-22 — The platform fee must be a percentage of each top-up, collected as the fintech partner's application fee at the moment the money moves, configured platform-wide rather than per agency, and fixed onto each transaction when its payment is raised — so a later change to the configured rate can never alter money already in flight or already taken. Where the percentage lands between whole cents the fee must round down, so that a fee never exceeds the published rate and an agency recomputing it by hand can never find it was charged above the rate it agreed to. (🚧 Spec only)
23. WALLET-23 — A top-up must be credited only on the fintech partner's own asynchronous confirmation, never because the paying device reported success. That processing must be idempotent per partner event: a redelivered, retried, or duplicated confirmation must credit the wallet exactly once. (🚧 Spec only)
24. WALLET-24 — Every amount must be recorded in whole minor units — cents, never a fraction of one — and every ledger entry must carry the balance that resulted from it. The ledger is the truth and a displayed balance is derived from it: the two must be reconcilable at any moment, and where they can briefly diverge — a machine failing partway through recording a movement — the system must detect the divergence and repair it from the ledger, never the other way round. A balance that cannot be rebuilt from its entries is a bug, not a rounding difference. (🚧 Spec only)
25. WALLET-25 — A correction is a new ledger entry carrying its reason and its author, never an edit or a deletion of an existing one. This restates WALLET-17 for a ledger that now carries a balance: reversing a mistake means posting its opposite, so the history of how a balance got where it is stays readable. (🚧 Spec only)

Who can do what

The earlier conflict on this page — whether a care provider or the responsible party raises the request — is resolved by the Essential Needs chain: the care provider raises an essential-needs request (NEED-18), agency management approves it (NEED-19), and only the responsible party approves and funds the resulting fund request (NEED-20).

Care providers hold no money permission of any kind. A care provider sees whether the request they raised is funded — which lives on Essential Needs — and never the household's balance, its payment history, or its receivable. They never raise a payment, never adjust a ledger, and never spend their own money (WALLET-19).

Decisions needed

• How does a responsible party get their money back before care ends? WALLET-11 covers the end of care, but a family that topped up and then changed agency, or simply changed their mind, has no route on this page. Anaya cannot refund what it never held, so any answer runs through the agency. Options: an in-platform refund request the agency actions in its own fintech dashboard, with the ledger entry posted here; a withdrawal the agency records as an off-platform payment; or nothing formal, and the family asks their agency directly. Open — and the one place where "the platform never holds the money" costs the family something real.
• How long until an unanswered fund request expires (WALLET-8)? Options: a fixed platform default; a per-agency configurable window; a per-request window set when it is raised. Should mirror whatever Essential Needs settles for its own fund-request expiry.
• Below what overspend is a top-up not worth prompting for (WALLET-16)? Chasing a family for a small overage may cost more goodwill than it recovers, and under WALLET-21 the alternative is simply a small receivable. Options: always prompt; a per-agency threshold below which the agency absorbs it; a threshold the responsible party pre-authorizes at top-up time.
• How far negative may a wallet go? WALLET-21 deliberately does not refuse an approval, which means nothing on this page stops a receivable growing. Options: no ceiling, and management judgement carries it; a per-client credit limit above which approval needs an owner; a per-agency ceiling. Whatever is chosen must not become a silent block, or WALLET-7 is undone.
• How is a refused or reversed payment handled after shopping has already happened? A chargeback lands days later, by which time the items are bought and used — and because the agency is the merchant of record, the chargeback lands on the agency, not on Anaya. Options: the agency carries the loss; the loss is posted back to the wallet as a receivable and pursued with the family; the platform mediates.
• Should bank transfer (ACH) be enabled alongside cards? ACH is materially cheaper on a large top-up, which matters when the fee is a percentage, but it settles in days rather than seconds and can fail after the wallet has apparently been credited. Options: cards only, and revisit on real fee data; ACH offered above a threshold amount; ACH offered everywhere, with the credit held until the transfer clears.
• Do representatives get a self-serve top-up surface on mobile? Today the only payment screen is on the dashboard, which does not serve representatives at all, so every top-up is staff-assisted. Options: build the essential-needs and wallet surfaces into the mobile app so a family tops up themselves; send a one-off payment link a representative opens in a browser; keep it staff-assisted permanently for agencies that prefer to stay in the conversation.