-
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
-
BitPOS PayPal-themed FigCraft concept. Fictional sample data and statuses; Sandbox integration planned, not runtime evidence.
BitPOS Café Copilot is built on the PayPal developer platform (free PayPal Sandbox: Orders v2 REST API, JavaScript SDK v6, Webhooks) and uses an AI model (Google Gemini API, function calling) inside the product. Hosted demo: https://paypal-pos.cashlessthailand.com (press Owner under Quick sign-in). Everything is Sandbox test money.
Inspiration
Small cafés end the day with surplus pastries and drinks. Owners know they should run a quick offer, but they have no time to work out a safe discount, update prices and take payment, and handing an AI the power to change prices or move money is not acceptable. We wanted an AI that does the analysis and drafting, while the owner approves and PayPal handles the payment, with the server checking every fact.
What it does
- The owner asks in plain words (English or Thai): "Sell the 8 croissants left before 4pm, at most 10% off."
- Café Copilot, a Google Gemini agent with function calling, uses six server tools:
read_merchant_limits,read_catalog_stockandread_recent_salesto read the facts;validate_campaign, where the server computes the offer price and checks stock, the shop limits and the limits the owner typed;save_campaign_draftto save a draft;ask_ownerwhen the request is unclear.
The agent has no tool to publish, charge or refund. Every model call and tool result is stored and shown as a trace.
- The owner reviews and approves the draft, then sends it to the shop's screens.
- The customer orders at the table or in Messenger at the offer price and pays with PayPal (JavaScript SDK v6 popup, PayPal Sandbox). In Messenger, the shop's AI turns a message into a cart from the real menu and replies with a "Pay with PayPal" button; signature-verified Meta webhooks, deduplicated messages.
- The server captures the order and verifies the order id,
custom_id,invoice_id, payee, currency, exact amount and the single final capture with PayPal before the bill is PAID. Webhooks (signature-verified) and a reconcile worker settle anything the customer's browser misses. - The owner sees the results:
- units sold against the approved cap;
- PayPal gross, fee and net from verified captures;
- an evidence timeline for each order, from the intent and AI tool calls through approval, PayPal capture and settlement.
How we built it
- PayPal developer platform (Sandbox):
- Orders v2 REST: create, capture and get, with OAuth client credentials and a
PayPal-Request-Idper operation so retries never create a second order or capture. - JS SDK v6 (
createPayPalOneTimePaymentSession) on the customer pay page. - Webhooks (
CHECKOUT.ORDER.APPROVED,PAYMENT.CAPTURE.*) with offline signature verification and a durable inbox. - The Sandbox business account is the payee.
- Orders v2 REST: create, capture and get, with OAuth client credentials and a
- AI:
- Google Gemini
generateContentwith function declarations, function-calling mode ANY, at most 6 model calls per run and a daily cap. - The shop's existing Gemini promotion generator writes the offer's headline and copy.
- Owner limits are parsed by the server as a second ceiling.
- Tests use a scripted model; real Gemini runs are logged in
evidence/ai-calls.md.
- Google Gemini
- Money safety in the database (PostgreSQL):
- Integer cents throughout.
- One live checkout per bill, settlement in one transaction, late or duplicate payments kept for review instead of dropped.
- The approved unit cap is enforced by a trigger, so it holds under concurrent orders.
- Stack:
- TypeScript on Node.js, an Astro + React web app, a worker for reconcile and webhooks.
- Deployed with Docker on Oracle Cloud behind a Cloudflare tunnel.
- 43 automated PayPal tests.
Challenges we ran into
- Thai sandbox merchant: a Thailand sandbox business account was declined at buyer approval ("to comply with international regulations"), so the demo shop uses a US Sandbox business account.
- Outcomes that are unknown, not failed: a timeout during capture can still mean money moved. Such checkouts stay "checking" and keep the bill protected until PayPal answers. We also had to separate temporary refusals (another capture in flight) from permanent ones.
- A smaller model on the hosted demo: it sometimes replied with an empty turn or with reasoning text instead of a tool call. Switching function calling to mode ANY and adding an
ask_ownertool made it reliable. - Limits the owner actually types: phrases such as "12 iced lattes", "ลด 10%", "by 15%" and "10 เปอร์เซ็นต์" all needed parsing, and "by 15%" must never be read as 3 pm.
Accomplishments that we're proud of
- A real PayPal Sandbox payment, end to end in the browser:
- Copilot (real Gemini) drafts the offer.
- The owner approves and publishes it.
- The customer orders at the table at the offer price.
- PayPal popup.
- The server captures: COMPLETED, USD 3.83, fee 0.62, net 3.21.
- The bill is SETTLED and the offer's unit is consumed.
Recorded in evidence/browser-e2e.md.
- An AI that cannot overspend: the model only proposes. The server computes prices, enforces limits, and the database caps units.
- Hosted, end to end with Messenger (11 Nov): a guest ordered in Messenger ("two iced lattes and a croissant"); the shop's AI built the cart from the real menu; the server priced a Table 2 bill (USD 13.05) and replied with a "Pay with PayPal" button; the PayPal Sandbox capture COMPLETED (fee 1.14, net 11.91), the server verified it, the bill became PAID, and a "Paid with PayPal ✓" reply arrived in Messenger. Recorded in
evidence/oci-deploy-2026-10-31.md. - Hosted: the deployment has quick sign-in for judges and a registered, signature-verified PayPal webhook. Judges can order at Table 2 and pay with PayPal Sandbox; the table's screen on the hosted demo is a clearly labelled simulated BitPOS Mini that never handles money.
What we learned
- Proof of payment must come from PayPal on the server, never from the browser callback.
- Idempotency keys plus a durable state machine make retries and crashes safe.
- The best place for an AI agent in commerce is analysis and drafting, with people approving and PayPal moving the money.
What's next for BitPOS Café Copilot
- PayPal refunds from the owner screen.
- More payment methods eligible through the JS SDK.
- Multi-product offers.
- Live mode after a security review.
- Copilot explaining campaign results in plain words from verified numbers.
Prior work and what is new (disclosure)
- BitPOS existed before this hackathon: a café POS with table QR ordering, a promotion approval flow, BitPOS Mini screens and Solana devnet payments.
- New for this hackathon, from 31 October 2026:
- all PayPal integration:
apps/api/src/paypal/,apps/web/src/components/paypal/, migrations400–405; - Café Copilot (the Gemini agent, tools, limits, traces);
- the hosted PayPal edition;
- the tests in
tests/paypal-*.
- all PayPal integration:
- Every new file and every changed existing file is listed in
paypal-hackathon/PROVENANCE.md. - AI used in the product: Google Gemini (function calling) for Café Copilot, and the existing Gemini promotion copy generator.
- AI used to develop it: coding assistants (Claude Code, Codex). These are separate from the product's AI.
Built With
- astro
- cloudflare-tunnel
- docker
- esp32-s3
- gemini-function-calling
- google-gemini-api
- node.js
- oracle-cloud
- paypal-javascript-sdk-v6
- paypal-orders-v2-api
- paypal-sandbox
- paypal-webhooks
- postgresql
- react
- typescript