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

# Quickstart

> Create your first escrow payment link and walk it through to settlement.

This guide takes you from zero to a funded, settled escrow on the **staging**
environment. You'll need a `sk_test_` secret key from your Payluk dashboard.

<Note>
  Set the API Reference server to **Staging** (`https://staging.api.payluk.ng`)
  and paste your `sk_test_` key into the **Authorization** field to run any
  request live from the docs.
</Note>

## 1. Create an escrow

Generate a payment link. The seller is the owner of the API key.

```bash theme={null}
curl -X POST https://staging.api.payluk.ng/v1/escrow/create \
  -H "Authorization: Bearer sk_test_replace_me" \
  -F "amount=150000" \
  -F "purpose=MacBook Pro 14\"" \
  -F "whoPays=both" \
  -F "maxDelivery=3" \
  -F "deliveryTimeline=days"
```

The response contains a `paymentToken`; this is your shareable payment link
reference.

```json theme={null}
{
  "status": 201,
  "message": "Created successfully",
  "data": {
    "paymentToken": "PY_8AB12C9D3045",
    "amount": 150000,
    "fee": 3750,
    "state": "AWAITING_PAYMENT",
    "status": "PENDING"
  }
}
```

## 2. Create a customer (the buyer)

Most buyer-side actions act on behalf of a **merchant customer**, identified by
the `customer-id` header. Create one first:

```bash theme={null}
curl -X POST https://staging.api.payluk.ng/v1/customer/create \
  -H "Authorization: Bearer sk_test_replace_me" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Ada",
    "lastname": "Eze",
    "email": "ada@example.com",
    "phone": "+2348012345678",
    "countryId": "665f1b2c9a1e4d0012ab3c40"
  }'
```

<Tip>
  Need a `countryId`? Call [Get countries](/api-reference/misc/get-countries).
</Tip>

## 3. Fund the buyer's wallet (staging helper)

On staging you can top up a customer's wallet once per day to simulate a
deposit:

```bash theme={null}
curl -X POST https://staging.api.payluk.ng/v1/payment/topup \
  -H "Authorization: Bearer sk_test_replace_me" \
  -H "Content-Type: application/json" \
  -H "customer-id: 665f1b2c9a1e4d0012ab3c01" \
  -d '{ "amount": 200000 }'
```

## 4. Pay the escrow

Fund the escrow from the buyer's wallet. Payluk charges the escrow amount plus
the buyer's share of the fee.

```bash theme={null}
curl -X POST https://staging.api.payluk.ng/v1/payment/escrow \
  -H "Authorization: Bearer sk_test_replace_me" \
  -H "Content-Type: application/json" \
  -H "customer-id: 665f1b2c9a1e4d0012ab3c01" \
  -d '{
    "gateway": "WALLET",
    "transactionType": "ESCROW",
    "reference": "ESC_REF_98765",
    "escrowDetails": { "escrowId": "665f1b2c9a1e4d0012ab3c10" }
  }'
```

The escrow now moves to `state: OPENED`; funds are held.

## 5. Confirm delivery

When the buyer is satisfied, confirm the payment. This releases funds to the
seller and completes the escrow.

```bash theme={null}
curl -X POST https://staging.api.payluk.ng/v1/escrow/confirm-payment/665f1b2c9a1e4d0012ab3c10 \
  -H "Authorization: Bearer sk_test_replace_me" \
  -H "customer-id: 665f1b2c9a1e4d0012ab3c01"
```

```json theme={null}
{
  "status": 200,
  "message": "Escrow updated successfully",
  "data": { "state": "CLOSED", "status": "COMPLETED" }
}
```

🎉 That's a full escrow lifecycle. Next, read how the
[escrow lifecycle](/concepts/escrow-lifecycle) and
[fees](/concepts/fees-and-settlement) work in detail.