A single-use escrow contract for fixed-price projects or purchases.
🧾 One-Time Escrow
Create a one-time escrow contract between a buyer and a seller. This type of escrow is ideal for single, non-recurring payments tied to a specific project, product, or service.
📌 Use Case
Use this endpoint when you want to:
- Secure payment for a one-off service (e.g., freelance work) or product (e.g., e-commerce sale).
- Define delivery expectations, inspection periods, and dispute resolution preferences.
- Support both freelancers and merchants looking to transact safely with clients or customers.
- Provide buyer and seller contact details for transparency and documentation.
🧰 Features
- Supports multiple currencies (e.g.
USD,NGN) - Inspection and dispute windows to protect both parties
- Optional PRD or documentation file URL
- Callback URL for webhook updates
- Configurable number of reviews and payout settings
🧾 Example Use Case
- A freelance designer and a client agree on a
$500logo design project. The client (buyer) funds the escrow. The designer (seller) completes the work. After a 5-day inspection period, the funds are released. - An online merchant sells a custom furniture piece for
$1,200. The buyer pays into escrow. Once the product is delivered and inspected, the funds are released to the seller.
🧱 Required Fields
| Field | Type | Description |
|---|---|---|
uuid | string | A unique reference for the escrow session |
escrow_type | string | Should be set to "onetime" |
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 transaction |
currency | string | Currency code (e.g. USD, NGN) |
description | string | Detailed description of the service or product |
acceptance_criteria | string | Criteria that must be met for acceptance |
inspection_period | string | Number of days the buyer has to inspect the delivery |
no_reviews | string | Number of review rounds allowed |
delivery_date | string | Expected 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 |
amount | number | Total amount to be held in escrow |
partner_escrow_fee | number | Partner fee amount (if applicable) |
dispute_window | string | Number of days available to open a dispute after delivery |
set_payout | boolean | Whether to set payout details immediately |
prd_url | string | (Optional) URL of uploaded project brief or product document |
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 | (Conditional) Object containing payout details for the seller |
callback_url | string | (Optional) URL to receive webhook events |
🧱 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": "4b5c12fb-74f8-4dd5-b700-f825b29e7719",
"escrow_type": "onetime",
"initiator_role": "seller",
"initiator_id": "4b5c12fb-74f8-4dd5-b700-f825b29e7719",
"receiver_id": null,
"title": "Purchase #48407312929 from Store ZYX",
"currency": "USD",
"description": "Purchase 10 Ton of metal",
"acceptance_criteria": "Hello world, this is an acceptance criteria",
"inspection_period": "2",
"no_reviews": "2",
"delivery_date": "2025-11-06",
"how_dispute_is_handled": "platform",
"who_pay_fees": "seller",
"amount": 350,
"partner_escrow_fee": 0.00,
"dispute_window": "5",
"set_payout": true,
"prd_url": "",
"buyer_details": {
"name": "Pandascrow Buyer",
"email": "[email protected]",
"phone": "+2348098765432"
},
"seller_details": {
"name": "Pandascrow Seller",
"email": "[email protected]",
"phone": "+2348098765433"
},
"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": ""
},
"callback_url": "app.wiserlance.com/success"
}