Skip to main content

Build a Marketplace with Ishtaran

Alice wants a pair of wireless headphones Bob is selling on Mercatto, a marketplace built on Ishtaran. She pays 200 USDT. That money doesn't go to Bob right away — it goes into a locked box with a label: can't be spent yet. Only once Mercatto tells Ishtaran "the headphones arrived" does Ishtaran open the box and split what's inside: a small slice for Mercatto, the rest for Bob.

Alicebuyerpays 200 USDTReserved"can't be spent yet"🔒Transaction: RESERVEDMercatto confirms delivery ↓19.82Mercatto10% commission178.38Bobseller1.80 (0.9%) stays with Ishtaran as the Platform Fee
Real numbers from a real run: 200 USDT in, 1.80 Platform Fee, 178.38 to Bob, 19.82 to Mercatto's own commission Account.

Why this exists​

This isn't a marketing tutorial. Every code block on these pages is the exact file the Mercatto E2E suite imports and runs — the same files that gate every SDK release and every platform release. If a change to Ishtaran breaks this story, the release is blocked. If you're building a marketplace, you should be able to read this, copy the code, run it against the real Sandbox, and see the same real responses shown here.

Nothing here is invented to look nicer. Where the platform has a real limitation — a route that doesn't exist yet, an authorization rule that surprised us, a cooldown that can't be skipped — it's called out explicitly, not hidden. See Known Limitations for the full list.

The actors​

WhoRoleHow they reach Ishtaran
MercattoThe marketplace — owns the Ishtaran Organization and ApplicationIts own Application API Key, and (for a few operations — see Architecture) a Member session
AliceBuyerHer own self-service AccountHolder login — Mercatto never sees her password
BobSellerHis own self-service AccountHolder login, same as Alice
Mercatto's revenue AccountWhere the marketplace's own commission landsA regular Account, owned by Mercatto directly
IshtaranFinancial infrastructureNever decides whether the headphones actually shipped — only Mercatto knows that

Chapters​

  1. Architecture — the full sequence, every real method call
  2. Setup — Mercatto signs up
  3. Seller onboarding — Bob, Alice, and Mercatto's own revenue Account
  4. Creating an order — Workflow + Transaction with a real Split
  5. Accepting payment — the Payment Intent and the deposit address
  6. Holding funds — reservation, and what "locked" really means
  7. Confirming delivery — the event that isn't a gate
  8. Settlement and Split — Fee, Distributable Amount, the real Split
  9. Partial Settlement — releasing funds in installments
  10. Seller balance — how Bob finds out he got paid
  11. Withdrawal — and the real cooldown that blocks it
  12. Failure scenarios — 11 real alternative paths, all live-tested
  13. Full source — every file, one page
  14. Known limitations — real gaps, never hidden
  15. Run it yourself — against the real public Sandbox, no private access needed