> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payluk.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault escrows

> Pool stakes from two or more customers and pay the whole pot to the winner you declare.

A **vault escrow** is a merchant-only, pooled-stake escrow. Two or more of your
customers each lock an agreed stake from their own main balance, and you, the
merchant, declare the winner, who receives the whole pot minus the platform
fee. It has `settlementType: VAULT` and carries a `participants[]` array.

This suits competition-style products: head-to-head wagers between two
customers, or full **tournament mode** with any number of participants staking
into one pot.

<Warning>
  Vaults have **no dispute flow**. You are the arbiter: verify the outcome
  off-platform before declaring the winner. Settlement is final.
</Warning>

## Rules

When you call [Create vault escrow](/api-reference/vault-escrow/create-vault-escrow):

<Check>At least **2 participants** are required; there is no upper limit.</Check>
<Check>Every participant must be **your customer** (created via [Create merchant customer](/api-reference/merchant-customers/create-merchant-customer)) and **active** (not blocked).</Check>
<Check>Each participant may appear **only once**, and every stake is a **positive integer**.</Check>
<Check>The pot (the sum of all stakes) must be **at least 1000**. The escrow `amount` is derived from it; you don't send an amount.</Check>
<Check>Every participant must have their stake **available in their main balance** at creation. Funding is all-or-nothing: if any stake cannot be locked, nothing is.</Check>
<Check>Vault routes are **merchant-only**: never send the `customer-id` header.</Check>

```json theme={null}
{
  "purpose": "FIFA tournament stake",
  "participants": [
    { "customerId": "665f1b2c9a1e4d0012ab3c40", "amount": 600000 },
    { "customerId": "665f1b2c9a1e4d0012ab3c41", "amount": 400000 }
  ]
}
```

## How money moves

<Steps>
  <Step title="Stakes lock at creation">
    Each participant's stake moves from their **main balance** into their own
    **escrow balance**. The vault is created already funded (`OPENED` /
    `ONGOING`) with every participant `STAKED`. No payment step follows.
  </Step>

  <Step title="Winner takes the pot">
    [Declare vault winner](/api-reference/vault-escrow/declare-vault-winner)
    empties every stake and credits the winner's main balance with the **pot
    minus the platform fee**. Participants become `RELEASED` and the vault
    closes as `COMPLETED`.
  </Step>

  <Step title="Or everyone is refunded, minus fees">
    [Cancel vault escrow](/api-reference/vault-escrow/cancel-vault-escrow)
    returns each stake to its owner's main balance **minus that participant's
    pro-rata share of the fee**. Participants become `REFUNDED` and the vault
    closes as `REFUNDED`.
  </Step>
</Steps>

<Info>
  The platform fee is calculated on the pot using your merchant fee configuration
  (see [fees & settlement](/concepts/fees-and-settlement)) and is collected
  **whether the vault completes or is cancelled**. Merchant commission settles
  from the fee in both outcomes.
</Info>

## Participant statuses

| Status     | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| `STAKED`   | The stake is locked in the participant's escrow balance.         |
| `RELEASED` | The stake was paid out to the declared winner.                   |
| `REFUNDED` | The stake was returned (minus the fee share) after cancellation. |

## Vault vs. standard and milestone escrows

|              | Standard         | Milestone                           | Vault                              |
| ------------ | ---------------- | ----------------------------------- | ---------------------------------- |
| Funded by    | One buyer        | One buyer                           | **2+ participants**                |
| Funding step | Separate payment | Separate payment                    | **At creation**                    |
| Released by  | Buyer confirms   | Buyer confirms each milestone       | **Merchant declares winner**       |
| Recipient    | Seller           | Seller or per-milestone beneficiary | **The winning participant**        |
| Disputes     | Yes              | Yes                                 | **None (merchant is the arbiter)** |