Inspiration
Cross-border teams lose money two ways: paying suppliers at the wrong FX moment, and babysitting manual payout batches. We built a treasury guard that watches FX risk and acts inside a policy a human pre-approved — AI decides, human allows, PayPal moves the money.
What it does
BAO VE TIEN is an AI-supervised global treasury demo: it takes payout batches, scores FX risk, and executes real PayPal Sandbox payouts. Human mode: AI recommends, human approves. Auto mode: qualifying batches (EXECUTE_NOW, low FX risk, within caps, allow-listed recipient) execute by themselves; anything else waits with the blocking reason shown. Every decision lands in an audit log with its policy snapshot.
How we built it
Node.js + Express + TypeScript backend calling the PayPal Payouts REST API (Sandbox) with OAuth2 and idempotency keys, plus a webhook listener with signature verification. The FX advisor runs on Gemini (gemini-3.6-flash) behind an OpenAI-compatible interface, with a rule-based HOLD fallback; every LLM answer is re-validated against batch amounts and currencies, and recipient PII is masked before any LLM call. Frontend is React + Vite + AG Grid with live SSE updates.
Challenges we ran into
• PayPal Payouts doesn't support VND — caught in our docs audit, so VND is display-only and converts to USD for processing. • Our early docs used wrong webhook names; fixed to PAYMENT.PAYOUTSBATCH.* with real signature checks. • Gemini model drift: gemini-2.5-flash retired for new keys (404), 3.8-flash overloaded (503) — shipped on 3.6-flash with graceful HOLD fallback. • Developer Dashboard login got captcha-locked, so we proved everything API-only through sandbox credentials.
Accomplishments that we're proud of
• Real sandbox money movement, including a fully autonomous $5 Auto-mode execution with zero per-batch clicks. • Honest failure design: any AI, FX, or PayPal failure becomes a visible HOLD or refusal — never faked for the camera. • 36/36 backend tests green; ~1.2s approve-to-PayPal round-trip and ~5s live AI advise, measured on video day.
What we learned
Free-tier AI is flaky — design the fallback first, not last. PayPal's idempotency model rewards careful state machines (terminal FAILED, never double-pay). And model IDs drift fast: keep them in config, not in code.
What's next for BAO VE TIEN
Live Payouts approval, a public webhook endpoint for true real-time settlement updates, a persistent ledger (demo store is in-memory today), then dispute-shield automation.
PayPal + AI tools used
• PayPal Payouts REST API (Sandbox): executes the real payout batches; idempotency via PayPal-Request-Id. • PayPal Webhooks (Sandbox): PAYOUTSBATCH / PAYOUTS-ITEM events drive live ledger updates; signatures verified. • Google Gemini (gemini-3.6-flash, free tier): FX advisor returning EXECUTE_NOW / HOLD /SPLIT_BATCH plus a 0–10 risk score, grounded against batch data. ## Additional sponsor tools AG Grid — the live treasury ledger grid. (PayPal OpenAPI specs guided our schema design; no other sponsor SDK is a runtime dependency.)
Built With
- ag-grid
- apimatic
- paypal
- paypal-payouts
- paypal-webhooks