Freelancers lose the thread between a spoken price, a PDF invoice, and the day the money actually arrives. Clients want Pay Later. Agencies only want to pay a provider after a deliverable is approved. Disputes start when nobody can show what was agreed.
I wanted one file where an agent negotiates the quote, PayPal writes the invoice and takes the payment, and the provider is paid only milestone by milestone.
What it does
AuraPay is a sandbox desk for that path.
The agent prices the work from a catalog. The browser never sends an amount, a tax, or a secret. When the client accepts, the server locks the before-tax price, adds 20% tax, and keeps an 8% platform fee. What remains is the provider pool, split 30% / 40% / 30%.
PayPal Invoicing v2 turns that locked quote into an invoice, a hosted page, and a QR code. JavaScript SDK v6 renders PayPal and Pay Later. Orders v2 captures the payment on the server. The first milestone goes out through Payouts v1. The next two stay in escrow until someone presses Approve and release.
If the buyer opens an inquiry, the agent reads the audit log, drafts a reply, and shows it before anything is sent.
How I built it
The app is Next.js 15 with the App Router, React 19, TypeScript, Tailwind, and Zod. Money is stored in integer cents. PayPal amounts are formatted only on the server.
The merchant access token never reaches the browser. Checkout starts from a separate client token, created with response_type=client_token and intent=sdk_init. The SDK is initialized with createInstance({ clientToken, components: ["paypal-payments"], locale: "en-US" }). Buttons appear only after findEligibleMethods().
Every create, capture, invoice, payout, and dispute call sends PayPal-Request-Id. Errors return a readable message plus PayPal’s issue and debug_id. Negative tests use PayPal-Mock-Response for codes such as INSTRUMENT_DECLINED.
On localhost there is no public webhook URL. PAYPAL_WEBHOOK_ID is optional. In development, an empty id skips signature verification, logs a warning, and still returns 204. A local emitter can simulate PAYMENT.CAPTURE.COMPLETED.
Challenges
PayPal rejects domains[] that contain localhost, so the client token is requested without that field. The SDK also has a known trap: session.start() must receive the Promise returned by createOrder(), not the function itself.
The invoice QR endpoint does not return a plain PNG. It answers 406 unless Accept is */*, then sends the image as base64 inside multipart form data.
Payouts were the sharpest edge. A placeholder address such as [email protected] comes back RECEIVER_UNREGISTERED. Paying the business sandbox account from itself returns SELF_PAY_NOT_ALLOWED. The recipient has to be a Personal sandbox email. Retrying a failed milestone with the same sender batch id is also rejected, so a retry mints a new id.
What I learned
The sensitive part of a payments app is not the button. It is keeping amounts, secrets, and idempotency on the server, then letting PayPal confirm each step: invoice, capture, payout batch, and dispute reply.
How we built it
Challenges we ran into
Accomplishments that we're proud of
What we learned
What's next for AuraPay — Autonomous AI Commercial Agent & Escrow Protocol
Built With
- api
- css
- javascript
- next.js
- node.js
- paypal
- react
- rest
- sandbox
- sdk
- tailwind
- typescript
- zod