Reaching the shared ledger behind a Heypenny group

The interesting surface on Heypenny is not the on-device receipt scan — that part stays on the phone. It is what happens once a person taps "add to group". The parsed line items, the per-member claims, the tax-and-tip allocation, and the running balance are pushed to Heypenny's backend so every other member sees the same ledger. That backend group is the integration target.

Heypenny sits in the receipt-scan-and-split corner of the bill-splitter category. The free flow stays local; the paid flow — groups, multi-currency, settle-up via Venmo, cross-device sync — is what most integrators actually want pulled. The page below treats the premium ledger as the spine of the work, with the settle-up tap modelled as a separate handoff.

What sits on Heypenny's servers, and what does not

Separating the two matters. An integration that assumes everything is server-side will miss receipts a user never added to a group; one that assumes nothing is server-side will miss the only data worth syncing. The split, as the app describes it:

What is not on the server: a raw image of a scanned receipt that a user never shared. Per the published policy, OCR runs locally. So a complete archive of a member's scans is only available from the device, not from the backend. We call that out so nobody scopes a build around something the backend never had.

Authorized routes into the data

Three apply here, and they compose.

1. User-consented session access on the member's account

The cleanest route. The member logs in once during onboarding (a real Heypenny account they own), we capture the resulting session credential, and a worker pulls their groups, expenses, balances, and settle-up history on a cadence the calling system controls. Built for one user; scoped to the groups that user is already in. Durability tracks how Heypenny rotates its session tokens — manageable, and the worker treats sign-out as a clean stop.

2. Protocol-level mapping of the sync traffic

Used to build route 1 properly. We instrument the app against a consenting test account, watch the calls it makes when a group is created, an expense is added, a member is invited, and a settle-up is tapped, then write that traffic up as an auth and request/response contract. This is interoperability work on data the customer's own user has authorized — we do not bypass authentication; we follow it.

3. Native export pairing

For one-off pulls — a trip is closing out, a housemate is moving — sharing the group's summary image or its in-app expense list is sometimes enough. We wrap that as a fallback for when continuous sync is overkill.

For most asks the recommendation is route 1 with route 2 as how we get there. Route 3 is offered when the customer's use case is genuinely one-shot.

Sample call against the group ledger

Illustrative shape, confirmed during the build against a real consenting account. Endpoint names are mapped during the protocol pass.

# heypenny_pull.py — pseudo-code; field names are mapped during the build

import requests, os

BASE = "https://api.heypenny.money"  # actual host confirmed at build time
SESSION = os.environ["HEYPENNY_SESSION"]  # captured from the user's consenting login

headers = {
    "Authorization": f"Bearer {SESSION}",
    "Accept": "application/json",
    "User-Agent": "heypenny-ios/1.x (integration via OpenBanking Studio)",
}

def list_groups():
    r = requests.get(f"{BASE}/v1/groups", headers=headers, timeout=10)
    if r.status_code == 401:
        raise PermissionError("session revoked — stop and request re-consent")
    r.raise_for_status()
    return r.json()["groups"]  # [{id, name, base_currency, member_ids}, ...]

def group_expenses(group_id, since_iso):
    params = {"updated_since": since_iso, "limit": 100}
    out = []
    while True:
        r = requests.get(f"{BASE}/v1/groups/{group_id}/expenses",
                         headers=headers, params=params, timeout=10)
        r.raise_for_status()
        body = r.json()
        out.extend(body["expenses"])
        if not body.get("next_cursor"): break
        params["cursor"] = body["next_cursor"]
    return out  # each: {id, paid_by, total, currency, fx_rate_at_entry,
                #        tax, tip, line_items:[{label, amount, claimed_by:[...]}]}

def settle_ups(group_id):
    r = requests.get(f"{BASE}/v1/groups/{group_id}/settle_ups",
                     headers=headers, timeout=10)
    r.raise_for_status()
    # Heypenny records the IOU and the Venmo handoff; pair with Venmo OAuth
    # to confirm the matching real-money transfer cleared.
    return r.json()["settle_ups"]

The pagination shape, the field names, and the precise auth header are nailed down during the protocol mapping; the snippet above is the skeleton we hand a client so they know what they will be holding.

What ships at the end of the build

• An OpenAPI document for the Heypenny surface that was reached — groups, expenses, members, balances, settle-ups — with the exact field names confirmed on-account.
• A short protocol and auth-flow report: how login is held, how the session is refreshed, what a 401 means in practice, what the Venmo handoff actually contains.
• Runnable source for the pull worker in Python and Node.js, with the consent token treated as a managed secret and a clean stop on revocation.
• A test suite that exercises the live calls against a sandbox member account so the contract is checked, not assumed.
• An interface document covering currency handling, the line-item-to-claimant mapping, and how to reconcile a Heypenny IOU with a Venmo payment.
• A short retention and data-minimization note for the customer's compliance file.

Engineering details we account for

A few choices that are specific to this app and shape how the build is scoped:

• Local vs synced split. We design the pull to read only the synced ledger, never the on-device receipt image store, so the integration's view matches what the user has actually shared with the group. Unshared scans are out of scope by construction — not by policy excuse, by how the app works.
• Currency rate at entry. The group's base currency and the entry's original currency are joined by a snapshot rate at the moment the expense was added. We preserve that snapshot in our normalized record so a later FX move does not retroactively rewrite a settled-up history.
• IOU vs payment. A "settle up on Venmo" tap inside Heypenny produces a prefilled Venmo intent — it is not, on its own, evidence the payment cleared. We model the IOU and the cleared transfer as two records, and pair the Heypenny pull with a per-user Venmo OAuth call when the customer needs confirmation rather than intent.
• Re-validation pass on app updates. Heypenny is an actively developed indie app; field names and the sync envelope can shift between releases. The maintenance contract covers a quick re-validation against a sandbox account when a new version ships, so the worker stops silently drifting.
• Multi-currency members. One group, several members each entering in their local currency, is a real shape this app supports. We scope the normalized schema so a single expense can carry both the entry currency and the group's reporting currency without collapsing them.

Consent, US privacy law, and Venmo's terms

Heypenny is a US-based indie product (Moelten, a sole-developer studio) and its privacy policy is plain: data not sold, not used for advertising, only what the app needs to run. A US consumer-rights regime (state-level laws like the CCPA / CPRA in California, comparable laws elsewhere) governs what a member can ask of any party holding their data, including a downstream integration. That is the frame we work in.

The dependable legal basis on the page is the member's own consent: a real Heypenny user, signing in to their own account, authorizing the integration to read the groups they are already in. We record that consent, scope the pull to those groups, and stop on sign-out. There is no third-party open-banking regime that applies here — this is not a regulated bank account — so the architecture is consent-and-contract, not scheme-mandated access. The Venmo handoff is governed separately by Venmo's developer terms; the studio handles the Venmo OAuth registration and the matching disclosure inside the build.

NDA and a short data-processing addendum are standard. Access onboarding — getting a consenting test member, agreeing the data we may store, agreeing the retention window — is arranged with the client as part of week one.

How a Heypenny build runs

Source-code delivery for a Heypenny group-ledger pull starts at $300, paid only after the runnable code is in your hands and you have run it against your own member account. The alternative is the hosted route: call our endpoint for the same data, pay per call, no upfront cost and we run the worker. Most one-team builds finish inside one to two weeks for the first usable cut. Talk to us at /contact.html with the group shape you want covered and we will scope it back the same day.

Sources checked

The factual claims above were checked against, in order of weight: the developer's product site, the published privacy policy, the Google Play listing, and Venmo's developer documentation for the settle-up handoff. Specific deep links:

• heypenny.money — product description, premium feature list.
• heypenny.money/privacy-policy — data collection and minimization posture.
• Google Play listing — developer name, package id, current feature copy.
• venmo.com/developers — Venmo OAuth and settle-up integration model.

Reviewed 2026-05-29 by the OpenBanking Studio integration desk.

Keeping the pull working

Indie apps move fast. The maintenance habit is small and steady: re-run the test suite against a sandbox member account when a new app version ships, diff the response shapes, patch the worker if a field renamed. We also watch the privacy policy and the Venmo handoff terms — both can change without a release note in the app. Customers on the hosted route get this work folded in; customers on source-code delivery can buy it as a small retainer or run it themselves with the test suite we shipped.

Sibling apps in the splitter category

If you are integrating Heypenny you are probably also looking at the rest of this category. Same data shape — groups, expenses, balances, settle-ups — different surface choices.

• Splitwise — the category benchmark; deepest published developer surface, group/expense/user pulls broadly comparable to what is described here.
• Tricount — strong multi-currency, trip-centric ledgers, popular in Europe.
• Settle Up — flexible split rules (percentages, custom ratios), itemized splits.
• Splid — no-sign-up trip ledgers, 150+ currencies, offline-first.
• SplitMyExpenses — web-first expense sharing with bank-card reconciliation in mind.
• PartyTab — event-and-tab style splits, often used for one-off gatherings.
• Cino — couples and small-household budgeting overlaid on shared spending.
• Splitterup — newer entrant focused on tidier UX over Splitwise's accumulated feature set.

Routing those into one normalized "shared ledger" schema is a common follow-on; the modelling we use for Heypenny groups/expenses/balances/IOUs lines up with what each of the above exposes in some form.

Questions integrators ask about Heypenny

Does Heypenny keep the parsed receipt line items on its servers, or only the totals?

The receipt OCR runs on the device, so the line-item parse happens locally. Once a member adds the parsed items to a shared group, the items, who claimed what, the tax/tip split, and the running balance are synced to the Heypenny backend so other group members see them — that synced shape is what an integration reads back.

Can a pull capture the actual Venmo settlement, or just the IOU Heypenny generated?

Heypenny's role ends at handing off a prefilled Venmo amount and memo to the Venmo app; whether the user tapped pay and Venmo settled is on Venmo's side. We model the IOU and the settle-up tap separately, and if you need the actual cleared payment we pair the Heypenny pull with a Venmo OAuth call against the same end user.

What happens to a long-running sync when a user signs out of Heypenny on their phone?

Sign-out should invalidate the session token the integration is riding on. We design the worker to treat a 401 as terminal for that user — stop, drop the token, log the revocation, and surface it to the calling system rather than retrying. Re-consent is a fresh login.

From kickoff to runnable code, how long is a typical Heypenny build?

One to two weeks for the first usable cut against a consenting account, including the OAuth-style login mapping, the group and expense pulls, and a small test suite. Edge work — multi-currency reconciliation, IOU-to-Venmo bridging — fits inside that window for one group shape.