--- updatedAt: 2026-09-24T08:16:57.000Z agentTools: projectIndex: https://pandascrow.readme.io/llms.txt --- # Onetime 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. * **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 | | `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 redirect to upon completion. | | `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) ```json { "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": "pandascrowhq.buyer@gmail.com", "phone": "+2348098765432" }, "seller_details": { "name": "Pandascrow Seller", "email": "pandascrowhq.seller@gmail.com", "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" } ```