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

# Escrow overview

> Create and manage standard (single-payment) escrow links, and how the seller gets paid.

A **standard escrow** is a single-payment link: the buyer funds it once, and the
full amount is released to the seller on confirmation. This group covers creating
the link, editing it before it's funded, and the seller's claim path. For the
full state machine see [Escrow lifecycle](/concepts/escrow-lifecycle); for the
call-by-call walkthrough see [How it works](/concepts/how-it-works).

<Info>
  **`customer-id` = the seller** when creating. Edit, delete and claim are
  seller-only and act on the escrow's `paymentToken`. Buyer-side actions (funding,
  confirming) live under [Payments](/api-reference/payments/overview) and
  [Disputes](/api-reference/disputes/overview).
</Info>

## Endpoints

| Route                                                                      | Method & path                               | What it does                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create escrow](/api-reference/escrow/create-escrow)                       | `POST /v1/escrow/create`                    | Generates a standard escrow link. **`multipart/form-data`** (up to 5 images). Required: `amount`, `purpose`, `whoPays`. Returns `id` + `paymentToken`; `state: AWAITING_PAYMENT`. **`customer-id` = seller.** A merchant can't create an escrow for itself. |
| [Edit escrow](/api-reference/escrow/edit-escrow)                           | `PUT /v1/escrow/edit/{paymentToken}`        | Update amount/purpose/delivery/images. Allowed **only while `AWAITING_PAYMENT`** and only by the seller. New images are appended.                                                                                                                           |
| [Delete escrow](/api-reference/escrow/delete-escrow)                       | `DELETE /v1/escrow/delete/{paymentToken}`   | Removes an unfunded escrow. Allowed **only while `AWAITING_PAYMENT`**.                                                                                                                                                                                      |
| [Verify payment token](/api-reference/escrow/verify-payment-token)         | `GET /v1/escrow/verify/{paymentToken}`      | Resolves a link to its full escrow details, used by the buyer to preview before paying.                                                                                                                                                                     |
| [Claim funds](/api-reference/escrow/claim-funds)                           | `GET /v1/escrow/claim-funds/{paymentToken}` | Seller releases funds to themselves. Allowed **only when `OPENED` and the delivery window has elapsed**. Closes as `CLAIMED`.                                                                                                                               |
| [List escrow transactions](/api-reference/escrow/list-escrow-transactions) | `GET /v1/escrow/transactions`               | Paginated escrows for the caller. **`type` (`sales` or `buy`) is required.** Optional `status`, `categoryId`, `page`, `limit`.                                                                                                                              |

## How a standard escrow flows

<Steps>
  <Step title="Create (seller)">
    `POST /v1/escrow/create` → `AWAITING_PAYMENT`. Editable/deletable until funded.
  </Step>

  <Step title="Fund (buyer)">
    Buyer pays via [Pay escrow](/api-reference/payments/pay-escrow-buy) → `OPENED`.
  </Step>

  <Step title="Release">
    Buyer [confirms](/api-reference/disputes/buyer-confirm-payment-standard) →
    `COMPLETED`, or the seller [claims](/api-reference/escrow/claim-funds) after
    the window → `CLAIMED`.
  </Step>
</Steps>

<Warning>
  Selling more than one unit from a single link (`totalQuantity > 1`) changes this
  behaviour: each buyer gets a cloned escrow. Read
  [Multi-quantity escrows](/concepts/multi-quantity-escrows).
</Warning>