Recurring

🔁 Recurring Escrow

Create a recurring escrow contract for automated, periodic payments. This type of escrow is ideal for subscriptions, installment plans, retainers, or any ongoing financial agreement that requires funds to be released at regular intervals.

📌 Use Case

Use this endpoint when you want to:

Automate subscription payments (e.g., SaaS, streaming services, memberships).
Structure installment-based transactions (e.g., phased project payments).
Manage retainer agreements for ongoing services (e.g., legal, consulting, maintenance).
Enable multi-contributor pools where multiple parties fund a recurring payment to a single receiver.
Define complete payment schedules upfront with automatic execution on due dates.

🧰 Features

Supports multiple cycle intervals (daily, weekly, monthly)
Automatic payment processing on scheduled due dates
Multi-contributor support for pooled funding
Configurable contributor minimums and maximums
Dispute protection for every cycle
Multiple payout methods (bank, crypto, mobile money)
Webhook callbacks for cycle events

🧾 Example Use Case

A SaaS platform charges clients $50/month for access. The client funds a recurring escrow, and payments are automatically released to the platform on the 1st of each month.
A group of tenants (5 contributors) each pay a portion of the monthly $2,500 rent into escrow. The funds are automatically released to the landlord on the 28th of every month.
A consultant agrees to a 6-month retainer at $2,000/month. The client funds the first month, and subsequent payments are triggered automatically on the same date each month.

🧱 Required Fields

Field	Type	Description
`uuid`	`string`	A unique reference for the escrow session
`escrow_type`	`string`	Must be set to `"recurring"`
`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 primary receiver (null if using contributors)
`title`	`string`	Short title of the recurring transaction
`currency`	`string`	Currency code (e.g. `USD`, `NGN`)
`amount`	`number`	Total amount to be collected per cycle
`description`	`string`	Detailed description of the recurring agreement
`how_dispute_is_handled`	`string`	Dispute method: `platform` or `arbitration`
`who_pay_fees`	`string`	Who covers transaction fees: `buyer`, `seller`, or `split`
`cycle`	`object`	Object defining the recurring schedule (see below)
`contributors`	`array`	(Optional) Array of participants for multi-party funding
`payout`	`object`	Object containing payout details for the receiver
`callback_url`	`string`	(Optional) URL to receive webhook events for each cycle

🔄 Cycle Object

Field	Type	Description
`cycle_interval`	`string`	Frequency: `daily`, `weekly`, or `monthly`
`minimum_contributors`	`integer`	Minimum contributors required (default: `1`)
`maximum_contributors`	`integer`	Maximum contributors allowed
`due_day_of_month`	`integer`	(Required for monthly) Day of month for payment (1-31)
`expected_amount`	`number`	Total amount expected per cycle
`due_date`	`string`	First payment due date in `YYYY-MM-DD` format

👥 Contributors Array (Optional)

Field	Type	Description
`name`	`string`	Full name of the contributor
`email`	`string`	Email address of the contributor
`expected_amount`	`number`	Amount this contributor pays per cycle

💰 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": "recurring",
  "initiator_role": "buyer",
  "initiator_id": "4b5c12fb-74f8-4dd5-b700-f825b29e7719",
  "receiver_id": null,
  "title": "Monthly Netflix Subscription 2",
  "currency": "NGN",
  "amount": 25000.00,
  "description": "Recurring subscription escrow for Netflix access.",
  "how_dispute_is_handled": "arbitration",
  "who_pay_fees": "buyer",
  "cycle": {
    "cycle_interval": "monthly",
    "minimum_contributors": 1,
    "maximum_contributors": 30,
    "due_day_of_month": 28,
    "expected_amount": 25000.00,
    "due_date": "2026-03-28"
  },
  "contributors": [
    {
      "name": "Jamb Tom",
      "email": "[email protected]",
      "expected_amount": 2000.00
    },
    {
      "name": "Dev Tom",
      "email": "[email protected]",
      "expected_amount": 2000.00
    }
  ],
  "payout": {
    "payout_type": "bank",
    "bank_name": "FIDELITY BANK",
    "bank_code": "077",
    "account_number": "6150222737",
    "account_name": "PRECIOUS TOM ANIEFIOK"
  },
  "callback_url": "app.pandascrow.io/recurring-webhook"
}