Payments overview - Payluk API

This group moves money: it funds escrows, tops up customer wallets, and provides the verification helpers around payments. Most routes act on behalf of a buyer, so they need the customer-id header. See fees & settlement for what the buyer is charged.

Funding an escrow is the headline call: Pay escrow. The deposit/verify pair (Create payment intent → Verify payment) is for topping up a wallet before paying with the WALLET gateway, or for completing card/bank gateways.

Core money movement

Route	Method & path	What it does
Pay escrow (buy)	`POST /v1/payment/escrow`	Funds an escrow (standard or milestone, funded in full). Charges the escrow amount + the buyer’s fee share; escrow → `OPENED`. `escrowDetails.escrowId` may be an array to fund several at once. `customer-id` = buyer.
Create payment intent	`POST /v1/payment/create-intent`	A merchant customer’s payout or top-up: fiat bank withdrawal (`withdrawal` + `withdrawalDetails`), crypto transfer (`withdrawal` + `blockchainDetails`), card deposit (`deposit` + `depositDetails.cardId`, a saved/tokenized card), or wallet transfer (`wallet_transfer` + `walletDetails`). `customer-id` required.
Verify payment	`POST /v1/payment/verify`	Submits a created intent for processing (step 2 of the two-step flow); this is what actually moves the money. Takes a single `reference` (+ `otp` when required). `customer-id` required.

Funding accounts

Route	Method & path	What it does
Generate virtual account	`POST /v1/payment/virtual-account`	Issues a temporary virtual account for a merchant customer to receive a bank transfer. `customer-id` required.
Top up virtual account	`POST /v1/payment/topup`	Staging-only test helper: credits a customer’s wallet once per day. `customer-id` required.
Get payment history	`GET /v1/payment/history`	Paginated money in/out for a customer. `customer-id` required.

Verification helpers

Route	Method & path	What it does
Get bank list	`GET /v1/payment/bank-list`	Banks with their codes, for use in `verify-account`.
Verify account number	`POST /v1/payment/verify-account`	Resolves an `accountNumber` + `bankCode` to an account name.
Verify phone number	`GET /v1/payment/verify-phone/{phone}`	Checks a phone belongs to one of your merchant customers.
Get master wallet address	`GET /v1/payment/deposit/wallet`	Returns the crypto master-wallet deposit address and network.

Wallet flow: Create payment intent → buyer pays the authorizationUrl → Verify payment → balance available → Pay escrow with gateway: WALLET. On staging, replace the first three steps with Top up.