> ## 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. # Declare vault winner > The merchant names the winning participant. Every stake is released from the participants' escrow balances and the **whole pot minus the platform fee** is credited to the winner's main balance. The escrow closes as `COMPLETED`. There is no dispute flow; the merchant is expected to have verified the outcome before calling this. Merchant-only: do **not** send the `customer-id` header. ## OpenAPI ````yaml openapi.json POST /v1/escrow/vault/winner/{paymentToken} 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/winner/{paymentToken}: post: tags: - Vault Escrow summary: Declare vault winner description: >- The merchant names the winning participant. Every stake is released from the participants' escrow balances and the **whole pot minus the platform fee** is credited to the winner's main balance. The escrow closes as `COMPLETED`. There is no dispute flow; the merchant is expected to have verified the outcome before calling this. Merchant-only: do **not** send the `customer-id` header. operationId: declareVaultWinner parameters: - $ref: '#/components/parameters/PaymentToken' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeclareVaultWinnerInput' example: winnerId: 665f1b2c9a1e4d0012ab3c40 responses: '200': description: Winner paid; vault completed. content: application/json: schema: $ref: '#/components/schemas/EscrowResponse' example: status: 200 message: Vault winner declared successfully data: id: 665f1b2c9a1e4d0012ab3c50 amount: 1000000 fee: 25000 paymentToken: PY_7CD34E0F5162 state: CLOSED status: COMPLETED completedAt: '1784990000' settlementType: VAULT participants: - customerId: 665f1b2c9a1e4d0012ab3c40 amount: 600000 status: RELEASED stakedAt: '1784900000' settledAt: '1784990000' - customerId: 665f1b2c9a1e4d0012ab3c41 amount: 400000 status: RELEASED stakedAt: '1784900000' settledAt: '1784990000' winnerId: 665f1b2c9a1e4d0012ab3c40 '400': description: Invalid winner or the vault is not open. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: notParticipant: summary: Winner not a participant value: status: 400 message: Winner must be a participant of this vault data: {} settled: summary: Already settled value: status: 400 message: Vault has already been settled data: {} notVault: summary: Not a vault escrow value: status: 400 message: Escrow is not a vault escrow data: {} notFound: summary: Unknown token value: status: 400 message: Escrow not found data: {} notOwner: summary: Another merchant's vault value: status: 400 message: Vault does not belong to this merchant data: {} '401': $ref: '#/components/responses/AccessDenied' components: parameters: PaymentToken: name: paymentToken in: path required: true description: The escrow's payment token (e.g. `PY_8AB12C9D3045`). schema: type: string example: PY_8AB12C9D3045 schemas: DeclareVaultWinnerInput: type: object required: - winnerId properties: winnerId: type: string description: The winning participant's customerId. example: 665f1b2c9a1e4d0012ab3c40 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: {} 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). ````