Skip to main content

​
Who pays the fee

Every escrow carries a whoPays field that determines how the Payluk fee is split: The computed fee is returned as fee on the escrow when you create or edit it.

​
What the buyer is charged

When funding via Pay escrow, the buyer is charged the escrow amount, plus their share of the fee, plus the escrow’s additionalFee. For example, an escrow of 1,000,000 with a 25,000 fee split may charge the buyer 1,012,500, or 1,015,000 if you have added a 2,500 delivery fee.
Send that full total as amount. Anything else is rejected with Amount mismatch, so read the escrow (amount, fee, whoPays, additionalFee) rather than caching a price you quoted earlier.

​
Additional (delivery) fee

Your own charge on top of an escrow: delivery, handling, anything the escrow amount itself shouldn’t include. Every escrow starts at additionalFee: 0; you set it with Update additional fee.
The delivery transaction type exists so this income stays separate from your commission. Both settle in the same step; only the delivery fee is the amount you set.

​
If the order is refunded

additionalFeeRefundable decides who carries the cost when a dispute is resolved in the buyer’s favour:
  • true (the default): the charge goes back to the buyer along with the refunded principal. Nothing shipped.
  • false: you are credited the charge anyway, as if the escrow had completed. The delivery cost was already incurred.
You normally set this when you resolve the dispute, not when you set the fee: POST /v1/escrow/dispute/resolve/{escrowId} takes additionalFeeRefundable alongside your ruling, because only then do you know whether the delivery happened. See Deciding who keeps the delivery fee. Setting it up front on Update additional fee is optional and only establishes the default: it is what applies if a dispute is resolved without an explicit choice. A choice sent at resolution overrides and replaces it. Either way the money is settled to one party; it is never left with the platform.

​
When settlement happens

Standard escrow

The full amount (net of the seller’s fee share) is released to the seller when the buyer confirms delivery, or when the seller successfully claims funds after the delivery window.

Milestone escrow

Each confirmed milestone releases its net share: the milestone amount minus its pro-rata portion of the seller fee. Commission is finalised when the last milestone releases.

​
Refunds and splits

When a dispute is resolved in the buyer’s favour (status: REFUNDED), funds are returned to the buyer’s wallet and the escrow closes. Any additionalFee is settled in the same pass, to whichever party additionalFeeRefundable names (see above). A split resolution (status: SPLIT) works the same way, except the held funds are divided: part is released to the seller and the rest returned to the buyer, in the amounts the merchant names. The escrow fee is retained in full, as on a refund, so the two amounts must add up to what the escrow actually holds rather than to its amount. Commission is charged once, as on a completion.
All amounts in the API are in the major currency unit (NGN), never kobo: send 150000 for ₦150,000, not 15000000. Kobo are expressed as decimals (₦100.20 is 100.2) and are rounded to two places, so a percentage fee on a decimal amount stays payable. Conversion to minor units happens inside Payluk at the gateway boundary; you never send or receive kobo.