> ## 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 escrow overview

> Pool stakes from two or more of your 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 amount ("stake") from their own **main balance**
into their own **escrow balance**, and you, the merchant, later declare the
winner, who receives the **whole pot minus the platform fee**. It has
`settlementType: VAULT` and carries a `participants[]` array. See
[Vault escrows](/concepts/vault-escrows) for the concept.

<Info>
  There is **no funding step and no dispute flow**. The vault is created already
  funded (every stake is verified and locked in the create call), and settlement
  is entirely merchant-driven: you are expected to verify the outcome off-platform
  before declaring the winner.
</Info>

## Endpoints

| Route                                                                    | Method & path                                 | What it does                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create vault escrow](/api-reference/vault-escrow/create-vault-escrow)   | `POST /v1/escrow/vault/create`                | Creates a **funded** vault. Rules: **≥ 2 unique participants**, each a customer of yours with the stake available in their main balance, and the pot (sum of stakes) **≥ 1000**. All-or-nothing: if any stake cannot be locked, everything rolls back. **No `customer-id` header.** |
| [Declare vault winner](/api-reference/vault-escrow/declare-vault-winner) | `POST /v1/escrow/vault/winner/{paymentToken}` | Pays the pot **minus the platform fee** to the named participant's main balance and closes the vault as `COMPLETED`. **No `customer-id` header.**                                                                                                                                   |
| [Cancel vault escrow](/api-reference/vault-escrow/cancel-vault-escrow)   | `POST /v1/escrow/vault/cancel/{paymentToken}` | Returns each stake to its owner's main balance **minus their pro-rata share of the fee**: the fee is collected either way. Closes the vault as `REFUNDED`. **No `customer-id` header.**                                                                                             |
| [Get vault escrow](/api-reference/vault-escrow/get-vault-escrow)         | `GET /v1/escrow/vault/{paymentToken}`         | Returns the vault with its `participants[]` and, once declared, the `winnerId`. **No `customer-id` header.**                                                                                                                                                                        |

## How a vault escrow flows

<Steps>
  <Step title="Create with participants (merchant)">
    `POST /v1/escrow/vault/create` with a `participants[]` array of
    `{ customerId, amount }`. Each stake is debited from the customer's main
    balance and locked in their own escrow balance; the vault is born
    `OPENED` / `ONGOING`.
  </Step>

  <Step title="The event plays out (off-platform)">
    Your customers compete, bet, or complete whatever the vault was staked on.
    You verify the outcome yourself; Payluk does not arbitrate vaults.
  </Step>

  <Step title="Declare the winner (merchant)">
    `POST …/vault/winner/{paymentToken}` with `{ winnerId }`. The winner's main
    balance is credited with the pot minus the fee; the vault closes as
    `COMPLETED`.
  </Step>

  <Step title="Or cancel">
    `POST …/vault/cancel/{paymentToken}` returns every stake minus its pro-rata
    fee share and closes the vault as `REFUNDED`.
  </Step>
</Steps>