---
updatedAt: 2026-02-18T04:19:24.000Z
agentTools:
  projectIndex: https://pandascrow.readme.io/llms.txt
---

# Recurring

A recurring escrow contract for subscriptions, retainers, and periodic payment schedules.

## 🔁 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

```json
{
  "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": "jambtom@gmail.com",
      "expected_amount": 2000.00
    },
    {
      "name": "Dev Tom",
      "email": "devtom0x@gmail.com",
      "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"
}
```