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. Collect the buyer’s payment

Every payment comes in as an escrow payment through the Checkout SDK. Payluk has no direct deposits and no card payments: Checkout generates a temporary virtual account for the escrow and the buyer pays it by bank transfer. From your frontend, pass the escrow’s paymentToken (returned in step 1) to pay() with your publishable key:

import { initEscrowCheckout, pay } from 'payluk-escrow-inline-checkout';

initEscrowCheckout({ publicKey: '<YOUR_PUBLISHABLE_KEY>' });

await pay({
  paymentToken: 'PY_8AB12C9D3045',
  reference: 'order_2026_0001',
  redirectUrl: 'https://yourapp.com/checkout/complete',
  callback: (result) => console.log('Payment result', result),
});

The buyer is charged the escrow amount plus their share of the fee. When the transfer lands, the escrow moves to state: OPENED and funds are held.

On staging the checkout window shows a Pay from Payluk Test Bank button, so you can complete a payment without real money. See Payluk Test Bank.

4. 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. Collect the buyer’s payment

4. Confirm delivery

​1. Create an escrow

​2. Create a customer (the buyer)

​3. Collect the buyer’s payment

​4. Confirm delivery

1. Create an escrow

2. Create a customer (the buyer)

3. Collect the buyer’s payment

4. Confirm delivery