> ## 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. # Submit dispute > Open or reply to a dispute. Escrow must be `OPENED`. **Only the buyer can open a dispute**; the seller can only respond once the buyer has raised one, after which the merchant resolves it. **Milestone escrows cannot be disputed**; only standard escrows are eligible. Requires the `customer-id` header. Sent as `multipart/form-data` so evidence can be attached. ## OpenAPI ````yaml openapi.json POST /v1/escrow/submit-dispute/{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: support@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/submit-dispute/{paymentToken}: post: tags: - Disputes summary: Submit dispute description: >- Open or reply to a dispute. Escrow must be `OPENED`. **Only the buyer can open a dispute**; the seller can only respond once the buyer has raised one, after which the merchant resolves it. **Milestone escrows cannot be disputed**; only standard escrows are eligible. Requires the `customer-id` header. Sent as `multipart/form-data` so evidence can be attached. operationId: submitDispute parameters: - $ref: '#/components/parameters/CustomerIdHeader' - $ref: '#/components/parameters/PaymentToken' requestBody: required: true content: multipart/form-data: schema: type: object required: - message properties: message: type: string example: Item not as described file: type: string format: binary description: Optional evidence attachment. responses: '200': description: Dispute submitted. content: application/json: schema: $ref: '#/components/schemas/EscrowResponse' example: status: 200 message: Escrow dispute submitted successfully data: id: 6948fb43cb570eeef76285e3 amount: 1000 purpose: iPhone 13 Pro Max description: >- Black Titanium, White Titanium, Natural Titanium, Desert Titanium Titanium design Latest-generation Ceramic Shield front Textured matt glass back whoPays: buyer imageUrl: - >- https://mediacloud.me/media/bWVkaWEvaW1hZ2VzL29wdGltaXplL3Z0VjhwN0psSzlIMzhEVWxicWpmV1JZdUpuSUZNWlhEdU03UkVmeHEuanBn.jpg fee: 15 paymentToken: PY_KrWLqPd90314 sellerId: 6a19b57ffa797d3af379ca2a buyerId: 69fe44bbc2cd478224ced16f paidAt: '1766391073' status: DISPUTED state: OPENED logs: - DISPUTED channel: API isSeller: false dispute: - userId: 69fe44bbc2cd478224ced16f message: Item not as described; the seal was broken on arrival proofUrl: https://mediacloud.me/media/dispute-evidence.jpg createdAt: '1766394820' name: Ezumah profile: null type: buyer category: null completedAt: null approvedClaimBy: null refundedBy: null paymentId: 6948fd20cb570eeef76286a4 maxDelivery: 20 deliveryDetails: null deliveryTimeline: minutes totalQuantity: 1 settlementType: STANDARD milestones: [] createdAt: '2025-12-22T08:03:15.124Z' updatedAt: '2025-12-22T08:14:49.601Z' environment: live isMerchant: true merchantId: null '400': description: Action not allowed or dispute already submitted. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: notAllowed: summary: Action not allowed value: status: 400 message: Action not allowed data: {} already: summary: Already submitted value: status: 400 message: Buyer already submitted Dispute data: {} components: parameters: CustomerIdHeader: name: customer-id in: header required: true description: The merchant customer this request acts on behalf of. schema: type: string example: 665f1b2c9a1e4d0012ab3c01 PaymentToken: name: paymentToken in: path required: true description: The escrow's payment token (e.g. `PY_8AB12C9D3045`). schema: type: string example: PY_8AB12C9D3045 schemas: 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 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). ````