Onetime

🧾 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.
NEW - Offer bank transfer payments via Dynamic Virtual Accounts (DVA) for NGN transactions.

🧰 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
NEW - Dual payment gateway support:
- Payment Link (default) - Paystack/Stripe checkout
- Virtual Account - Generate a unique bank account for NGN bank transfers

🧾 Example Use Case

A freelance designer and a client agree on a $500 logo 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.
NEW - A Nigerian merchant sells goods for ₦50,000. The buyer chooses to pay via bank transfer to a generated virtual account, avoiding card fees and providing a familiar payment experience.

🧱 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`, `seller`, or `broker`
`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
`payment_gateway`	string	(Optional) Payment method: `payment_link` or `virtual_account`. `virtual_account` only available for NGN
`expiry_hours`	integer	(Optional) DVA expiry in hours (1-24, default: 1)

🧱 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

💳 Payment Gateway Options

Gateway	Description	Currency Support	Use Case
`payment_link`	Generates a payment link via Paystack/Stripe checkout	All supported currencies	Default option for card payments
`virtual_account`	Generates a unique 10-digit 9PSB virtual account number for bank transfer	NGN only	Offer bank transfer payments to Nigerian customers

🔑 Virtual Account (DVA) Details

When payment_gateway is set to virtual_account:

A unique 10-digit 9PSB virtual account number is generated
The account is linked to the escrow amount (EXACT amount required)
Account expires after expiry_hours (1-24 hours, default: 1)
Funds are automatically credited to escrow when the customer transfers the exact amount
Both buyer and broker receive the virtual account details in their confirmation emails

⚠️ Important Notes:

Virtual accounts only work with currency: "NGN"
If payment_gateway: "virtual_account" is used with a non-NGN currency, the system automatically falls back to payment_link
The customer must transfer the exact amount to the generated account number

📦 Example Payloads

🔗 Payment Link (Default)

{
  "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"
  },
  "callback_url": "app.wiserlance.com/success",
  "payment_gateway": "payment_link"
}