Onboard customers overview

Payluk is a merchant platform: your account holds a set of customers (role merchant_user) who act as buyers and sellers. Almost every escrow and payment action is performed on behalf of one of these customers via the customer-id header, so this is step 1 of any integration.

Creating and managing customers needs your key to belong to a merchant super-admin account. Acting as a customer (wallet, payments, escrows) is done by passing their ID in the customer-id header. See Merchant customers and Authentication.

Endpoints

Route	Method & path	What it does
Create merchant customer	`POST /v1/customer/create`	Onboards a buyer or seller under your account. Body: `firstname`, `lastname`, `email`, `phone`, `countryId`. Returns the customer `id` you’ll use as `customer-id`. Super-admin key required.
List merchant customers	`GET /v1/customers`	Paginated list of every customer on your account. Supports `page` / `limit`.
Get merchant customer	`GET /v1/customer/get/{customerId}`	Fetch a single customer’s profile by ID.
Update customer	`PUT /v1/customer/update/{customerId}`	Corrects a customer’s profile. Accepts any of `firstname`, `lastname`, `email` — at least one is required. `phone` and `bvn` are not editable here. Super-admin key required.
Update customer permissions	`PUT /v1/customer/permissions/{customerId}`	Toggle `canBuy` / `canSell`. A customer with `canBuy: false` is rejected at payment time; `canSell: false` blocks selling.
Block customer	`PUT /v1/customer/block/{customerId}`	Suspends a customer’s activity (status → `blocked`).
Unblock customer	`PUT /v1/customer/unblock/{customerId}`	Restores a blocked customer (status → `active`).
Get customer wallet	`GET /v1/wallet`	Returns `mainBalance` (spendable) and `escrowBalance` (locked in open escrows). Requires the `customer-id` header.

Typical order

Create the seller and the buyer

Two POST /v1/customer/create calls. Keep both returned IDs.

Set permissions

Give the seller canSell and the buyer canBuy.

Use them everywhere else

Pass the right customer-id on escrow, payment and dispute calls. Check balances any time with GET /v1/wallet.

Next: create the deal, or see the full end-to-end journey.

1. Onboard customers

2. Catalog (optional)

3. Create the deal: Escrow

4. Create the deal: Milestone Escrow

5. Stake & resolve: Vault Escrow

6. Fund it: Payments

7. Release & resolve: Disputes

Other: Debit Cards

Other: Crypto Whitelist

Other: Misc

Onboard customers overview

Endpoints

Typical order

​Endpoints

​Typical order

Endpoints

Typical order