Payments overview - Payluk API

This group covers paying escrows from wallet balances, payouts, and the verification helpers around payments. Most routes act on behalf of a customer, so they need the customer-id header. See fees & settlement for what the buyer is charged.

All money comes in as an escrow payment through the Checkout SDK. Checkout generates a temporary virtual account for the escrow and the buyer pays it by bank transfer. Payluk has no direct deposits, no card payments, and no wallet top-ups, and Generate virtual account returns 410.

Core money movement

Route	Method & path	What it does
Pay escrow (buy)	`POST /v1/payment/escrow`	Funds an escrow from the buyer’s existing wallet balance (standard or milestone, funded in full). Charges the escrow amount + the buyer’s fee share; escrow → `OPENED`. `escrowDetails.escrowId` may be an array. `customer-id` = buyer. To collect a new payment, use the Checkout SDK instead.
Create payment intent	`POST /v1/payment/create-intent`	A merchant customer’s payout: fiat bank withdrawal (`withdrawal` + `withdrawalDetails`), crypto transfer (`withdrawal` + `blockchainDetails`), 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.
Get payment history	`GET /v1/payment/history`	Paginated money in/out for a customer. Supports `page` and `limit` (1-100, default 10). `customer-id` required.
Generate virtual account	`POST /v1/payment/virtual-account`	Deprecated, returns `410`. Collect with the Checkout SDK instead.

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.

Payout flow: Create payment intent → Verify payment with the intent’s reference → the withdrawal or transfer is executed.