Reading per-user balances and payouts from Cenoa

Cenoa holds three things worth integrating: a per-user balance kept in named USD, EUR and GBP virtual accounts, an inbound payout ledger fed by Amazon, Etsy, Upwork, Wise, Fiverr, Shopify and direct ACH, and a settlement layer that books value as USDC on Circle's rails. The customer-facing app speaks fiat; the value actually moves as stablecoin underneath. Both halves are integrable. Which half you read depends on whether you are the account holder, the customer's accounting system, or — in a smaller number of engagements — Cenoa's institutional counterparty on the Circle side.

The route we usually take for a Cenoa build is authorized interface integration of the mobile app and its backend, run under a consenting user account that the customer either owns or has written user-consent for. That route reaches all of the data domains in the table below. We arrange access and the consent paperwork with the customer during onboarding; nothing about the engagement waits on the customer to assemble a sandbox first.

What lives inside a Cenoa account

The surfaces below are what the app actually exposes to its end users. Each row is a real screen or activity feed in the app; the third column says what granularity is recoverable and the fourth says what an integrator does with it.

Routes that actually work here

Authorized interface integration of the Cenoa app traffic

This is the route most Cenoa builds run on. We trace the iOS and Android client against its backend under a consenting account, produce a clean call inventory, and rebuild the auth chain (token issue, refresh, the rotating device-binding header). All seven domains in the table are reachable this way, including the granular gross/net split on marketplace payouts. Durability is good as long as the maintenance window stays funded — the app updates a few times a quarter on observed cadence and we re-verify the call graph on each release.

User-consented credential access

For customers who don't want to host an integration of their own, we sign in to Cenoa on behalf of the consenting user, fetch the same surfaces, and ship records onward. This is the simplest legal posture — the user is reading their own account through a delegated session — and it composes cleanly with NDAs and DPAs. The user-consent record is a deliverable; we don't operate without it.

AIS on the downstream landing bank

Where Cenoa is a stop in a larger flow — paid into Cenoa, withdrawn to a local bank account — the local bank is often inside its market's Open Banking regime (UK Open Banking under the FCA, PSD2 in the EU, Open Finance in Brazil, the Account Aggregator framework in India, and so on, depending on the user). When the customer needs the end-to-end picture rather than just the Cenoa leg, we wire AIS on the local bank alongside the Cenoa side.

Circle Mint at the partner layer

This route only applies if the customer is Cenoa's institutional counterparty rather than a consumer-side integrator. Circle Mint exposes mint, redeem, payouts and on-chain settlement views over USDC; we have integrated against it for partners who hold the issuance side and need both halves of the ledger to reconcile.

For a typical Cenoa customer the practical pick is the first route, with user-consented credential access as a fallback when the customer wants a hosted endpoint instead of source.

What lands on your machine at handoff

• OpenAPI 3.1 specification covering the endpoints we reverse-engineered: accounts, payouts, transfers, FX quotes, beneficiaries, profile/KYC status. Field-level types and examples, not just paths.
• Protocol & auth-flow report: how the bearer token is issued and refreshed; the 24-hour device-binding header chain; the cookie/CSRF posture; error envelopes; rate-limit observations.
• Runnable source in Python (httpx) and Node.js (undici), structured as a small client library with retries, paging, and the device-binding header threaded through. No copy-pasted snippets from this page — a real package.
• Automated tests against a consenting test account, covering balance read, payout ledger paging, an FX quote round-trip, and an outbound transfer in dry-run.
• Interface documentation: a README mapping every Cenoa screen to the call(s) that feed it, plus a normalized record schema that maps payouts onto ISO 20022 pacs.008 shape for ERP import, if you want it.
• Compliance & retention notes: what we recommend logging, what we recommend not storing, NDA/DPA templates ready to sign.

How the fetch loop looks in practice

Sketch of the read path against the Cenoa app's backend, with the device-binding header and the gross/net split on inbound payouts. Endpoints and headers shown are illustrative — confirmed during the build, not vendor-published.

# Illustrative — endpoints, headers and field names are confirmed during the build run.
import httpx
from cenoa_auth import bearer_token, device_header   # captured during onboarding

BASE = "https://api.cenoa.example/v1"   # real host pinned at build time

def list_accounts(session):
    h = {
        "Authorization": f"Bearer {bearer_token(session)}",
        "X-CN-Device":   device_header(session),   # rotates every ~24h
    }
    r = httpx.get(f"{BASE}/me/accounts", headers=h, timeout=15)
    r.raise_for_status()
    return [
        {
            "id":           a["account_id"],
            "currency":     a["currency"],           # "USD" | "EUR" | "GBP"
            "balance":      a["available_minor"] / 100,
            "pending_in":   a.get("pending_in_minor", 0) / 100,
            "partner_bank": a.get("partner"),        # e.g. "lead_bank" for USD
        }
        for a in r.json()["accounts"]
    ]

def list_payouts(session, account_id, since):
    h = {
        "Authorization": f"Bearer {bearer_token(session)}",
        "X-CN-Device":   device_header(session),
    }
    r = httpx.get(
        f"{BASE}/accounts/{account_id}/payouts",
        params={"since": since.isoformat()},
        headers=h, timeout=20,
    )
    r.raise_for_status()
    out = []
    for p in r.json()["payouts"]:
        out.append({
            "source":      p["origin"],              # "amazon", "etsy", "upwork", "ach", ...
            "gross":       p["gross_minor"] / 100,
            "net":         p["net_minor"]   / 100,   # after the marketplace's own fee
            "fx_rate":     p.get("fx_rate"),         # set if booked through a conversion
            "settled_at":  p["settled_at"],          # use this, not request time, for reconciliation
            "usdc_batch":  p.get("circle_settlement_id"),  # institutional view only
        })
    return out

Staying lawful across three jurisdictions

Cenoa is not itself a bank. Its US accounts are powered by Lead Bank with Stripe in the stack, per Cenoa's own partnership disclosures; EUR and GBP accounts sit with licensed European partners that Cenoa names selectively. The dependable legal basis we build on is the user's own authorization to access their own Cenoa account — the same posture the user already holds in the app — captured as a written consent record and the credentials needed to act on it.

On the US side, the CFPB's Personal Financial Data Rights rule under §1033 was finalized in late 2024 and then stayed in October 2025 by the court in Forcht Bank, N.A., et al. v. CFPB, with the Bureau opening an Advance Notice of Proposed Rulemaking to reconsider it. As of this writing the rule is not in force, so we do not present it as the operative US framework for a Cenoa build. The integration is structured so that if a successor rule is reissued in a form that covers Lead Bank's transaction accounts, the consent flow can be remapped without rewriting the data layer below it.

On the EU side, GDPR applies to the EUR account records, and UK GDPR plus FCA conduct rules apply to the GBP side via the European EMI partners. We minimize what's stored, log who read what when, and put an NDA and DPA in place before any account access starts.

Things the build has to account for

These are the specific items we work through on a Cenoa engagement — flagged here as engineering posture rather than as anything the customer needs to handle in advance:

• The 24-hour device-binding header. The Authorization bearer alone won't satisfy the backend for long-running sessions; the X-CN-Device value rotates and we re-derive it inside the client library so syncs that span more than a day don't silently start failing with 401s.
• Gross-vs-net on marketplace payouts. Amazon and Etsy land net of their own platform fee; Upwork and Fiverr land net of theirs. We expose both gross_minor and net_minor so the customer's accounting can reconcile from either direction — important when the same merchant is booked across platforms with different fee structures.
• Two-leg FX journal entries. A USD→EUR move books as a sell-USD / buy-EUR pair with a spread on each leg (Cenoa publishes the end-to-end cost as under 1% on its pricing posts). Treasury tools that expect a single conversion line will lose the leg; we model both legs and the markup as separate fields.
• The USDC layer is opaque on the consumer side. A regular Cenoa user only sees the fiat-equivalent balance. We treat USDC as the underlying rail and do not surface it for consumer integrations. When the customer is the institutional partner who actually mints or redeems, we add the Circle Mint side and the chain receipt cross-check.
• Re-verification cadence. Cenoa ships app updates every few weeks; the backend call graph holds across most of them, but a small fraction touch the auth chain. The maintenance subscription budgets for a re-verification pass per release so the field shape and the rotating header don't drift unannounced.

Concrete jobs this integration handles

1. A multi-marketplace seller wants one ledger. Amazon, Etsy and Shopify all pay into the user's Cenoa USD account; the build reads the activity feed, splits by origin, and posts a unified daily roll-up into the seller's accounting system with gross-and-net per source.
2. A remote-worker payroll platform wants confirmation. Wages are pushed into Cenoa USD via ACH or wire; the build checks the payout actually landed (matching gross, source, and settled_at), then flags any mismatch back for retry.
3. A small treasury wants FX visibility. The build polls the exchange screen for buy/sell rates and the published markup, logs end-to-end cost per leg, and surfaces an alert when the effective rate crosses a configured threshold.
4. An institutional Circle counterparty wants both halves. The build reads the Cenoa-side fiat ledger and the Circle Mint-side USDC settlement records, joins them on circle_settlement_id, and produces a reconciliation report.

The screens we mapped

The six images below are the publicly listed Play Store screenshots of Cenoa: Get Paid Globally. They double as a visual index of the surfaces the integration touches — open one in the lightbox to inspect the UI affordances we trace.

What we checked and where

For this brief we read Cenoa's published statements on its banking partners, the public coverage of Lead Bank's BaaS platform that powers the USD account layer, the Federal Register entry where the CFPB reopened the §1033 rule, and Circle's developer documentation for the USDC settlement side. The cited links below are the deep pages we worked from, not landing pages.

• Cenoa — How Cenoa partners with licensed banks and regulated entities
• PYMNTS — Lead Bank raises $70M to grow its BaaS platform (2025)
• Federal Register — Personal Financial Data Rights Reconsideration (CFPB, Aug 22 2025)
• Circle Developer — Circle Mint API (mint, redeem, settlement payouts)

Mapped by the OpenBanking Studio integration desk, May 2026.

Other apps in the same payout stack

Cenoa shares its category with several apps an integrator is likely to touch in the same engagement. Listed neutrally for orientation; a unified integration over more than one of these is a common ask.

• Payoneer — long-running virtual receiving accounts in USD, GBP, EUR and others; widely accepted across Upwork, Fiverr and large marketplaces; richer card programme than most peers.
• Wise — multi-currency holding accounts with publicly visible mid-market FX; primarily a transfer service, less a payouts hub.
• Grey — virtual USD, GBP and EUR accounts targeted at African freelancers; lighter on platform integrations than Cenoa or Payoneer.
• Cleva — Nigeria-focused virtual US account; overlaps with Grey on customer base.
• Revolut Business — multi-currency accounts and FX inside a broader business banking offer; UK and EU heavy.
• Airwallex — global business accounts with deeper treasury and card issuing; popular with mid-market e-commerce.
• Mercury — US business banking with international wires; common landing point for venture-backed companies.
• Deel — contractor payments and EOR platform that often pays into Cenoa, Payoneer or local banks downstream.
• Ruul — invoicing and payouts for freelancers in emerging markets, partnered with Cenoa for USD receipt in some flows.
• Remote — global payroll / contractor payments; another upstream feeder into wallets like Cenoa.

Questions integrators tend to ask about Cenoa

Which of Cenoa's three account types — USD, EUR or GBP — actually carries the data integrators usually want?

USD is by far the busiest because most marketplace payouts land there — Amazon, Etsy, Upwork, Wise, Fiverr, direct ACH. EUR is live for SEPA-tied flows; GBP for UK clients. We map all three with the same record shape, and the customer picks which one is wired into the build first.

Is the USDC settlement layer reachable, or only the front-end fiat view?

For the consumer side, what you read is the fiat-equivalent balance and the payout ledger — that's what the app exposes. If you are an institutional partner of Cenoa, the Circle Mint API and on-chain settlement records give the USDC side and we wire both layers. For non-partners, USDC stays as the underlying rail and does not appear in the integration surface.

Cenoa is not itself a bank — how does that shape the integration?

USD accounts are powered by Lead Bank with Stripe in the stack (per Cenoa's own partnership disclosures); EUR and GBP sit with licensed European partners. The integration speaks to the Cenoa account perimeter the user actually signed up for, and the dependable legal basis is the user's authorization to read their own account. We document the partner stack alongside the data layer so the two stay aligned.

Does the US Open Banking conversation (CFPB §1033) apply to a Cenoa build today?

The CFPB's Personal Financial Data Rights rule under §1033 was finalized in late 2024 and then stayed in October 2025 pending the agency's reconsideration; it does not govern this build today. The integration is anchored on the user's authorization to access their own Cenoa account. If §1033 is reissued in a form that covers Lead Bank's transaction accounts, the consent flow can be remapped without rewriting the data layer underneath.

How quickly do inbound marketplace payouts show up cleanly in the ledger?

Amazon and Etsy land as net of platform fees and Cenoa surfaces them in the activity feed within the same business day in our test runs; we map gross and net side by side so the reconciliation works from either direction. Direct ACH and Wise transfers behave similarly. We capture the settled_at timestamp from the activity record rather than the request time, which avoids the off-by-one when the cut-off straddles UTC midnight.

How we'd run this one

A Cenoa build usually lands in one to two weeks, with the USD account wired by default and EUR or GBP added on request. Source-code delivery starts at $300, paid after handoff once you're satisfied with what we shipped, and includes the OpenAPI spec, the Python and Node sources, the auth-flow report, the test suite and the interface README. If running the endpoint yourself isn't the right shape for your team, the same coverage is available as a pay-per-call hosted API with no upfront fee — you pay only for calls actually made. Scoping begins as soon as you give us the app name and the surfaces you need from it; everything else, including the consent paperwork and any sandbox arrangements, is handled with you during onboarding. Open a brief with us and we'll come back with the route, the timeline, and the deliverable list for your specific case.