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": "08012345678",
    "countryId": "NG"
  }'

Send phone as digits only, with no leading +. countryId is optional: omit it and the customer inherits your merchant account’s country. It takes either an ISO code like NG or an id from 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 }'

This helper credits the wallet directly, so it skips the deposit path entirely.

Virtual accounts are deprecated and POST /v1/payment/virtual-account now returns 410. CBN rules require inflows to arrive as a direct escrow payment, so collect with the Checkout SDK rather than by issuing an account to pay into.

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

Build with AI

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