🧩 Milestone Escrow

Create a milestone-based escrow contract for projects broken into phases. Funds are held in a master escrow and released incrementally as each predefined milestone is completed and approved. This structure ensures continuous cash flow for the seller and staged delivery assurance for the buyer.

📌 Use Case

Use this endpoint when you want to:

Manage complex, long-term projects with multiple deliverables (e.g., software development, content marketing retainers).
Release funds incrementally upon the completion and approval of specific work stages.
Protect both parties by tying payment to the successful delivery of each project phase.
Reduce financial risk by avoiding large, single upfront payments.

🧰 Features

Create a parent escrow that holds the total project funds.
Define multiple milestones with individual amounts, titles, and delivery dates.
Supports release of funds on a per-milestone basis upon buyer approval.
Maintain a clear audit trail of completed phases and remaining work.
Flexible deposit options: fund the full amount upfront or per milestone.

🧾 Example Use Case

A client hires a developer to build a mobile app for $10,000. The project is split into three milestones: Design ($2,000), Development ($6,000), and Testing & Launch ($2,000). The client can choose to fund the full $10,000 upfront or fund each milestone as work progresses. As the developer completes the designs and the client approves them, the first $2,000 is released. This process repeats for each subsequent milestone until the project is complete.

🧱 Required Fields

Field	Type	Description
`uuid`	string	A unique reference for the escrow session
`escrow_type`	string	Should be set to `"milestone"`
`initiator_role`	string	Role of the initiator: `buyer` or `seller`
`initiator_id`	string	Unique identifier of the user creating the escrow
`receiver_id`	string or null	Unique identifier of the other party (null if not registered)
`title`	string	Short title of the overall project
`currency`	string	Currency code (e.g. `USD`, `NGN`)
`description`	string	Detailed description of the project scope
`acceptance_criteria`	string	(Optional) Criteria that must be met for acceptance
`inspection_period`	string	Number of days the buyer has to inspect the delivery (per milestone)
`delivery_date`	string	Expected final delivery date in `YYYY-MM-DD` format
`how_dispute_is_handled`	string	Dispute method: `platform` or `arbitration`
`who_pay_fees`	string	Who covers transaction fees: `buyer`, `seller`, or `both`
`dispute_window`	string	Number of days available to open a dispute after delivery
`prd_url`	string	(Optional) URL of uploaded project brief or product document
`deposit_option`	string	How funds will be deposited: `full` (all upfront) or `milestone` (per phase)
`milestones`	array	An array of milestone objects (see table below)
`buyer_details`	object	Object containing name, email, and phone of the buyer
`seller_details`	object	Object containing name, email, and phone of the seller
`payout`	object	Object containing payout details for the seller (see table below)
`callback_url`	string	(Optional) URL to receive webhook events

🧱 Milestone Object Fields

Field	Type	Description
`title`	string	Short title of the milestone (e.g., "UI/UX Design Phase")
`description`	string	Detailed description of the work for this milestone
`amount`	number	Amount to be released upon completion of this milestone
`due_date`	string	Expected delivery date for this milestone (`YYYY-MM-DD`)
`inspection_hrs`	number	Number of hours the buyer has to inspect this milestone

🧱 Payout Object Fields

Field	Type	Description
`payout_type`	string	Payout method: `bank`, `crypto`, or `mobile_money`
`bank_name`	string	(Bank) Name of the bank
`bank_code`	string	(Bank) Bank code
`account_number`	string	(Bank) Account number
`account_name`	string	(Bank) Account holder name
`account_branch`	string	(Bank, Optional) Account branch
`bank_address`	string	(Bank, Optional) Bank address
`swift_code`	string	(Bank, Optional) SWIFT code for international transfers
`iban`	string	(Bank, Optional) IBAN for international transfers
`routing_number`	string	(Bank, Optional) Routing number
`sort_code`	string	(Bank, Optional) Sort code
`wallet_address`	string	(Crypto) Wallet address
`crypto_network`	string	(Crypto) Network (e.g., ERC20, TRC20, BEP20)
`token_symbol`	string	(Crypto) Token symbol (e.g., USDT, USDC)
`mobile_money_provider`	string	(Mobile Money) Provider name
`mobile_money_number`	string	(Mobile Money) Mobile money account number

📦 Example Payload

{
  "uuid": "d3216f5a-7147-48d7-82a2-a008d5d29382",
  "escrow_type": "milestone",
  "initiator_role": "buyer",
  "initiator_id": "d3216f5a-7147-48d7-82a2-a008d5d29382",
  "receiver_id": null,
  "title": "Website Development Project",
  "currency": "USD",
  "description": "A full-stack e-commerce platform for the client's store with 3 milestone phases.",
  "acceptance_criteria": "",
  "inspection_period": "5",
  "delivery_date": "2025-08-15",
  "how_dispute_is_handled": "arbitration",
  "who_pay_fees": "both",
  "dispute_window": "2",
  "prd_url": "",
  "deposit_option": "full",
  "milestones": [
    {
      "title": "UI/UX Design Phase",
      "description": "Wireframes and mockups for desktop & mobile",
      "amount": 500,
      "due_date": "2025-07-05",
      "inspection_hrs": 48
    },
    {
      "title": "Frontend Development",
      "description": "React + Tailwind implementation of designs",
      "amount": 15000,
      "due_date": "2025-07-15",
      "inspection_hrs": 72
    },
    {
      "title": "Backend Integration",
      "description": "Node.js API, database setup, and payment gateway",
      "amount": 10000,
      "due_date": "2025-08-05",
      "inspection_hrs": 72
    }
  ],
  "buyer_details": {
    "name": "Pandascrow HQ",
    "email": "pandascrowhq@gmail.com",
    "phone": "+2348098765432"
  },
  "seller_details": {
    "name": "Pandascrow HQ",
    "email": "pandascrowhq@gmail.com",
    "phone": "+2348098765432"
  },
  "payout": {
    "payout_type": "bank",
    "bank_name": "FIDELITY BANK",
    "bank_code": "077",
    "account_number": "6150222737",
    "account_name": "PRECIOUS TOM ANIEFIOK",
    "account_branch": "",
    "bank_address": "",
    "swift_code": "",
    "iban": "",
    "routing_number": "",
    "sort_code": "",
    "wallet_address": "",
    "crypto_network": "",
    "token_symbol": "",
    "mobile_money_provider": "",
    "mobile_money_number": ""
  }
}