Python SDK

Thin Python client for the fednow-gateway REST API — stdlib only, zero runtime dependencies.

import os
from fednow_client import GatewayClient, ProfileViolation

gw = GatewayClient("http://localhost:8090", api_key=os.environ["FEDNOW_GW_API_KEY"])

payment = gw.submit(
    "order-2026-0001",                 # idempotency key — mandatory by design
    reference="ORDER0001",
    amount_cents=125_000,              # integer cents, never floats
    debtor_name="Jane Example",   debtor_account="123456789012",
    creditor_name="John Example", creditor_account="987654321000",
    creditor_agent_routing_number="992000008",
)
print(payment.state)                   # ACK_PENDING — the answer is async

final = gw.wait_final("order-2026-0001")
print(final.state)                     # SETTLED (or REJECTED + rejection_reason)

The client mirrors the gateway’s operating rules instead of hiding them:

• Idempotency first. The key is the first positional argument of submit; calling it again with the same key returns the payment as it stands — safe inside any retry loop.
• wait_final understands the timeout case. TIMEOUT_UNRESOLVED is not final: the gateway’s reconciler is resolving it with a pacs.028 status request (never a resend), so the client keeps polling through it. HELD, REFUSED and CANCELLED, which only a gateway with its optional pre-send risk check produces, return at once: nothing was sent. HELD is not terminal (an operator key can release or cancel it), but it waits for a person, not for an advice; call wait_final again after a release. Releasing is an operator action, so the SDKs, which hold a submitting key, deliberately have no release call.
• Authenticated. Pass api_key= (one of the gateway’s FEDNOW_GW_API_KEYS, or a read-only key for monitoring); it is sent as Authorization: Bearer <key> on every call except healthy(). A missing or unknown key raises Unauthorized (401), a read-only key on a write raises Forbidden (403). The key is never included in an exception message or in the client’s repr.
• Profile violations are exceptions with rule codes. ProfileViolation.codes carries the gateway’s stable identifiers (fednow.ctgypurp.known, fednow.aba.checksum, …) — every violation at once, before anything reaches the wire.

Install / test

pip install ./sdk/python              # or: pip install -e ./sdk/python
pytest sdk/python                     # unit tests (stub server, no gateway)

# integration against the live stack (see QUICKSTART.md at the repo root);
# FEDNOW_GW_API_KEY must be a key the gateway was started with:
FEDNOW_GW_URL=http://localhost:8090 FEDNOW_GW_API_KEY=... pytest sdk/python

The integration tests run in CI against a real gateway↔simulator pair in MQ mode on every commit.