Scenarios

Escrow with inspection

One buyer · one seller · one milestone · inspection enabled at org level. One extra step compared to Simple — CONFIRM_INSPECTION sits between ACCEPT_CONTRACT and SETTLE_CONTRACT.

Same escrow as the Simple flow — the buyer pays, Waffy holds the funds. With inspection enabled, once the admin confirms delivery via ACCEPT_CONTRACT the contract moves to ITEM_INSPECTION and the buyer reviews in the Waffy app. Once they confirm, the admin calls CONFIRM_INSPECTION, then SETTLE_CONTRACT.

Inspection is an org-level setting configured at onboarding — not a per-milestone flag. If your org has inspection disabled, use the Simple escrow flow instead.

Parties

Role	API value	What they do	arbitrator	isSender
Broker — your org admin	`BROKER`	Creates and manages the contract	true	true
Buyer	`CUSTOMER`	Pays into escrow	false	— omit
Seller	`PROVIDER`	Receives payout on settlement	—	— omit

Flow

Your platformBuyerWaffyAutomatic

Setup

Set up buyerSign up + IBAN + address

Your platform

Set up sellerSign up + IBAN + address

Your platform

Create complex contractContainer — holds no money

Your platform

Add milestone1000 SAR escrow transaction

Your platform

Add parties to milestoneBuyer, seller, broker joined

Your platform

Payment

Generate checkout linkScoped to buyer identity

Your platform

Buyer paysFunds held in escrow

Buyer

Delivery

Admin confirms deliveryACCEPT_CONTRACT called

Your platform

Inspection

Admin confirms inspectionCONFIRM_INSPECTION called

Your platform

Settlement

Admin settlesSETTLE_CONTRACT with cashout split

Your platform

Cash out in progressWaffy processes bank transfers

Waffy

CompletedAll parties paid out

Automatic

Walkthrough

Before you start

You need APP_TOKEN, USER_TOKEN, and WAFFY_ADMIN_PHONE — see the Authentication page.

You also need WAFFY_ADMIN_ID — your org admin's Waffy user ID. Fetch it once and store it:

bash

curl -s "$WAFFY_AUTH_URL/api/users/me" \
  -H "Authorization: Bearer $USER_TOKEN"
# save data.id as WAFFY_ADMIN_ID

Set up the buyer

Three calls in order: register, add IBAN, add address. IBAN and address are only required if the buyer may receive a bank transfer refund — card payments (Mada, Visa, Apple Pay) refund directly to the original payment method.

1a — Register

bash

curl -s "$WAFFY_AUTH_URL/v2/api/users/sign-up" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "{{BUYER_PHONE}}",
    "firstName": "{{BUYER_FIRST_NAME}}",
    "lastName": "{{BUYER_LAST_NAME}}",
    "clientUserId": "{{YOUR_INTERNAL_BUYER_ID}}"
  }'

json

{
  "data": {
    "id": 99001,
    "phoneNumber": "{{BUYER_PHONE}}",
    "preExistingUser": false,
    "clientUserToken": "eyJhbGc..."
  }
}

clientUserToken is the buyer's Waffy password — store it encrypted

Save data.id as BUYER_ID, data.phoneNumber as BUYER_PHONE, and clientUserToken as BUYER_CLIENT_TOKEN. Never log it. Never expose it to the browser. You will use it to generate checkout tokens. Do not send password in the sign-up body — Waffy generates and returns it.

1b — Add IBAN

Required for refund payouts. Saudi format: SA + 22 digits.

bash

curl -s "$WAFFY_AUTH_URL/api/users/$BUYER_ID/IBAN" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "{{BUYER_IBAN}}",
    "currency": "SAR",
    "beneficiaryName": "{{BUYER_FULL_NAME}}",
    "nationalId": "{{BUYER_NATIONAL_ID}}",
    "accountType": "PERSONAL"
  }'

1c — Add address

Required alongside IBAN for bank transfer cash-out.

bash

curl -s "$WAFFY_AUTH_URL/api/profiles/$BUYER_ID/addresses" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addressLabel": "HOME",
    "street": "{{BUYER_STREET}}",
    "district": "{{BUYER_DISTRICT}}",
    "city": "{{BUYER_CITY}}",
    "countryCode": "SA",
    "postalCode": "{{BUYER_POSTAL_CODE}}"
  }'

Set up the seller

Same three calls for the seller. IBAN and address are required for the seller — cashout will be blocked until they are on file.

2a — Register

bash

curl -s "$WAFFY_AUTH_URL/v2/api/users/sign-up" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "{{SELLER_PHONE}}",
    "firstName": "{{SELLER_FIRST_NAME}}",
    "lastName": "{{SELLER_LAST_NAME}}",
    "clientUserId": "{{YOUR_INTERNAL_SELLER_ID}}"
  }'

Save data.id as SELLER_ID.

2b — Add IBAN

bash

curl -s "$WAFFY_AUTH_URL/api/users/$SELLER_ID/IBAN" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "{{SELLER_IBAN}}",
    "currency": "SAR",
    "beneficiaryName": "{{SELLER_FULL_NAME}}",
    "nationalId": "{{SELLER_NATIONAL_ID}}",
    "accountType": "PERSONAL"
  }'

2c — Add address

bash

curl -s "$WAFFY_AUTH_URL/api/profiles/$SELLER_ID/addresses" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addressLabel": "HOME",
    "street": "{{SELLER_STREET}}",
    "district": "{{SELLER_DISTRICT}}",
    "city": "{{SELLER_CITY}}",
    "countryCode": "SA",
    "postalCode": "{{SELLER_POSTAL_CODE}}"
  }'

Create the complex contract

The parent is a container — it holds no money. itemPrice: 0 is intentional.

bash

curl -s "$WAFFY_BASE_URL/api/external/contracts" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPLEX_CONTRACT",
    "senderRole": "BROKER",
    "contractClassification": "BASIC",
    "currency": "SAR",
    "itemPrice": 0,
    "itemDetail": {
      "title": "Order #1001",
      "description": "Product description here"
    },
    "returnPolicy": "NO_RETURN",
    "returnFeePayee": "PROVIDER",
    "waffyTermsAccepted": true,
    "isParent": true
  }'

json

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "type": "COMPLEX_CONTRACT",
    "senderRole": "BROKER",
    "status": "CREATED"
  }
}

Save data.id as CONTRACT_ID.

Add the milestone

This is where the amount lives. Do not pass paymentMethods, isDeliverable, or isInspectable — these are org-level settings configured at onboarding.

bash

curl -s -X PATCH "$WAFFY_BASE_URL/api/external/contracts/$CONTRACT_ID/milestones" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "milestones": [{
      "type": "MILESTONE_CONTRACT",
      "senderRole": "BROKER",
      "itemDetail": {
        "title": "Order #1001",
        "description": "Product description here"
      },
      "itemPrice": 1000,
      "currency": "SAR",
      "returnPolicy": "NO_RETURN",
      "returnFeePayee": "PROVIDER",
      "deadLine": "2026-12-31T23:59:59Z",
      "waffyTermsAccepted": true
    }]
  }'

json

{
  "data": {
    "parentContractId": "507f1f77bcf86cd799439011",
    "milestones": [{
      "id": "607f1f77bcf86cd799439022",
      "itemPrice": 1000,
      "status": "CREATED"
    }]
  }
}

Save milestones[0].id as MILESTONE_ID.

Add parties to the milestone

All three parties in one call using phone numbers. Once this lands, the milestone is payable automatically — no separate publish step for API integrations.

bash

curl -s -X PATCH "$WAFFY_BASE_URL/api/external/contracts/$CONTRACT_ID/parties" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"mileStonesParties\": {
      \"$MILESTONE_ID\": [
        {
          \"phoneNumber\": \"$BUYER_PHONE\",
          \"role\": \"CUSTOMER\",
          \"amount\": 1000,
          \"arbitrator\": false
        },
        {
          \"phoneNumber\": \"$WAFFY_ADMIN_PHONE\",
          \"role\": \"BROKER\",
          \"amount\": 960,
          \"arbitrator\": true,
          \"isSender\": true
        },
        {
          \"phoneNumber\": \"$SELLER_PHONE\",
          \"role\": \"PROVIDER\",
          \"amount\": 40
        }
      ]
    }
  }"

Party rules — no exceptions

• BROKER must have arbitrator: true and isSender: true — the contract creator
• CUSTOMER and PROVIDER — omit isSender entirely

What the buyer and seller experience

If your org has invitationAllowed: false (most orgs) — parties are auto-joined immediately after this call. No action required from buyer or seller before payment can proceed.

If invitationAllowed: true — buyer and seller receive an invitation in the Waffy app and must accept before payment becomes available. Your account manager confirms which applies to your org during onboarding.

Generate the buyer's checkout link

First exchange the stored BUYER_CLIENT_TOKEN for a short-lived checkout token. Fetch this immediately before redirecting — tokens expire in 60 minutes.

bash

curl -s "$WAFFY_AUTH_URL/oauth/token" \
  -u "$WAFFY_CLIENT_ID:$WAFFY_CLIENT_PASSWORD" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=$BUYER_PHONE" \
  --data-urlencode "password=$BUYER_CLIENT_TOKEN" \
  --data-urlencode "scope=WRITE"
# save access_token as CUSTOMER_TOKEN

Then get the checkout URL. WAFFY_CLIENT_ID here is the same client_id from your onboarding credentials:

bash

curl -s "$WAFFY_BASE_URL/api/external/contracts/startPayment/$MILESTONE_ID/$WAFFY_CLIENT_ID?redirectUrl=https://yourapp.com/done&paymentType=PURCHASE" \
  -H "Authorization: Bearer $USER_TOKEN"

json

{
  "data": "https://app.waffyapp.com/external/UXFmUCaG?client_id=...&payment_methods=MADA,VISA,APPLE_PAY"
}

payment_methods is auto-populated from your org's contracted methods — you do not set it.

Two ways to present the checkout URL:

Option A — Raw URL redirect (Flutter and frameworks the SDK doesn't cover)

javascript

const url = paymentUrl + "&userTokenUrl=" + CUSTOMER_TOKEN;
window.location.href = url;  // or Flutter: launchUrl(Uri.parse(url))

Option B — Waffy SDK (recommended for Web, Android, iOS, React Native)

Include the SDK script from https://sdk.waffyapp.com/v2/waffy-payment-display.min.js, then call:

javascript

WaffyPaymentDisplay.show({
  paymentUrl: "https://app.waffyapp.com/external/UXFmUCaG?client_id=...",
  userToken: CUSTOMER_TOKEN,
  mode: "modal"  // or "popup" or "iframe"
});

Android / iOS / React Native use the platform SDK equivalents — your integration team receives package references during onboarding.

Buyer pays — listen for webhook

When the buyer completes payment Waffy fires a webhook to your configured endpoint:

json

{
  "contractId": "607f1f77bcf86cd799439022",
  "status": "PAID",
  "referenceId": "txn_abc123"
}

contractId is the milestone ID.

Always verify the webhook signature

Every request carries a Waffy-Signature header. HMAC-SHA256 the raw body with your webhook secret and compare before acting. Respond HTTP 200 immediately and process async.

Waffy retries failed deliveries 3 times: after 1s, 10s, and 100s. If your endpoint doesn't respond within a few seconds, the delivery is marked failed and retried.

Funds are now held in escrow. The contract moves from PAID to WAITING_FOR_DELIVERY — the seller fulfilment phase begins.

Admin confirms delivery

Once you confirm delivery happened on your side, call ACCEPT_CONTRACT. Note actorRole: BROKER — accept and reject are always broker-side actions.

bash

curl -s "$WAFFY_BASE_URL/contract-actions/external" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"contractId\": \"$MILESTONE_ID\",
    \"userId\": \"$WAFFY_ADMIN_ID\",
    \"actorRole\": \"BROKER\",
    \"contractAction\": \"ACCEPT_CONTRACT\",
    \"contractType\": \"MILESTONE_CONTRACT\"
  }"

What happens next — inspection window opens

Once delivery is acknowledged the contract moves to ITEM_INSPECTION — the buyer reviews the item in the Waffy app. Funds remain held in escrow throughout. Confirm the buyer's acceptance in Step 9.

With inspection enabled, settlement is blocked until you call CONFIRM_INSPECTION (or REJECT_CONTRACT) in the next step.

Admin confirms inspection

Once the buyer signals acceptance in the Waffy app, call CONFIRM_INSPECTION to mark inspection complete. Same endpoint and body shape as Step 8 — only the action string changes. actorRole: BROKER — confirm and reject are always broker-side actions.

bash

curl -s "$WAFFY_BASE_URL/contract-actions/external" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"contractId\": \"$MILESTONE_ID\",
    \"userId\": \"$WAFFY_ADMIN_ID\",
    \"actorRole\": \"BROKER\",
    \"contractAction\": \"CONFIRM_INSPECTION\",
    \"contractType\": \"MILESTONE_CONTRACT\"
  }"

Reject path — buyer rejects the item

If the buyer rejects during inspection, call REJECT_CONTRACT instead — same body, same actorRole: BROKER. The refund flows through Step 10 settlement.

bash

curl -s "$WAFFY_BASE_URL/contract-actions/external" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"contractId\": \"$MILESTONE_ID\",
    \"userId\": \"$WAFFY_ADMIN_ID\",
    \"actorRole\": \"BROKER\",
    \"contractAction\": \"REJECT_CONTRACT\",
    \"contractType\": \"MILESTONE_CONTRACT\"
  }"

After this call the milestone moves to ready-to-settle. You will receive a CASHOUT_IN_PROGRESS webhook once you trigger settlement in the next step.

Admin settles

Distribute the funds. cashOutAmountList must sum to exactly itemPrice. Note actorRole: CLIENT_ADMIN — only SETTLE uses this role.

bash

curl -s "$WAFFY_BASE_URL/contract-actions/external" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"contractId\": \"$MILESTONE_ID\",
    \"userId\": \"$WAFFY_ADMIN_ID\",
    \"actorRole\": \"CLIENT_ADMIN\",
    \"receiverId\": \"$SELLER_ID\",
    \"senderId\": \"$WAFFY_ADMIN_ID\",
    \"contractType\": \"MILESTONE_CONTRACT\",
    \"contractAction\": \"SETTLE_CONTRACT\",
    \"cashOutAmountList\": [
      { \"id\": \"$SELLER_ID\",      \"amountDue\": $SELLER_AMOUNT },
      { \"id\": \"$WAFFY_ADMIN_ID\", \"amountDue\": $BROKER_AMOUNT }
    ]
  }"

Settlement math — must be exact

The fee is calculated after payment based on the payment method used and your org's agreement — not pre-calculated at milestone creation. The total of all amountDue entries must equal itemPrice exactly — any mismatch rejects the call.

Waffy processes bank transfers. You will receive CASHOUT_IN_PROGRESS then COMPLETED webhooks when all parties are paid out.

Common mistakes

Step	Mistake	Fix
1–2	Skipping IBAN or address for seller	Cashout will be blocked until IBAN + address are on file. For buyer, only needed if they may receive a bank transfer refund.
3	itemPrice: 0 on milestone	Parent contract is 0. Milestone carries the real amount (1000).
4	senderRole: PROVIDER on milestone	Must be BROKER — matches the parent contract sender.
4	paymentMethods / isDeliverable / isInspectable on milestone	Org-level settings — passing per-milestone is rejected. Inspection is enabled for your org at onboarding, not per milestone.
5	isSender on PROVIDER	Omit entirely — passing it is rejected by the API.
5	BROKER missing arbitrator: true or isSender: true	Both fields are required on BROKER, no exceptions.
6	Reusing customer_token	Tokens expire in 60 min — fetch fresh immediately before redirecting to checkout.
6	Using WAFFY_CLIENT_ID vs client_id confusion	They are the same credential from your onboarding package.
8	actorRole: CLIENT_ADMIN on ACCEPT_CONTRACT	ACCEPT and REJECT use BROKER. Only SETTLE_CONTRACT uses CLIENT_ADMIN.
9	Skipping CONFIRM_INSPECTION and going straight to SETTLE_CONTRACT	With inspection enabled, settlement is blocked until CONFIRM_INSPECTION (or REJECT_CONTRACT) is called.
9	Calling CONFIRM_INSPECTION before the buyer signals acceptance	Wait for the buyer's in-app decision. Confirming early skips the buyer-protection step inspection is designed for.
9	actorRole: CLIENT_ADMIN on CONFIRM_INSPECTION or REJECT_CONTRACT	CONFIRM and REJECT use BROKER. Only SETTLE_CONTRACT uses CLIENT_ADMIN.
10	Using client_id as admin_id in cashOutAmountList	admin_id is the user ID from /api/users/me, not your client_id credential.
10	cashOutAmountList doesn't sum to itemPrice	All entries must sum to itemPrice exactly — over or under is rejected.
10	Calling SETTLE before CONFIRM_INSPECTION	SETTLE is only valid after CONFIRM_INSPECTION (or REJECT_CONTRACT) moves the milestone to ready-to-settle.