# Payluk API

> Merchant API for escrow payment links, milestones, disputes and payments on Payluk.

## Docs

- [Create category](https://docs.payluk.ng/api-reference/categories/create-category.md): Creates an escrow category. Sent as `multipart/form-data` so a cover image can be attached.
- [Delete category](https://docs.payluk.ng/api-reference/categories/delete-category.md)
- [Get category by ID](https://docs.payluk.ng/api-reference/categories/get-category-by-id.md)
- [List categories](https://docs.payluk.ng/api-reference/categories/list-categories.md)
- [Catalog (categories) — overview](https://docs.payluk.ng/api-reference/categories/overview.md): Optional product categories you can attach to escrows to organise your catalog.
- [Update category](https://docs.payluk.ng/api-reference/categories/update-category.md)
- [Update category position](https://docs.payluk.ng/api-reference/categories/update-category-position.md)
- [Add whitelisted address](https://docs.payluk.ng/api-reference/crypto-whitelist/add-whitelisted-address.md)
- [List whitelisted addresses](https://docs.payluk.ng/api-reference/crypto-whitelist/list-whitelisted-addresses.md)
- [Crypto whitelist — overview](https://docs.payluk.ng/api-reference/crypto-whitelist/overview.md): Manage the crypto addresses a customer is allowed to deposit from.
- [Remove whitelisted address](https://docs.payluk.ng/api-reference/crypto-whitelist/remove-whitelisted-address.md)
- [List customer debit cards](https://docs.payluk.ng/api-reference/debit-cards/list-customer-debit-cards.md): Requires the merchant to have the save-debit-cards feature enabled. Requires the `customer-id` header.
- [Debit cards — overview](https://docs.payluk.ng/api-reference/debit-cards/overview.md): List and remove the saved debit cards a merchant customer can reuse for payments.
- [Remove customer debit card](https://docs.payluk.ng/api-reference/debit-cards/remove-customer-debit-card.md)
- [Buyer confirm payment (standard)](https://docs.payluk.ng/api-reference/disputes/buyer-confirm-payment-standard.md): Buyer confirms delivery on a standard escrow; releases the full amount to the seller and completes the escrow. Requires the `customer-id` header (the buyer).
- [Get dispute by escrow ID](https://docs.payluk.ng/api-reference/disputes/get-dispute-by-escrow-id.md)
- [Get escrow feeds](https://docs.payluk.ng/api-reference/disputes/get-escrow-feeds.md): Merchant-wide feed of all customers' escrows. Must **not** send a `customer-id` header.
- [List all customers' disputes](https://docs.payluk.ng/api-reference/disputes/list-all-customers-disputes.md): Merchant-wide dispute feed. Must **not** send a `customer-id` header.
- [List my disputes](https://docs.payluk.ng/api-reference/disputes/list-my-disputes.md): Returns disputes for a specific customer. Requires the `customer-id` header.
- [Release & resolve (disputes) — overview](https://docs.payluk.ng/api-reference/disputes/overview.md): Confirm delivery to release funds, raise disputes, and resolve them as the merchant.
- [Resolve dispute](https://docs.payluk.ng/api-reference/disputes/resolve-dispute.md): Merchant resolves a dispute: `COMPLETED` releases to the seller; `REFUNDED` returns funds to the buyer. Must **not** send a `customer-id` header; the escrow must belong to one of the merchant's customers. Sent as `multipart/form-data`.
- [Submit dispute](https://docs.payluk.ng/api-reference/disputes/submit-dispute.md): Open or reply to a dispute. Escrow must be `OPENED`. **Only the buyer can open a dispute**; the seller can only respond once the buyer has raised one, after which the merchant resolves it. **Milestone escrows cannot be disputed** — only standard escrows are eligible. Requires the `customer-id` heade…
- [Claim funds](https://docs.payluk.ng/api-reference/escrow/claim-funds.md): Seller requests release of funds. Allowed only when the escrow is `OPENED` and the delivery window has elapsed.
- [Create escrow](https://docs.payluk.ng/api-reference/escrow/create-escrow.md): Generates a standard escrow payment link. Sent as `multipart/form-data` so up to 5 images can be attached under `imageUrl`. The seller is the authenticated key owner. Merchants cannot create an escrow for themselves via the API. Requires the `customer-id` header.
- [Delete escrow](https://docs.payluk.ng/api-reference/escrow/delete-escrow.md): Deletes an escrow. Allowed only while `AWAITING_PAYMENT` and only by the seller.
- [Edit escrow](https://docs.payluk.ng/api-reference/escrow/edit-escrow.md): Editable only while the escrow is `AWAITING_PAYMENT`, and only by the seller. New images are appended to the existing ones.
- [List escrow transactions](https://docs.payluk.ng/api-reference/escrow/list-escrow-transactions.md): Paginated list of the authenticated user's escrows, filtered by `type` (sales or buy).
- [Escrow — overview](https://docs.payluk.ng/api-reference/escrow/overview.md): Create and manage standard (single-payment) escrow links, and how the seller gets paid.
- [Verify payment token](https://docs.payluk.ng/api-reference/escrow/verify-payment-token.md): Resolves an escrow by its payment token. Used by a buyer to inspect a payment link before paying.
- [Block customer](https://docs.payluk.ng/api-reference/merchant-customers/block-customer.md)
- [Create merchant customer](https://docs.payluk.ng/api-reference/merchant-customers/create-merchant-customer.md): Creates a customer (buyer/seller) under your merchant account. Requires the API key to belong to a merchant super-admin account.
- [Get customer wallet](https://docs.payluk.ng/api-reference/merchant-customers/get-customer-wallet.md): Returns the wallet balances for a specific merchant customer. Requires the `customer-id` header.
- [Get merchant customer](https://docs.payluk.ng/api-reference/merchant-customers/get-merchant-customer.md)
- [List merchant customers](https://docs.payluk.ng/api-reference/merchant-customers/list-merchant-customers.md)
- [Onboard customers — overview](https://docs.payluk.ng/api-reference/merchant-customers/overview.md): Create and manage the buyers and sellers that transact under your merchant account.
- [Unblock customer](https://docs.payluk.ng/api-reference/merchant-customers/unblock-customer.md)
- [Update customer permissions](https://docs.payluk.ng/api-reference/merchant-customers/update-customer-permissions.md)
- [Confirm milestone](https://docs.payluk.ng/api-reference/milestone-escrow/confirm-milestone.md): Buyer approves one milestone; its full amount is released to the seller's main balance. If the milestone was created with a `customerId`, the funds are released to that customer's main balance instead. Requires the escrow to be funded (`OPENED`) and the caller to be the buyer. The escrow completes a…
- [Create milestone escrow](https://docs.payluk.ng/api-reference/milestone-escrow/create-milestone-escrow.md): Creates a milestone escrow (JSON body, no file upload). Rules: at least 2 milestones, every milestone amount is a positive integer, and the **sum of milestone amounts must equal `amount`**. Requires the `customer-id` header.
- [Get milestones](https://docs.payluk.ng/api-reference/milestone-escrow/get-milestones.md): Returns the milestone list for an escrow, by payment token. Returns an empty array for standard (non-milestone) escrows.
- [Milestone escrow — overview](https://docs.payluk.ng/api-reference/milestone-escrow/overview.md): Fund a project in full upfront and release it in stages as each milestone is confirmed.
- [Get countries](https://docs.payluk.ng/api-reference/misc/get-countries.md)
- [Misc — overview](https://docs.payluk.ng/api-reference/misc/overview.md): Reference lookups used across the rest of the API.
- [Create payment intent](https://docs.payluk.ng/api-reference/payments/create-payment-intent.md): Creates a payment intent to fund a customer's wallet. Requires the `customer-id` header.
- [Generate virtual account](https://docs.payluk.ng/api-reference/payments/generate-virtual-account.md): Generates a temporary virtual account for a merchant customer (`merchant_user` role only). Requires the `customer-id` header.
- [Get bank list](https://docs.payluk.ng/api-reference/payments/get-bank-list.md)
- [Get master wallet address](https://docs.payluk.ng/api-reference/payments/get-master-wallet-address.md)
- [Get payment history](https://docs.payluk.ng/api-reference/payments/get-payment-history.md)
- [Payments — overview](https://docs.payluk.ng/api-reference/payments/overview.md): Fund escrows and wallets, generate virtual accounts, and verify references and bank details.
- [Pay escrow (buy)](https://docs.payluk.ng/api-reference/payments/pay-escrow-buy.md): Fund an escrow (works for standard and milestone escrows — a milestone escrow is funded in full here). The amount charged is the escrow amount plus the buyer's fee share. `escrowDetails.escrowId` may be an array to fund multiple escrows. Requires the `customer-id` header (the buyer).
- [Top up virtual account (staging only)](https://docs.payluk.ng/api-reference/payments/top-up-virtual-account-staging-only.md): Test helper available only on the staging environment. Tops up a customer's wallet once per day. Requires the `customer-id` header.
- [Verify account number](https://docs.payluk.ng/api-reference/payments/verify-account-number.md)
- [Verify payment](https://docs.payluk.ng/api-reference/payments/verify-payment.md): Verify a single reference, or pass `references: [...]` to verify a batch. Requires the `customer-id` header.
- [Verify phone number](https://docs.payluk.ng/api-reference/payments/verify-phone-number.md): Verify a phone number belongs to one of your merchant customers.
- [Authentication](https://docs.payluk.ng/authentication.md): Secret keys, environments, and the customer-id header.
- [Dispute resolution](https://docs.payluk.ng/concepts/dispute-resolution.md): How disputes are raised between your customers and how you, the merchant, resolve them and disburse the held funds.
- [Escrow lifecycle](https://docs.payluk.ng/concepts/escrow-lifecycle.md): How an escrow moves from creation to settlement, and what state and status mean.
- [Fees & settlement](https://docs.payluk.ng/concepts/fees-and-settlement.md): How fees are split, when they're charged, and how funds settle.
- [How it works (end-to-end)](https://docs.payluk.ng/concepts/how-it-works.md): Every endpoint a merchant calls, in order, to take a standard or milestone payment from creation to settlement.
- [Merchant customers](https://docs.payluk.ng/concepts/merchant-customers.md): Onboard the buyers and sellers that transact under your merchant account.
- [Milestone escrows](https://docs.payluk.ng/concepts/milestone-escrows.md): Fund a project upfront and release it in stages as each milestone is confirmed.
- [Multi-quantity escrows (totalQuantity)](https://docs.payluk.ng/concepts/multi-quantity-escrows.md): How one escrow link with totalQuantity > 1 mints a separate escrow per buyer, so the same link can be sold many times.
- [Escrow webhooks](https://docs.payluk.ng/concepts/webhooks.md): Get notified at your callback URL every time an escrow changes state, so you never have to poll.
- [Errors](https://docs.payluk.ng/essentials/errors.md): How Payluk reports errors and what each status code means.
- [Pagination](https://docs.payluk.ng/essentials/pagination.md): How list endpoints paginate results.
- [Status reference](https://docs.payluk.ng/essentials/status-reference.md): Every enumerated value used across escrows, milestones and payments.
- [Introduction](https://docs.payluk.ng/introduction.md): Accept escrow-protected payments with a single API call.
- [Quickstart](https://docs.payluk.ng/quickstart.md): Create your first escrow payment link and walk it through to settlement.
- [Error handling](https://docs.payluk.ng/sdk/errors.md): Catch EscrowCheckoutError and branch on its code.
- [Inline Checkout SDK](https://docs.payluk.ng/sdk/introduction.md): Launch an escrow checkout widget from your web app with a publishable key.
- [JavaScript / TypeScript](https://docs.payluk.ng/sdk/javascript.md): Initialize the SDK once, then call pay() to open the checkout widget.
- [React](https://docs.payluk.ng/sdk/react.md): Use the useEscrowCheckout hook or the drop-in EscrowCheckoutButton.
- [SDK reference](https://docs.payluk.ng/sdk/reference.md): Every export, type and default in payluk-escrow-inline-checkout.

## OpenAPI Specs

- [openapi](https://docs.payluk.ng/openapi.json)