Mapping the USHG Digital Wallet payout stream into back-office systems

Underneath the USHG-branded shell sits Branch's embedded worker-payments platform; the Mastercard debit and the demand-deposit account are issued by Evolve Bank & Trust, per Branch's own disclosure for this program. That means the integration surface that matters here is not a consumer-facing portal — it is the Branch payouts engine. The dominant data flow is tip-payout events at end-of-shift, with on-demand pay advances as a second event family. Treat the wallet as a presentation layer; ingest at the rail.

Where the data sits inside the wallet

Routes we'd take to reach it

Route 1 — Direct Branch webhook integration (sponsor / employer side)

Reachable: payout events, advance events, card-transaction notifications, balance-change events. Effort: medium — registration with Branch via the customer-support flow, AES-CBC key exchange, handler implementation. Durability: high; this is the rail's native push channel and is documented on Branch's developer site. What we set up alongside the client: the Branch registration itself, key provisioning and rotation policy, a sandbox test rig, and the production cutover plan.

Route 2 — Authorized interface integration of the wallet client (user-consented)

Reachable: per-user wallet state, transaction history visible to the end user, profile fields the worker sees. Effort: medium. We do the protocol analysis, map the auth handshake and request signing, and normalize the response shapes. Durability: medium — depends on Branch client updates, so the build ships with a regression suite that fails noisily when the wire format moves.

Route 3 — User-consented credential access on the sponsor admin portal

Reachable: employer-side reporting, roster state, scheduled exports. Lower effort, narrower data shape than route 1. Useful when the goal is finance reporting rather than per-worker eventing, and when the sponsor wants the integration to live entirely on the admin surface they already control.

For a back-office build, route 1 is what we'd actually use — it is the route the platform itself documents and the one that produces the cleanest reconciliation pattern. Routes 2 and 3 come into play for an end-user app, or for filling in fields the webhook stream doesn't carry.

What lands in your repo

• Runnable webhook handler in Python (FastAPI) and Node.js (Express) — receives, AES-decrypts, validates the envelope, normalizes the event, and writes it through an idempotent ledger keyed on Branch's event ID.
• Sync engine: push (webhook) plus pull (Branch developer API) reconciliation worker for backfill, gap detection, and out-of-order delivery.
• Automated test rig with recorded fixtures — replayable encrypted payloads — so CI doesn't depend on Branch's sandbox staying up.
• SDK-style client module with typed bindings for Python and TypeScript, wrapping the payout, advance, transaction, and balance objects.
• A small admin runbook covering key rotation, replay-window tuning, and the cutover playbook between sandbox and production.
• OpenAPI document for the normalized internal surface we expose downstream, so your other services don't talk Branch types directly.
• Auth-flow report on Branch's customer-support key provisioning and the decrypt chain.
• Compliance and data-retention notes for the EWA portion: covered-EWA criteria, fields we persist, fields we drop, audit-trail layout.

A look at the webhook handler

This is the shape of the core handler — field names and event types are illustrative here and pinned to the actual wire format during the build.

# Webhook handler for the Branch-powered USHG Digital Wallet
# Illustrative; envelope keys, event types and field names are confirmed
# against the live sandbox during the build.

import json
from base64 import b64decode
from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
AES_KEY = load_key("ushg_wallet_branch")  # provisioned via Branch CS flow

@app.post("/webhooks/ushg-wallet")
async def handle(req: Request):
    envelope = await req.json()
    try:
        ct  = b64decode(envelope["data"])
        iv  = b64decode(envelope["iv"])
        cipher = AES.new(AES_KEY, AES.MODE_CBC, iv)
        payload = json.loads(unpad(cipher.decrypt(ct), AES.block_size))
    except (KeyError, ValueError):
        raise HTTPException(400, "bad envelope")

    if replayed(payload["event_id"], payload["emitted_at"]):
        return {"status": "duplicate"}

    if payload["type"] == "tip_payout.posted":
        record_tip(
            employee_id = payload["employee_ref"],
            shift_id    = payload["shift_ref"],
            gross_cents = payload["gross_cents"],
            posted_at   = payload["posted_at"],
        )
    elif payload["type"] == "advance.disbursed":
        record_advance(
            employee_id  = payload["employee_ref"],
            amount_cents = payload["amount_cents"],
            period_id    = payload["pay_period_ref"],
        )
    elif payload["type"] == "card_txn.posted":
        record_card_txn(payload)
    # additional event types added as the sponsor program scopes them
    return {"status": "ok"}

Engineering notes we account for

Sponsor-scoped eligibility, kept as data not code

The USHG program is sponsor-scoped: eligibility for the tip-payout flow and for the on-demand pay advance is set per the USHG agreement (the program disclosure cites approximately 51% of tip earnings auto-deposited, and advances against accrued non-tip wages capped around $1,000 per pay period). We code those rules as a versioned eligibility table the worker reads at event time, not as if-trees scattered through the handler. When a sponsor changes a cap or a split, the change is a row, not a re-cut.

AES key rotation and replay handling, designed in from day one

Branch ships a single AES-CBC key per integration via its customer-support flow. We hold two keys simultaneously during cutover, accept the older one for a configurable grace window, and key replay protection off the event ID plus a sliding timestamp window. The replay table is kept separate from the business-idempotency table, so a legitimate Branch rebroadcast of a real event isn't silently dropped as a duplicate of itself.

Reconciling the rail with the POS

Tip totals on the POS side and tip totals on the wallet side don't always agree to the minute — the wallet sees only the share the worker opted into; the rest still routes through the legacy payroll path. The reconciliation worker knows both sides and flags any difference that isn't the expected split, instead of swallowing it. That single check has caught the most real bugs in our prior hospitality builds.

Regulatory posture for a US paycard with EWA

On the banking side the wallet is a Mastercard demand-deposit account issued by Evolve Bank & Trust under a Branch program — FDIC posture, KYC, BSA/AML, and dispute handling sit with the issuing bank. The integration we deliver does not move money on its own; it ingests, normalizes, and persists events the issuer's program generates.

On the earned-wage-access side, the relevant current anchor is the CFPB's December 2025 advisory opinion, which holds that qualifying EWA — non-recourse, no credit-risk assessment, capped at accrued wages — is not "credit" under TILA and Regulation Z, and that voluntary tips and optional expedited-delivery fees are not finance charges. Branch's USHG program reads as the covered EWA model. The auth-flow report still flags which event fields would need different treatment if a state regulator or your auditor takes a different view.

Federal data-rights rulemaking for personal financial data (CFPB 12 CFR Part 1033) is unsettled at the time of this writing — enforcement enjoined, the rule back in agency reconsideration. We do not anchor the consent story on a settled federal data-portability obligation that does not exist; the dependable basis here is the worker's own authorization, captured through the wallet's onboarding and through whatever sponsor-side consent surface the back-office build exposes. Operationally: authorized access only, logged consent records, data minimization on what we keep, and an NDA where the client wants one.

Screenshots referenced during the mapping

Other paycard and EWA platforms we map

• DailyPay — gross-to-net earned wage access for hourly workforces; the integration target is payout events, balance, and pay-period state.
• Payactiv — EWA paired with bill pay and savings; the data model includes earned-balance ledgers and merchant-bill rails.
• EarnIn — consumer-side EWA without a required employer integration; bank-link and timesheet data drive the eligibility check.
• Tapcheck — employer-side EWA; webhook delivery of advance events and payroll-deduction recovery records.
• ZayZoon — EWA bundled with gas cards and a debit wallet; payout, gift-card load, and advance events sit alongside the wage objects.
• Rain Instant Pay — direct-deposit-based EWA with employer integration; pay-cycle and advance objects.
• Clair — neobank-style EWA with a Mastercard debit and a sponsor-bank model close to USHG's; account, transaction, and advance events.
• Even (now part of One) — EWA and budgeting platform; pay-period and instant-pay events sit at the integration boundary.

Questions integrators ask us

When do tip-payout events fire from the Branch backend?

Per the case study Branch published with USHG, tip payouts move into the wallet shortly after end-of-shift close — opt-in employees see 51% of their tip earnings post automatically, as Branch describes the program. The Branch webhook surface emits an event when funds clear; we wire that to your reconciliation table so daily totals don't drift between the POS and the wallet.

Can we get balance and card-transaction data, or only payout events?

Both are reachable. Wallet balance and Mastercard debit transactions are issued by Evolve Bank & Trust under the Branch program, per the official disclosure; the same webhook channel carries auth, capture, and posted-transaction events. For historical pulls we use the Branch developer API rather than the live stream, and reconcile the two.

How are the AES-encrypted webhook payloads handled in your reference code?

Branch's developer documentation describes AES with CBC mode and PKCS5 padding; the shared key is provisioned through their customer-support flow. Our reference handler decrypts on receipt, validates the envelope timestamp, and rejects replays — the code ships in Python (FastAPI) and Node.js (Express) so you can drop it into whichever runtime your back office uses.

Is the on-demand pay advance treated as a loan we need to report on?

Under the CFPB's December 2025 advisory opinion, qualifying earned wage access — non-recourse, no credit-risk assessment, capped at accrued wages — sits outside Regulation Z. Branch's USHG program reads as the covered EWA model, but we still flag in the auth-flow report which event fields would need reclassification if a state regulator or your auditor takes a different view.

What was checked

Sources read between 26 and 27 May 2026: Branch's own legal/program page for the USHG Digital Wallet, the Branch case study on the USHG rollout, the public Branch developer docs on webhook implementation, and the U.S. Federal Register notice of the December 2025 CFPB advisory opinion on earned wage access. Where a fact wasn't in those sources, this brief says so rather than guesses.

• Branch — What is USHG Digital Wallet (program disclosure)
• Branch — Union Square Hospitality Group case study
• Branch Developer — Webhook implementation
• U.S. Federal Register — CFPB advisory on EWA under TILA / Regulation Z (23 December 2025)

Mapping reviewed 27 May 2026 by the OpenFinance Lab integration desk.

Source delivery on a build like this starts at $300, paid only after the working code is handed off and you're satisfied with it; if you'd rather not host anything, the same surface is available as a pay-per-call hosted endpoint with no upfront fee. Either way the build cycle runs one to two weeks, and access provisioning — Branch sandbox enrollment, key handover, sponsor-side authorizations — is arranged together with you during onboarding rather than treated as paperwork you have to clear before we start. Reach the integration desk via the contact page.

Mapping reviewed 2026-05-27