> ## 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. # Create vault escrow > Creates a **funded** vault escrow in one call. Every participant must be a customer of the merchant with the stake available in their **main balance**; each stake is locked into the participant's own **escrow balance** immediately (all-or-nothing: if any stake cannot be locked, everything is rolled back). Merchant-only: do **not** send the `customer-id` header. Rules: at least 2 unique participants, positive integer stakes, and the derived pot (sum of stakes) must be at least 1000. ## OpenAPI ````yaml openapi.json POST /v1/escrow/vault/create openapi: 3.0.3 info: title: Payluk ThirdParty API version: 1.0.0 description: >- Merchant / Business API for the Payluk escrow and payments platform. All routes are mounted under `/v1` and authenticated with a secret key. Every response uses the standard envelope `{ status, message, data }`. contact: name: Payluk Developer Support email: developers@payluk.ng url: https://payluk.ng servers: - url: https://staging.api.payluk.ng description: 'Staging: use sk_test_ keys here for safe testing' - url: https://api.payluk.ng description: 'Production: use sk_live_ keys' security: - bearerAuth: [] tags: - name: Escrow description: Create and manage standard escrow payment links. - name: Milestone Escrow description: Escrows that release funds in parts as milestones are confirmed. - name: Vault Escrow description: >- Merchant-only pooled-stake escrows: customers stake from their wallets and the merchant declares the winner. - name: Categories description: Organise escrows into merchant-defined categories. - name: Merchant Customers description: Manage the buyers and sellers that transact under your merchant account. - name: Disputes description: Confirm deliveries, raise disputes and resolve them. - name: Payments description: Fund wallets and escrows, verify references and manage payout details. - name: Debit Cards description: List and remove customers' saved debit cards. - name: Crypto Whitelist description: Manage whitelisted crypto withdrawal addresses. - name: Misc description: Supporting reference data. paths: /v1/escrow/vault/create: post: tags: - Vault Escrow summary: Create vault escrow description: >- Creates a **funded** vault escrow in one call. Every participant must be a customer of the merchant with the stake available in their **main balance**; each stake is locked into the participant's own **escrow balance** immediately (all-or-nothing: if any stake cannot be locked, everything is rolled back). Merchant-only: do **not** send the `customer-id` header. Rules: at least 2 unique participants, positive integer stakes, and the derived pot (sum of stakes) must be at least 1000. operationId: createVaultEscrow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVaultEscrowInput' example: purpose: FIFA tournament stake description: Winner takes all; final on Saturday participants: - customerId: 665f1b2c9a1e4d0012ab3c40 amount: 600000 - customerId: 665f1b2c9a1e4d0012ab3c41 amount: 400000 responses: '201': description: Vault escrow created and funded (`OPENED` / `ONGOING`). content: application/json: schema: $ref: '#/components/schemas/EscrowResponse' example: status: 201 message: Vault escrow created successfully data: id: 665f1b2c9a1e4d0012ab3c50 amount: 1000000 purpose: FIFA tournament stake fee: 25000 paymentToken: PY_7CD34E0F5162 paidAt: '1784900000' state: OPENED status: ONGOING settlementType: VAULT participants: - customerId: 665f1b2c9a1e4d0012ab3c40 amount: 600000 status: STAKED stakedAt: '1784900000' settledAt: null - customerId: 665f1b2c9a1e4d0012ab3c41 amount: 400000 status: STAKED stakedAt: '1784900000' settledAt: null winnerId: null createdAt: '2026-07-24T10:15:00.000Z' updatedAt: '2026-07-24T10:15:00.000Z' '400': description: >- Validation failed, a participant does not belong to the merchant, or a stake cannot be covered. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: tooFew: summary: Too few participants value: status: 400 message: A vault escrow must have at least 2 participants data: {} duplicate: summary: Duplicate participant value: status: 400 message: Each participant may only appear once in a vault data: {} minimum: summary: Pot below minimum value: status: 400 message: The total staked amount must be at least 1000 data: {} notCustomer: summary: Not a merchant customer value: status: 400 message: >- Participant 665f1b2c9a1e4d0012ab3c40 is not a customer of this merchant data: {} blocked: summary: Blocked customer value: status: 400 message: >- Participant 665f1b2c9a1e4d0012ab3c40 is not an active customer data: {} balance: summary: Insufficient balance value: status: 400 message: >- Participant 665f1b2c9a1e4d0012ab3c40 has insufficient main balance for their stake data: {} '401': $ref: '#/components/responses/AccessDenied' components: schemas: CreateVaultEscrowInput: type: object required: - purpose - participants properties: purpose: type: string example: FIFA tournament stake description: type: string example: Winner takes all; final on Saturday categoryId: type: string example: 665f1b2c9a1e4d0012ab3c30 participants: type: array minItems: 2 description: >- At least 2 unique customers. The escrow amount is derived as the sum of the stakes and must be at least 1000. items: $ref: '#/components/schemas/VaultParticipantInput' EscrowResponse: type: object properties: status: type: integer example: 200 message: type: string example: Operation successful data: $ref: '#/components/schemas/Escrow' ApiError: type: object description: Standard error envelope. properties: status: type: integer example: 400 message: type: string example: Action not allowed data: type: object example: {} VaultParticipantInput: type: object required: - customerId - amount properties: customerId: type: string description: A customer of the requesting merchant. example: 665f1b2c9a1e4d0012ab3c40 amount: type: integer minimum: 1 description: The stake this customer locks, debited from their main balance. example: 600000 Escrow: type: object properties: id: type: string example: 665f1b2c9a1e4d0012ab3c10 amount: type: integer example: 150000 purpose: type: string example: MacBook Pro 14" description: type: string example: Space grey, sealed whoPays: type: string enum: - buyer - seller - both example: both imageUrl: type: array items: type: string example: - https://cdn.payluk.ng/escrow/abc.png fee: type: integer example: 3750 paymentToken: type: string example: PY_8AB12C9D3045 paidAt: type: string nullable: true example: null status: $ref: '#/components/schemas/EscrowStatus' state: $ref: '#/components/schemas/EscrowState' channel: type: string example: API isSeller: type: boolean example: true dispute: type: array nullable: true items: type: object example: null category: type: object nullable: true example: null completedAt: type: string nullable: true example: null maxDelivery: type: integer example: 3 deliveryTimeline: type: string example: days totalQuantity: type: integer example: 1 settlementType: $ref: '#/components/schemas/SettlementType' milestones: type: array items: $ref: '#/components/schemas/Milestone' participants: type: array nullable: true description: 'VAULT escrows only: the customers staking into the pot.' items: $ref: '#/components/schemas/VaultParticipant' winnerId: type: string nullable: true description: >- VAULT escrows only: the participant declared the winner by the merchant. example: null createdAt: type: string example: '2026-06-22T10:15:00.000Z' updatedAt: type: string example: '2026-06-22T10:15:00.000Z' EscrowStatus: type: string description: High-level escrow status. enum: - PENDING - ONGOING - COMPLETED - REFUNDED - CLAIMED - DISPUTED - INVESTIGATING EscrowState: type: string description: Lifecycle state of the escrow. enum: - AWAITING_PAYMENT - OPENED - CLOSED SettlementType: type: string enum: - STANDARD - MILESTONE - VAULT Milestone: type: object properties: id: type: string example: 665f1b2c9a1e4d0012ab3c21 title: type: string example: Design description: type: string example: Figma mockups amount: type: integer example: 300000 dueDate: type: string nullable: true example: '2026-07-15' customerId: type: string nullable: true description: >- Optional beneficiary. When set, releasing this milestone credits this customer's main balance instead of the seller's. example: null status: type: string enum: - PENDING - RELEASED example: PENDING releasedAt: type: string nullable: true example: null VaultParticipant: type: object properties: customerId: type: string example: 665f1b2c9a1e4d0012ab3c40 amount: type: integer example: 600000 status: type: string enum: - STAKED - RELEASED - REFUNDED example: STAKED stakedAt: type: string description: Unix timestamp (seconds) the stake was locked. example: '1784900000' settledAt: type: string nullable: true description: Unix timestamp (seconds) the stake was released or refunded. example: null responses: AccessDenied: description: Access denied. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: status: 401 message: Access denied data: {} securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your secret key as a Bearer token. The key prefix selects the environment: `sk_test_...` (test) or `sk_live_...` (live). ````