Quickstart

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.

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.

1. Create an escrow

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

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.

{
  "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:

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": "[email protected]",
    "phone": "+2348012345678",
    "countryId": "665f1b2c9a1e4d0012ab3c40"
  }'

Need a countryId? Call Get countries.

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:

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.

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.

curl -X POST https://staging.api.payluk.ng/v1/escrow/confirm-payment/665f1b2c9a1e4d0012ab3c10 \
  -H "Authorization: Bearer sk_test_replace_me" \
  -H "customer-id: 665f1b2c9a1e4d0012ab3c01"

{
  "status": 200,
  "message": "Escrow updated successfully",
  "data": { "state": "CLOSED", "status": "COMPLETED" }
}

🎉 That’s a full escrow lifecycle. Next, read how the escrow lifecycle and fees work in detail.

Get started

The merchant journey

Core concepts

Guides

Reference

1. Create an escrow

2. Create a customer (the buyer)

3. Fund the buyer’s wallet (staging helper)

4. Pay the escrow

5. Confirm delivery

​1. Create an escrow

​2. Create a customer (the buyer)

​3. Fund the buyer’s wallet (staging helper)

​4. Pay the escrow

​5. Confirm delivery

1. Create an escrow

2. Create a customer (the buyer)

3. Fund the buyer’s wallet (staging helper)

4. Pay the escrow

5. Confirm delivery