Inspiration

Freight payments run on trust. A forwarder pays a carrier on paperwork it cannot fully check, and the loss from one wrong payment is the whole freight bill. We started from Floorline, our shipment-fraud screen from the Nebius x NVIDIA hackathon, which already set a risk floor with plain code and let AI agents argue only upward. It had no payment code. This project connects it to real money movement on PayPal.

What it does

A shipper books a shipment and approves the payment on PayPal's own page. PayPal holds the money (intent: AUTHORIZE); nothing is taken. Floorline screens the case, and money moves only when a decision is published:

  • Release, by a person signed in with a password: the settler checks the payment rules once more, captures the money and pays the carrier with PayPal Payouts.
  • Block: the settler voids the hold and the money stays with the shipper.
  • The agent, only when a governance admin has published an agent limit: it may decide a clean case below that limit by itself. With no limit, or a limit of 0, every payment waits for a person. On the live demo the agent is off.

Deterministic checks (a payee that is not the one on file, a payee changed in the last 14 days, a payout above the booked freight, a missing payee) add to a risk floor. AI agents may raise a case above the floor; no model, learning adjustment or debate verdict can lower it. A one-click guest session on the live demo has the Viewer role: it can look at every screen but cannot book, block, release or approve; a large payout (2,500 USD or more by default) needs a second approver. The settler is the only code that moves money, and it never calls a model.

This is a proof of concept on the PayPal sandbox: no real money moves.

How we built it

  • PayPal (sandbox only): REST Orders v2 (create with AUTHORIZE, authorize), authorization capture and void, and Payouts. Every call returns a receipt and never raises; each carries a request id derived from the decision key, so a repeat cannot pay twice.
  • Settlement path: a decision is published to Google Pub/Sub; Pub/Sub pushes it to a receiver that accepts only a Google-signed token; the settler captures, pays or voids. An unknown outcome is answered with 503 so the decision is delivered again.
  • AI: Nemotron 3 Nano and Super through Nebius Token Factory screen every case; Tavily gives live web search; a payment-risk analyst sees numbers and categories, never a name or an address. Each AI layer may only raise risk or tighten a limit.
  • Credit security in seven layers: booking-bound authorizations, a two-person carrier payee registry, limits and a pause switch, dual approval of a large release, settlement integrity (webhook, payout tracking, freezes), and the AI layers above.
  • Console and API: Python and Flask backend, Next.js console, Firestore for the case store. Hosted on Render, with Firestore and Pub/Sub in a separate Google Cloud project.
  • Tests: 3,429 backend tests pass (49 skipped without the Firestore and Pub/Sub emulators) and 2,115 frontend tests pass; ruff, mypy and tsc are clean and eslint reports no errors. No test calls PayPal: they use fakes and recorded sandbox answers.

What changed during the Submission Period

The baseline is the Nebius submission (tag nebius-baseline), which had no payment code. Everything after that tag is the PayPal work: the PayPal client, the payment checks, the settler, the booking and payments pages, and credit-security layers one to seven. git diff --stat nebius-baseline HEAD shows it; the README lists each part and its files.

Challenges

  • Never paying by accident. Every release path fails closed: a missing, unreadable or placeholder value means "not verified", never "fine". Each refusal is a named status and pays nothing.
  • The first real booking found a gap. A person's release or block, for a case booked through the console, was recorded but not published, so the settler never saw it and a block could not void the hold. We fixed it and pinned it with tests. The fix is now shown end to end on the live service.
  • An agent that starts suspended. Until a person publishes what the agent may do, it can analyse and propose but not act. That is the safe default, and it caught us out when nothing was being published.

Accomplishments we are proud of

  • The core rule holds in code and in tests: a model can raise risk and never lower it, and the code that moves money never calls a model.
  • Run for real on the live service, sandbox money only (5 Nov 2026): a Block voided a 1,300 USD hold (PayPal answered 204), and a Release captured it (201) and paid the carrier through Payouts (201). The webhook verified real signed events from PayPal, a payout moved from unconfirmed to confirmed from the payout-item event, and a capture refund froze the carrier.
  • The agent, stated within what was shown: under a 500 USD limit a person published, it refused sixteen sandbox trials, then paid two cases of one fictional demo shipper (8 Nov 2026). In the second, the buyer, the carrier and the operator were three separate sandbox accounts: 1,500 USD held and captured, 400 USD paid out and confirmed by PayPal. That is not evidence that it pays everyday freight, and the limit is now 0.
  • A repeat does not hold twice (9 Nov 2026): authorizing an already authorized order again returned the stored authorization without calling PayPal, and PayPal's activity shows one authorization for that order.
  • Measured, with the limits stated. On an invented set of 80 payouts (36 fraudulent, 44 honest), the deterministic checks catch 24 of 36 with 0 of 44 false flags; adding a carrier look-up reaches 32 of 36 with 6 of 44 false flags. These rates describe that invented set only and are not a forecast.

What we learned

A payment agent is mostly a set of refusals. The useful work was deciding what it must never do, writing each refusal down as a named status, and testing the refusals more than the happy path.

What's next

  • Get a real dispute event through the webhook against the sandbox (a refund already came through and froze the carrier).
  • Run the webhook-first and unknown-outcome recovery paths against the real sandbox; they are tested in simulation only.
  • Give the payment-risk analyst something to catch: measured live on the first invented set, it added nothing (it missed all four impersonated-carrier cases), so it needs better inputs or a better corpus before we rely on it.
  • Exercise the daily-limit reservation against Firestore under real concurrency. It is tested on the in-memory store and ran end to end on the live service, one settlement at a time.

Built With

  • authorizations
  • flask
  • google-firestore
  • google-pub/sub
  • nebius-token-factory-(nemotron-3-nano-and-super)
  • next.js
  • payouts)
  • paypal-rest-(orders-v2
  • python
  • render
  • tavily
  • typescript
Share this project:

Updates

Submission history