Inspiration

I live in Vietnam. Small shops price in Vietnamese dong (VND), tourists arrive from everywhere, and PayPal cannot settle in dong. Closing that gap today takes a calculator, a translator and a payment link. TourPay Copilot does all three from one sentence.

What it does

A tourist (or the shopkeeper) writes the bill in plain words, in Chinese, English or Vietnamese: 3 x 45k + 80k, pay in USD, or 三杯咖啡每杯四万五,再加一份蛋糕八万,用欧元付. The app:

  • sums the items and converts 215,000 VND at a live mid-market rate (8.33 USD in the demo),
  • creates a PayPal Orders v2 order and hands over the payer link,
  • captures the payment automatically when the payer returns from PayPal's checkout,
  • replies and issues receipts in the payer's language,
  • refunds a completed payment through PayPal's refund API with a two-step confirmation (request, then confirm within 2 minutes),
  • gives the merchant a reconciliation dashboard (today in Vietnam time, by currency, CSV export),
  • answers "how can I pay in Vietnam?" honestly, including that cryptocurrency is not legal tender for payments there.

The design idea: the model never touches money

Language models read messy requests well and do arithmetic badly. So the AI (Google Gemini, free tier) only understands the request: intent, amount, currency. Every amount, exchange rate, limit and PayPal call comes from deterministic, tested code using exact Decimal arithmetic (round half up, zero-decimal currencies such as JPY handled). Rules parse first; the model is asked only when the rules cannot, and its answer is validated. If the model fails or no key is set, the app falls back to the rules, so the demo never depends on a network model.

How I built it

Python standard library only (no pip install). PayPal Orders v2 and the Payments refund API in the sandbox, OAuth client credentials, PayPal-Request-Id idempotency. A built-in mock PayPal makes the whole lifecycle testable offline and lets judges run the project with no accounts or keys. The server listens on localhost only and refuses foreign Host/Origin headers.

AI tools used, and how

  • In the product: Google Gemini (gemini-3.5-flash-lite, free tier, with automatic fallbacks) reads messy bills (Chinese numerals, Vietnamese number words), decides pay-vs-quote intent and handles small talk. Anthropic Claude and any OpenAI-compatible server are supported as optional alternatives (not verified live; no key available).
  • In development: I built the project with AI coding agents (Claude Code and Codex) under my direction. I set the goals, made the judgment calls, and verified the results against the real PayPal sandbox.

Verified, not just claimed

  • The full order lifecycle ran against the real PayPal sandbox: create, buyer approval on PayPal's checkout, automatic capture (COMPLETED), refund (REFUNDED). The demo video shows the real sandbox order and capture; its refund card is a labelled mock illustration, not a recording.
  • I probed each currency on the real sandbox: 12 are accepted (AUD, CAD, EUR, GBP, HKD, JPY, MYR, PHP, SGD, THB, TWD, USD). CNY is rejected by PayPal, so the app refuses it instead of silently switching currency.
  • 46 automated offline tests, including hostile inputs (dates and phone numbers are never read as amounts, negative amounts, oversized requests), the real HTTP server on an ephemeral port, and a fake model returning bad output.

Challenges

Keeping the model away from arithmetic; VND is not a PayPal currency; Vietnamese shorthand such as 1tr2 (1.2 million); stale model names (a free-tier model returned 404 for a new account, so the app falls back to other models); and being honest about what is verified live versus only tested offline.

What I learned

Use models for language and code for money. Probe the real API before trusting a documented list: the currency list I assumed was wrong for CNY.

What's next

Native-speaker review of the Vietnamese strings, webhooks instead of polling, VietQR deep links, and multi-merchant accounts with authentication.

New work

Created entirely during the Submission Period (first commit 2026-10-31); no earlier code reused. Open source under the MIT license.

Try it

Needs only Python 3.9+. No accounts or keys: git clone https://github.com/A-Tao990/tourpay-copilot && cd tourpay-copilot && python3 -m tourpay, then open http://localhost:8080 (mock PayPal and built-in rules, clearly labelled). The README explains how to connect your own free PayPal sandbox credentials and a Gemini key.

Built With

Share this project:

Updates

Submission history