Skip to main content
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.
Vaults have no dispute flow. You are the arbiter: verify the outcome off-platform before declaring the winner. Settlement is final.

​
Rules

When you call Create vault escrow:
At least 2 participants are required; there is no upper limit.
Every participant must be your customer (created via Create merchant customer) and active (not blocked).
Each participant may appear only once, and every stake is a positive integer.
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.
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.
Vault routes are merchant-only: never send the customer-id header.

​
How money moves

1

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.
2

Winner takes the pot

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.
3

Or everyone is refunded, minus fees

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.
The platform fee is calculated on the pot using your merchant fee configuration (see fees & settlement) and is collected whether the vault completes or is cancelled. Merchant commission settles from the fee in both outcomes.

​
Participant statuses

​
Vault vs. standard and milestone escrows