A payment gateway where the shopper stays private and the merchant still gets paid

Wisp is a stablecoin payment gateway. A shop drops in a checkout, a shopper pays in USDC from their own wallet, and the shop is paid without touching a wallet themselves. What makes it a product rather than a transfer button is the choice the shopper gets at checkout: pay in public, the way every on-chain payment works today, or pay privately, through a zero-knowledge pool that leaves nothing on-chain connecting them to the shop.

The merchant side is a working product: a shop signs up, sees its balances, watches payments arrive, registers where private money should land, issues keys, and reads every notification its own server was sent. The shopper side is a checkout that takes a real payment on-chain. Phase one is complete on testnet; it is not on mainnet yet, so there are no real users or volume to report. What is still in front of us is settlement operations: payouts, reconciliation and disputes, and the case study says which is which rather than implying the whole thing is done.

There are four moving parts: a Solidity router that settles public payments in a single transaction, a Go API that owns invoices and the ledger, a Node service that holds everything the privacy layer needs, and the web application that both the shopper and the merchant actually touch. I own the web application end to end, wrote parts of the API, and integrated both sides against the router. The contract itself was written by another engineer on the team.

4

Services on the payment path

3

Independent idempotency layers before money moves

0

Floating point numbers anywhere near money

A blockchain broadcasts each purchase to anyone watching: the amount, who was paid, and the full history of the paying wallet. Pay a shop on-chain and you have handed that shop, and everyone else, your balance and your entire purchase history. No card network works this way, and no shopper would accept one that did.

The existing fix makes the problem worse. Funds that pass through a mixer are routinely frozen by exchanges and off-ramps, so privacy bought that way is privacy a business cannot use. Meanwhile the merchant wants none of this: not volatility, not custody, not a wallet to look after. They want the money, in the form they chose, on time.

The first week of the private flow went into finding out what the pool actually requires, and three answers changed the plan.

The first: the shopper's half of a private payment is much smaller than it looks. Moving money into the pool is a shield, and a shield needs no merkle tree, no synced wallet and no zero-knowledge proof. Proving is only required to spend from inside the pool, which is our side of the payment, not theirs. That collapsed the browser's job from a heavy client that downloads proving artifacts to one ordinary transaction, and it is the single biggest reason the checkout is fast on a phone.

The second: the version of the pool we build on has no memo field on a shield. The obvious design, where the shopper attaches the invoice number to their payment, is not available. So the invoice is matched by what the server can observe on its own, and the shopper's client is never trusted to label money it is sending.

The third: privacy pools do not exist on every chain, and the chains the gateway settles on are not automatically among them. That meant the checkout had to know the difference, rather than assume.

One API owns the money. A browser talks to it, That API owns invoices, the ledger and every decision about money; it never lets another service write a balance. Two things it cannot do itself live behind their own boundaries: the chain, which it watches rather than trusts, and the privacy layer, which speaks a language it does not.

Solid lines are request paths. Dashed lines are things that arrive on their own schedule: blocks confirming, a scanner finding a payment, a notification going out to a shop. Note the top line: the shopper's wallet pays the contract directly, so the money never passes through us. A private payment leaves the same way, into the pool, and only the scanner sees where it landed. The browser never talks to the privacy service, and the privacy service never talks to the database.

The router is the whole public payment. The API signs the exact terms of one invoice, the shopper's wallet calls the contract with that signature, and in one transaction the contract checks the signature, separates the fee, and forwards the rest to the merchant's own address. On the public path Wisp never holds the money: it never touches the transfer. A duplicate call on the same invoice reverts, so the contract, not our database, is the last word on whether a payment happened twice.

The privacy sidecar is the answer to a language problem that could have gone badly. The mature pool SDK is TypeScript; the service that owns money is Go. Rewriting cryptography in Go to keep one language was never a real option, and neither was moving the ledger into Node. So the SDK lives alone in a small service that holds the pool wallet, scans for incoming payments and decrypts them, and offers the Go side a typed contract with five calls on it. That service has no database, no authority over balances, and no route in from the internet.

The watcher is deliberately dull. It reads events from a block behind the head, records each one under the chain, transaction and log position it came from, and advances a stored marker so a restart resumes rather than replays. An event only counts once it has the confirmations the chain is configured to need, and an event whose block is later orphaned is marked as such rather than deleted, because the fact that we once believed it is part of the record.

1. 01

   The shop creates an invoice

   A server-to-server call opens an invoice against the merchant's account and returns a link. The shopper is sent there; the link itself is the credential, so the checkout needs no account and no login.

   On failureAn invoice that has expired, been paid, or been cancelled opens as a closed state rather than a payable one, so a stale link cannot take a second payment.

2. 02

   The wallet is screened before the option exists

   Private mode is offered only to a wallet that passed screening, and the report is stored against the invoice. This ordering is the point: the entrance to the pool is controlled, so every private payment we later have to account for came from a wallet we checked first.

   On failureA wallet that does not pass is offered the public route instead, without an explanation to work against. A verdict that has not come back yet is not a pass: the public route carries on, and private mode waits for a real answer rather than treating silence as one.

3. 03

   The shopper sees the whole price before anything is signed

   Amount, the rate behind it and the fee are on screen before a wallet prompt opens, with the quote counting down to its expiry rather than silently going stale.

4. 04

   The browser checks the server before the wallet does

   The terms the wallet will be asked to approve arrive from the API, and are re-checked against exactly what the shopper was shown: the same amount, the same chain, a token from the list that chain published, and a contract from the deployment allowlist. Passed through is not the same as trusted.

   On failureA mismatch stops before any wallet prompt. A response that disagrees with the screen is treated as an attack, not as a new price.

5. 05

   The payment is rehearsed before a wallet opens

   The exact call the wallet is about to make is simulated against the chain first. If the contract would reject it, the shopper is told that the shop's setup and the network disagree, before they have approved anything. Without that rehearsal the first thing they pay for is an approval, and the payment reverts immediately afterwards.

   On failureA rehearsal that cannot run, because the network is unreachable, does not block the payment: an unknown answer is not a refusal.

6. 06

   The shield is one ordinary transaction

   The browser derives a one-time key from a signature, builds one note for the merchant and one for the fee, and sends them together in a single transaction addressed into the pool. The key is used and dropped: it is never stored, never sent to us, and cannot spend anything.

   On failureA rejected signature, a short balance, or a chain with no pool each end in their own message. A private invoice on a chain without a pool is refused outright rather than quietly settled in public, because a shopper who asked for privacy must never be given publicity instead.

7. 07

   The pool hides what happens next

   From outside, a wallet deposited into a public privacy pool, which thousands of wallets do. Separately, a merchant was paid. No direct on-chain link joins the two. Amount and timing correlation are the residual risk, which is why the fee note and the merchant note travel in one transaction rather than two. Matching the shield to its invoice happens on our side from what the scanner sees, not from anything the shopper's client was trusted to attach.

8. 08

   The hash is reported, and the report is not allowed to be the weak link

   By the time the browser tells us the shield happened, the money has already moved. So that one call retries with backoff rather than failing with the tab, and a refusal the server means (a bad request) stops immediately instead of hammering it.

   On failureA payment whose settlement depends on a browser tab surviving long enough to make an HTTP call is a payment that will sometimes not settle. That is written down as the open risk it is, not smoothed over.

9. 09

   The merchant is paid and told

   Settlement is written to the ledger in one transaction with the fee, the shop is notified with a signed message it can verify, and the dashboard shows the payment with no receipt link, because there is no public record to link to. The absence is rendered as a statement rather than an empty cell.

   On failureA notification the shop does not acknowledge is retried with backoff and surfaced in the dashboard, so a shop is never silently out of sync about money it has received.

Four stack decisions carry most of the weight here, and each one has a bill attached.

Every one of these buys something specific and charges for it somewhere else.

A payment gateway is mostly the study of things arriving more than once. A shop retries a request it never saw answered. A chain delivers the same event after a restart. A scanner replays a page it already read. Any of those crediting a payment twice is worse than an outage, because an outage is visible.

So repetition is handled three times over, at three different boundaries. An inbound request carries a key that makes a retry return the first answer instead of doing the work again. A ledger movement is written under an identity derived from what it represents, so the same settlement cannot post twice. And a chain event is stored under the chain, transaction and log position it came from, which is a natural identity nothing else can collide with. Each layer would be enough on a good day; the point is that they do not share a failure.

The chain gets the same treatment from the other side. Nothing counts as paid on its first sighting: an event waits for the confirmations that chain requires, and a block that is later orphaned marks its events as reorganised rather than deleting them, because a shop may already have been told and the record needs to show what we believed and when. The watcher keeps a marker per chain so a restart resumes from the last block it finished rather than rescanning from zero or, worse, skipping ahead.

Notifications to a shop are their own small reliability problem. They are signed so the shop can verify the message is ours, retried with backoff when the shop's endpoint is down, and every attempt is recorded with its response, so a merchant can see in the dashboard that their own server rejected a payment notification five times rather than concluding that the payment never happened.

The parts that are easy to get quietly wrong have checks that run as commands rather than opinions: the contract interface the frontend encodes against is asserted to match the deployed one, the money helpers are asserted to round the way the backend does, and the privacy layer's network support is asserted against the SDK's own list rather than a constant someone remembered to update. They run in seconds and fail loudly, which is what makes them useful in a place where a mistake is a wrong amount rather than a broken page.

Five product decisions took the most argument, and in each case the faster option was the one that would have been discovered later, by a shopper.

One decision was about what not to build. The merchant application shipped without the screens the API could not yet serve, rather than with screens that invented their own contents. A balance nobody can stand behind is the fastest way to lose a partner's trust in everything else on the page, and each of those screens was cheap to add back the day the service behind it existed.

The same instinct went through the copy with a red pen. A payout “expected within 2 to 6 hours”, a shield that takes “a couple of minutes”, a landing page promising five networks in under a minute: none of those numbers had been measured, and a payment product that guesses at timings in writing is teaching people not to believe it. They came out. What is left is what the system can actually stand behind.

The same instinct shaped the checkout copy. The words the industry uses, the pool's name, the screening vocabulary, the compliance terms, appear nowhere in front of a shopper. They see an amount, a fee, a countdown, and a plain sentence about what is about to happen. The interesting machinery is the part a payment product should never make its user learn.

The cryptography was never the hard part, because it was not mine to write. The hard part was deciding where uncertainty is allowed to live: which service may be wrong, which one is allowed to be slow, and which one is the last word when they disagree. Once the chain was something watched rather than trusted, the pool something reached through one boundary, and the ledger the only place a balance exists, most of the remaining questions answered themselves.

The other lesson was about the boundary between a server and a wallet. In an ordinary product, the server is the authority and the client renders what it is told. When the client is holding a key that can move a stranger's money, that inverts: the client has to check the server, because the person clicking is the one who pays for a lie. Building the checkout as though the API might be hostile made it a better client of a friendly one.