Skip to main content
POST
/
v1
/
escrow
/
create
Create escrow
curl --request POST \
  --url https://staging.api.payluk.ng/v1/escrow/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'customer-id: <customer-id>' \
  --form amount=150000 \
  --form 'purpose=MacBook Pro 14"' \
  --form whoPays=both \
  --form 'description=Space grey, sealed' \
  --form maxDelivery=3 \
  --form deliveryTimeline=days \
  --form totalQuantity=1 \
  --form categoryId=665f1b2c9a1e4d0012ab3c30 \
  --form imageUrl='@example-file'
{
  "status": 201,
  "message": "Created successfully",
  "data": {
    "id": "665f1b2c9a1e4d0012ab3c10",
    "amount": 150000,
    "purpose": "MacBook Pro 14\"",
    "description": "Space grey, sealed",
    "whoPays": "both",
    "imageUrl": [
      "https://cdn.payluk.ng/escrow/abc.png"
    ],
    "fee": 3750,
    "paymentToken": "PY_8AB12C9D3045",
    "paidAt": null,
    "status": "PENDING",
    "state": "AWAITING_PAYMENT",
    "logs": [],
    "channel": "API",
    "isSeller": true,
    "dispute": null,
    "paymentDetails": null,
    "category": null,
    "completedAt": null,
    "approvedClaimBy": null,
    "refundedBy": null,
    "maxDelivery": 3,
    "deliveryTimeline": "days",
    "totalQuantity": 1,
    "settlementType": "STANDARD",
    "milestones": [],
    "createdAt": "2026-06-22T10:15:00.000Z",
    "updatedAt": "2026-06-22T10:15:00.000Z"
  }
}

Authorizations

​
Authorization
string
header
required

Your secret key as a Bearer token. The key prefix selects the environment: sk_test_... (test) or sk_live_... (live).

Headers

​
customer-id
string
required

The merchant customer this request acts on behalf of.

Body

multipart/form-data
​
amount
integer
required

Escrow amount in kobo-less major units (NGN). Must be a positive integer.

Example:

150000

​
purpose
string
required

Short title of what is being sold.

Example:

"MacBook Pro 14\""

​
whoPays
enum<string>
required

Which party pays the Payluk fee.

Available options:
buyer,
seller,
both
Example:

"both"

​
description
string
Example:

"Space grey, sealed"

​
maxDelivery
integer

Length of the delivery window, in deliveryTimeline units.

Example:

3

​
deliveryTimeline
enum<string>
Available options:
minutes,
hours,
days
Example:

"days"

​
totalQuantity
integer
Example:

1

​
categoryId
string
Example:

"665f1b2c9a1e4d0012ab3c30"

​
imageUrl
file

Product image. Attach the field up to 5 times to upload multiple images.

Response

Escrow created.

​
status
integer
Example:

200

​
message
string
Example:

"Operation successful"

​
data
object