Key concepts
Five concepts you'll encounter everywhere — in the API, in this documentation, and in your agreement with Waffy. Read this once and everything else will make sense faster.
Parties and roles
Every Waffy transaction has the same three roles. The API uses the code names — learn them once.
| Code name | Plain name | What they do |
|---|---|---|
CUSTOMER | Buyer | Pays into the escrow. Receives the goods or service. Gets a refund if delivery is rejected. |
PROVIDER | Seller | Delivers. Gets paid when the deal is settled — Waffy disburses their share per the settlement request. |
BROKER | Your business | Creates the contract. Confirms or rejects delivery. Sends the settlement request. Optionally keeps a commission from the split. |
In conversation, just say buyer, seller, and your business. The code names appear in API requests, webhook payloads, and contract objects.
Contract
A contract is the record of a deal on Waffy. It ties together the parties, the amount, the payment method, and the outcome. Your team creates it; the buyer funds it; your team confirms and settles it.
One contract = one transaction. For multi-milestone deals (staged projects), each milestone is its own payment unit inside a parent contract — each milestone follows the same 7-step flow independently.
A contract moves through a fixed set of states — Created → Funded → Delivery → Confirmed → Settled → Completed — and your team is the actor at every gate.
Escrow
Waffy's role is to collect, hold, and disburse money. When the buyer pays — say 1,000 SAR — Waffy holds it. Nobody has the money yet. It stays held until your team tells Waffy what to do with it.
You can read the held amount on any contract at any time via the API or the B2B portal.
Settlement
Settlement is the act of your team sending Waffy a request specifying exactly how to disburse the held funds — how much goes to the seller, how much to your org, how much (if any) returns to the buyer.
Settlement is a separate step from delivery confirmation. Your team first marks the contract accepted or rejected, then sends the settlement request. Waffy executes exactly what your team sends. Once cashout runs, funds have moved.
Your org's share sits with Waffy until you request a withdrawal to your registered IBAN — settlement and cashout-to-your-bank are two distinct events.
Sandbox
Waffy provides an isolated sandbox environment for every client — its own users, its own contracts, no real money. You build and test your full integration in sandbox before going live. Sandbox credentials are issued by your account manager after onboarding. See Sandbox & credentials for the full picture.
Next
- How the money moves — the full flow, step by step, using the vocabulary from this page.