Skip to content

Revolut Business

Created 2026-09-20; local enrollment added 2026-09-21. Doctrine Rev 17 with the active operator delegation.

ZeoCore reads a Revolut Business account: list accounts and read one bounded page of transactions. It never pays, transfers or changes settings.

You can use it on your own, with your own Revolut account, on your own machine, with no hosted service and no database. That is the local profile, described first. Organizations that prefer guided browser enrollment and managed custody can use the hosted profile through ZEOconnect instead.

Profiles are selected explicitly. Nothing falls back from one to the other: a hosted failure stays a hosted failure and never reaches for local credentials.

Live behaviour is unverified. Models, routes and the enrollment flow follow Revolut's published Business API description and are exercised against offline fixtures only. No sandbox or production request has been made by this code.

Local profile: enroll your own account

Install the extra, which adds cryptography for the client key and certificate:

pip install "zeocore[revolut]"

Start with managed environments. Configuration, and only configuration, may come from .env or the launcher:

Variable Meaning
REVOLUT_ENVIRONMENT sandbox or production. Separate enrollments.
REVOLUT_REDIRECT_URI An https URL you control or simply own the name of.
REVOLUT_CLIENT_ID Issued by Revolut after step 1. Not a secret.

No variable holds the private key or a token, and none is read. Those live in owner-only files (mode 0600, directory 0700) under the selected managed environment, or under your per-user configuration directory, in revolut/<environment>/. The store refuses a directory inside a git repository, a symlink, or a file other users can read.

Revolut issues a client id only after you register a certificate by hand, so enrollment is three explicit steps:

# 1. Create your key and certificate, then upload the certificate at
#    Revolut Business -> Settings -> APIs -> Business API, with the same
#    redirect URI. Revolut shows you a client id.
python -m zeo_core.integrations.revolut.local setup --redirect-uri https://example.com/revolut

# 2. Record the client id. Open the URL it prints and approve READ access.
python -m zeo_core.integrations.revolut.local authorize --client-id <client id>

# 3. Revolut redirects your browser to the redirect URI with a one-time code.
#    The page need not exist: copy the address bar and paste it here. This is
#    the one human step: only you can copy that address. In a terminal the
#    input is hidden so the code does not land in your shell history.
python -m zeo_core.integrations.revolut.local complete
#    Without a terminal it reads the first line of stdin instead, so a
#    program can pipe the URL; later lines are ignored. Never pass the URL as an
#    argument: the code would show in process listings and shell history, and
#    `complete` refuses an argument without echoing it. Pipe it from your own
#    shell without writing it into a command line or a variable:
pbpaste | python -m zeo_core.integrations.revolut.local complete
#    or read it silently:  read -rs URL; printf '%s\n' "$URL" | ... complete
#    A pipe that sends nothing, or stops before the line ends, for 30 seconds in
#    all is refused; `< /dev/null` is refused at once.

python -m zeo_core.integrations.revolut.local status     # never prints a secret
python -m zeo_core.integrations.revolut.local accounts   # first live check

Exit codes. 0 done. 2 the input was not accepted and nothing was sent: a usage error, CLIENT_ID (an authorize --client-id that looks like an address, so it is refused without echoing it), or REDIRECT_URL (no usable first line on stdin, a first line over 8192 bytes or that is not UTF-8, a pipe that is silent or stops mid-line, no stdin at all, an address that urlsplit rejects, or a URL given as an argument). Text that is a well-formed address but not Revolut's redirect, and plain words, are not REDIRECT_URL: they end as CONSENT_MISMATCH, exit 1. 1 every other refusal of this module (NOT_SET_UP, CONSENT_MISMATCH, EXCHANGE_*, store errors); these older refusals keep 1. Every REDIRECT_URL message ends with what to do, and none quotes the address.

The same steps are available in Python as LocalRevolutEnrollment(environment).setup(...), .authorize(...), .complete(...). The JWT iss Revolut checks is the host of your redirect URI.

Reading

from zeo_core.integrations.revolut import RevolutEnvironment, TransactionQuery
from zeo_core.integrations.revolut.local import LocalRevolutEnrollment

revolut = LocalRevolutEnrollment(RevolutEnvironment.SANDBOX)
accounts = revolut.read(lambda client: client.list_accounts())
page = revolut.read(
    lambda client: client.list_transactions(TransactionQuery(from_=since, count=200))
)

read runs one logical operation with at most one token refresh and one repeat, including the proactive refresh shortly before expiry. Do not wrap it in your own retry.

Local does not mean race-free

Two of your scripts can share these files, and a process can die after Revolut has processed a refresh. Revolut invalidates the previous access token when it refreshes, so a lost answer leaves the client unable to say whether its stored token still works. The client therefore:

  • takes an exclusive file lock for the whole operation, so two local processes never refresh at once. POSIX only;
  • writes a marker durably before a refresh request is sent, and removes it only once a definite answer is stored;
  • treats a marker found later as an unknown outcome. That state is blocked: nothing refreshes again, however long you wait, because waiting proves nothing about what Revolut did. The stored token keeps serving reads while Revolut accepts it;
  • reports what it observed, never a diagnosis. OUTCOME_UNKNOWN, GRANT_REFUSED and TOKEN_REJECTED do not establish that you revoked consent. UNAVAILABLE means nothing reached Revolut and nothing changed.
  • holds the file lock only on your machine. It says nothing about what Revolut is still processing.

What a fresh consent does and does not do. Running authorize and complete again on the same registration gives you new tokens. It answers a GRANT_REFUSED or a TOKEN_REJECTED, which are definite answers, and clears them. It does not clear an unknown outcome: your consent authorizes new tokens, it does not settle what Revolut did with the request whose answer was lost. The new access token serves reads while it is valid and accepted; refreshing stays blocked.

There is no qualified recovery from an unknown outcome yet. You can start a new registration with setup --new-key, which discards every stored token, creates a new key and certificate, and needs a new client id from Revolut. That is a fresh local binding. It is not established that a new key and client id, or deleting the old certificate in Revolut Business, isolates the new registration from a late refresh of the old one; this has not been verified against Revolut and this guide does not promise it. The new enrollment records follows_unresolved_refresh so status keeps saying so. Removing local files alone removes nothing at Revolut.

An enrollment belongs to its environment. Files written for sandbox are refused for production, and the reverse, with ENVIRONMENT_MISMATCH, before any client is built or any credential is sent. This holds even if you copy a directory or pass a store explicitly. Moving to another environment is an explicit setup --new-key there, never a reinterpretation of existing secrets.

Hosted profile: ZEOconnect

RevolutBusinessClient holds no credentials of its own. A credential owner constructs it with a current access token:

Concern Owner
Typed operations, fixed-origin transport, normalization The client, in both profiles
Key, certificate, consent, exchange, refresh, files The local profile above, for one person
Guided enrollment, custody, coordinated refresh across workers, revocation ZEOconnect, for the hosted profile
Paging loop, checkpoints, deduplication, evidence storage, matching The consuming application

Hosted enrollment is not yet admitted; the setup catalogue reports its state.

From 0.14.0, HostedRevolutBusinessClient makes the same two reads through ZEOconnect, with the credential held by the Broker (Broker contract 1.0.0 ยง6). It is read-only and never makes a payment. Pass it a HostedConnectionClient and the connection's id:

from zeo_core.integrations.revolut import (
    HostedRevolutBusinessClient,
    TransactionQuery,
)

revolut = HostedRevolutBusinessClient(client, connection_id=connection_id)
accounts = revolut.list_accounts()
page = revolut.list_transactions(TransactionQuery(from_=since, count=200))

Paging works as with the direct client. Two wire rules apply: the query's start field is sent as from, and every amount must arrive as an exact decimal string. A result that carries a JSON number is refused, not rounded. A Broker stop raises HostedStoppedError. Error codes from the client are sanitized categories, not diagnoses: AUTHENTICATION (401) does not establish that a token expired, and ACCESS (403) does not establish that a connection was revoked.

Using the client directly

from pydantic import SecretStr
from zeo_core.integrations.revolut import (
    RevolutBusinessClient,
    RevolutEnvironment,
    TransactionQuery,
)

client = RevolutBusinessClient(token, environment=RevolutEnvironment.SANDBOX)
try:
    accounts = client.list_accounts()
    page = client.list_transactions(TransactionQuery(from_=since, count=200))
    while page.next_to is not None:
        page = client.list_transactions(
            TransactionQuery(from_=since, to=page.next_to, count=200)
        )
finally:
    client.close()

token is a SecretStr supplied by the credential owner. environment selects one of two fixed origins; a caller can never supply a provider URL.

Expenses, receipts and labels (from 0.13.0)

Read-only, like the rest of the client. Offline contract only: the shapes come from Revolut's published OpenAPI contract, and none of these reads has been made against a real account.

from zeo_core.integrations.revolut import ExpenseQuery, LabelQuery

page = client.list_expenses(ExpenseQuery(from_=since, count=200))
expense = client.get_expense(page.expenses[0].id)
receipt = client.download_receipt(expense.id, expense.receipt_ids[0])
groups = client.list_label_groups(LabelQuery(limit=100))
labels = client.list_labels(str(groups.label_groups[0].id))
  • Expenses page like transactions: one page per call, with next_to as the next to, PAGINATION_STALLED when a full page does not advance, and count up to 500. Replace stored expenses by id.
  • Which date the window filters on is not stated in Revolut's published contract. next_to is derived from the oldest expense_date, and that choice is unverified until a live sandbox run. If it is wrong, a page can start past expenses that were never returned. Replacing by id removes duplicates, but it cannot recover a skipped expense.
  • So an expense read is never reported complete. Every ExpensePage carries completeness="unverified". Reaching next_to=None means Revolut returned a short page, not that every expense in the window was read. Record an expense sync as potentially incomplete, and do not use it to conclude that an expense does not exist.
  • Labels and label groups page by an opaque next_page_token. Pass it back unchanged as LabelQuery(page_token=...). limit goes up to 500, and a token that does not change raises PAGINATION_STALLED.
  • A receipt is read whole and bounded while it is read, to MAX_RECEIPT_BYTES (10 MiB, equal to the hosted artifact limit). It is returned as Receipt(content, media_type, sha256, observed_at). Its bytes are never parsed, logged or shown in repr.
  • Redirects are never followed. A 3xx is refused (HTTP, with its status code), so the access token goes only to Revolut's fixed origin, never to a host a response names.
  • An identifier that is not a single safe path segment ([A-Za-z0-9_-], at most 100 characters) is refused before any request is sent.

Paging contract

Revolut's published description pages transactions by a from/to window on created_at with a count, and has no cursor token. list_transactions returns one page. When the page is full, next_to is the oldest created_at in it, computed without assuming any provider ordering; pass it as the next to.

A page is an observation, not a snapshot. The same window and cursor can return different records later: transactions change state, and new ones can appear inside a window already read. Each page carries observed_at.

  • Key stored transactions by id. A projection with a later updated_at replaces the earlier one; keep earlier observations as history, do not discard them as duplicates.
  • Adjacent pages can overlap at next_to. Whether Revolut treats to as inclusive, how it orders results and how it breaks created_at ties are unverified against the live API; replacement by id is what makes the loop safe under any of those answers.
  • Progress is detected, not assumed: a full page whose oldest instant does not move below the requested to raises PAGINATION_STALLED. Narrow the window or raise count (maximum 1000).
  • Any error means the window was not fully read. Record an incomplete sync with the last good cursor; never report completion.
  • There is no collect-everything helper.

Size bounds

A bounded count does not bound bytes, so both sides are bounded explicitly.

  • The upstream body is streamed and abandoned once it passes MAX_UPSTREAM_BYTES (8 MiB), before any parsing. Error bodies are never read.
  • The normalized, serialized result must fit MAX_RESULT_BYTES (768 KiB, below the 1 MiB hosted JSON limit with room for its envelope).

Either breach raises RESPONSE_TOO_LARGE and returns nothing. Results are never truncated: a silently shortened page would lose evidence needed for matching. Lower count or narrow the window and read again.

Normalization

Results carry normalization_version = "revolut-business-read-1".

  • Amounts are parsed from JSON numbers directly into Decimal; they never pass through a binary float.
  • Provider fields not declared by the models are dropped. From card, only the card id is kept: card number, holder name and phone are discarded.
  • Provider enumerations (type, state, account_type) are kept as bounded lowercase tokens, so a new provider value does not fail a whole page.
  • From an expense, payer (a person's name) is dropped, as a card holder's name is.

This output is normalized application data. It is not raw provider evidence and must not be stored or labelled as raw.

What the credential tests do and do not show

Only declared, typed fields leave the client, errors carry fixed messages with no provider body, URL or validation detail, and representations of the client, transport and errors omit the token. Tests plant a canary credential and check those outputs, malformed and undecodable responses, and debug-level logs.

That shows the supplied credential does not leak through the exercised paths. It does not show that provider text can never contain some other token-like value: free-text fields such as reference are passed through as data. As defence in depth, a response containing the request's own token is refused; this is not a general secret scanner.

Test account track

Use a Revolut Business sandbox account with REVOLUT_ENVIRONMENT=sandbox. The sandbox has its own certificate registration, client id and consent, fully separate from production, and its own directory of private files.

Production account track

Set REVOLUT_ENVIRONMENT=production and enroll again from step 1: a production enrollment shares nothing with a sandbox one. Approve READ access only. If your Revolut account enforces an IP allowlist, register the address you read from.

Bounded E2E

Not yet run. After enrolling, python -m zeo_core.integrations.revolut.local accounts is the first live check. Then: list accounts, read one page of at most ten transactions from a one-day window, and confirm that amounts match the Revolut web interface to the minor unit. Record the environment, date and outcome alongside the change that claims it.