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 — the Wallet is built: the ledger, Stripe Connect onboarding, card top-ups on both the dashboard and the mobile app, drawdown on fund approval, and receipt reconciliation are all in code and run on staging, as are the per-household low-balance alert (WALLET-6), fund-request expiry (WALLET-8), and the end-of-care close-out (WALLET-11). No rule on this page is unbuilt. Four remain ⚠️ Partial — WALLET-2, WALLET-4, WALLET-10 and WALLET-19 — each with the missing half named on it, and WALLET-19 is the one that still matters most. Last audited against the code on 2026-08-15. It is not yet released to customers: production shows it as coming soon until it leaves the list of held-back modules (checked 2026-09-23). 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: 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.

The responsible party pays on their own device. The money is theirs, so the person it belongs to enters the card, in their own app, and nobody at the agency handles it. A family reaching a payment screen is not something an agency configures: the ability is inherent to being the responsible party, for the same reason that seeing the balance is (WALLET-5). Agency staff can still raise and collect a top-up from the dashboard — a family that would rather pay over the phone is a real household — but that is now one route of two, not the only one.

This replaces the original staff-assisted arrangement, where the payment screen lived only on the dashboard and a representative's card had to be read out to agency staff. That was a consequence of the mobile app having no essential-needs surface at the time, and it no longer does.

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. (✅ In code)

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. (⚠️ Partial — the mobile Wallet screens refuse a top-up while the device is offline, but platform-wide offline mode does not exist yet and the dashboard has no such gate.)

3. WALLET-3 — The system must notify the responsible party for every fund request. (✅ In code)

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. (⚠️ Partial — a request cannot close until every line is fully received, and a purchase records who, when, how many, the cost and any receipt photos. But the photo is optional, so nothing yet requires a receipt to exist.)

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. (✅ In code)

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. The minimum is agreed per household, not per agency, because a household that shops weekly needs a different floor from one that buys twice a year. The alert covers the band above zero: once a movement carries the balance below zero the agency has already fronted the money, and WALLET-21 owns what is said about it — the two must never both speak about the same movement. It is raised on the downward crossing, not repeated for a wallet resting under its floor, and never raised by a payment that improves the balance. (✅ In code)

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. (✅ In code)

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. The period is a needed-by date set by whoever raises the request — the care provider in the home is the only person who knows when the household runs out — and it is the request's urgency, shown to the family on the fund request and ordering their funding inbox, not merely an internal timeout. A request raised without one still expires, on a default window measured from the moment it reached the family. Management may extend the date while approving, but must never send onward a request whose date has already passed: it would arrive dead and be closed before anyone could answer. Expiry releases the request's items back to the household's list, and is recorded as Expired, never as Declined — nobody refused it, nobody answered it, and that distinction is the whole story months later. (✅ In code)

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. (✅ In code)

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. (⚠️ Partial — cards are live on both surfaces, including Apple Pay and Google Pay. ACH is not offered.)

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. Closing a client is therefore gated on the wallet: a balance within the de-minimis band is written off automatically with an entry, and anything larger refuses the close until somebody records what happened to it. The gate is about the record, not the amount — a wallet ending at zero with nothing explaining how is what this rule forbids, whether the figure was five dollars or five hundred. Because the platform never holds the money (WALLET-12), a card refund remains the agency's own action at the payment partner: the close-out records that decision and posts nothing, and the balance follows when the partner's confirmation arrives. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (⚠️ Partial — the prohibition is enforced where the platform can enforce it: a care provider holds no wallet permission and sees no balance. But nothing in the product hands the provider a way to pay at the till, so whether they front the money is still decided off-platform. When a care provider does front it anyway, they now say so on the purchase ("I paid myself", NEED-3), and Finance refunds it with their wages once the request completes, provided there is a receipt (FIN-12). The refund makes fronting visible and repaid; it does not make it acceptable. See Decisions needed.)

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. (✅ In code)

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. The balance is surfaced at all times, on every wallet screen; the alert is raised when the agency has just fronted more — a movement taking the balance below zero, or deepening a debt already there. A payment that reduces a debt without clearing it raises nothing, because answering a repayment with "you are overdrawn" is the one reply guaranteed to discourage the next one. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

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. (✅ In code)

26. WALLET-26 — An agency must be able to disconnect its payment account and run setup again from nothing — connecting the wrong account must not be permanent. But only while no payment has ever settled on it: once real money has moved, the connection is fixed, because the ledger must stay reconcilable against the partner's record of the account the money actually went through (WALLET-17). Disconnecting removes the platform's link only — the account itself remains the agency's at the fintech partner — and any payment still open on the account must be canceled there first, never left collectable against a connection the platform has forgotten. (✅ In code)

27. WALLET-27 — The responsible party must be able to raise and pay a top-up themselves, on their own device, for a household they are responsible for — without agency staff handling their card. The capability is inherent to the role and not agency-configurable, on the same reasoning as WALLET-5: a person answerable for a balance, told by WALLET-7 to top it up, must have a way to do so that does not depend on an agency's configuration or its office hours. Paying is not the same as editing: this must never carry the ability to credit a wallet directly or to post an adjustment, or a family could grant itself the money it is being asked to pay. Staff-raised collection remains available alongside it. (✅ In code)

Who can do what

On "care manager". The handbook uses the term throughout, but there is no care-manager role in the code — it is a custom role an agency defines. Wallet access therefore reaches a care manager only when the agency grants wallet:view or wallet:top_up to that role. Nothing about money is handed to them by default, deliberately: moving a family's money is an ownership responsibility, and an agency that wants to delegate it must say so.

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 now answers the end of care, but a family that topped up and then changed agency, or simply changed their mind, still 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. Note the close-out mechanism built for WALLET-11 is most of the machinery this needs; what it lacks is a way for the family to start it.
• 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.
• What does the care provider actually pay with at the till? This is the gap under WALLET-19, and it is the largest one on this page. The chain is complete from "the household needs bin bags" to "the receipt is filed" — except for the moment money leaves someone's hand. The wallet balance is a ledger figure, and the money it stands for is in the agency's Stripe balance, days from its bank account; the provider is in a shop. Nothing in the product says what happens next, so in practice the agency hands over a company card, or the provider fronts it and claims it back through payroll, or the agency orders online itself — and the platform cannot tell which. WALLET-19 is therefore a promise the code cannot keep. Options, in ascending order of effort: record the instrument on the purchase (agency card / provider fronted / ordered online), which enforces nothing but makes a provider paying out of pocket visible and chaseable rather than invisible; a provider reimbursement ledger, accepting that providers front money and tracking what the agency owes them, which fixes the real-world case but institutionalizes the very thing this module set out to end; or issued virtual cards — one per funded request, spend-limited to the approved total — which actually enforces WALLET-19 and makes reconciliation automatic, because the card authorization is the receipt, at the cost of a card program and per-agency onboarding on top of Connect. Open. Until it is answered, WALLET-19 stays ⚠️ Partial and the module's founding promise is honoured by convention rather than by construction. Since 2026-09-23 the first option is built and the second in part: a purchase records who paid (NEED-3), and Finance repays a care provider who paid with their own money through their wages (FIN-12). That turns fronting from invisible into visible and repaid; it does not stop it, so the question of what the provider pays with stays open.

Resolved. How long until an unanswered fund request expires (WALLET-8)? — per request, set by whoever raises it, as a needed-by date. Not a platform default and not a per-agency window: both of those describe the platform's patience, and the question a household actually has is when it runs out of something. Making it the requester's field turns a timeout into a piece of information the family is given — which is why it is shown on the fund request and orders the funding inbox, rather than sitting silently in a database. Requests raised without a date fall back to a one-week window measured from approval, so the rule still binds where nobody thought about urgency.

Resolved. Do representatives get a self-serve top-up surface on mobile? — yes, and it is built. The mobile app carries the wallet screen and a two-step top-up (amount, then Stripe's payment sheet with Apple Pay and Google Pay), reachable by the responsible party for their own household. Staff-assisted collection on the dashboard remains as the second route, for a family that would rather pay over the phone.