> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payluk.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard customers overview

> Create and manage the buyers and sellers that transact under your merchant account.

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.

<Info>
  **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](/concepts/merchant-customers) and
  [Authentication](/authentication#the-customer-id-header).
</Info>

## Endpoints

| Route                                                                                        | Method & path                               | What it does                                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create merchant customer](/api-reference/merchant-customers/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](/api-reference/merchant-customers/list-merchant-customers)         | `GET /v1/customers`                         | Paginated list of every customer on your account. Supports `page` / `limit`.                                                                                                                      |
| [Get merchant customer](/api-reference/merchant-customers/get-merchant-customer)             | `GET /v1/customer/get/{customerId}`         | Fetch a single customer's profile by ID.                                                                                                                                                          |
| [Update customer](/api-reference/merchant-customers/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](/api-reference/merchant-customers/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](/api-reference/merchant-customers/block-customer)                           | `PUT /v1/customer/block/{customerId}`       | Suspends a customer's activity (status → `blocked`).                                                                                                                                              |
| [Unblock customer](/api-reference/merchant-customers/unblock-customer)                       | `PUT /v1/customer/unblock/{customerId}`     | Restores a blocked customer (status → `active`).                                                                                                                                                  |
| [Get customer wallet](/api-reference/merchant-customers/get-customer-wallet)                 | `GET /v1/wallet`                            | Returns `mainBalance` (spendable) and `escrowBalance` (locked in open escrows). **Requires the `customer-id` header.**                                                                            |

## Typical order

<Steps>
  <Step title="Create the seller and the buyer">
    Two `POST /v1/customer/create` calls. Keep both returned IDs.
  </Step>

  <Step title="Set permissions">
    Give the seller `canSell` and the buyer `canBuy`.
  </Step>

  <Step title="Use them everywhere else">
    Pass the right `customer-id` on escrow, payment and dispute calls. Check
    balances any time with `GET /v1/wallet`.
  </Step>
</Steps>

Next: [create the deal](/api-reference/escrow/overview), or see the full
[end-to-end journey](/concepts/how-it-works).