Skip to main content
Every escrow tracks two related fields:
  • state: where the escrow is in its lifecycle: AWAITING_PAYMENT → OPENED → CLOSED.
  • status: the business outcome: PENDING, ONGOING, COMPLETED, REFUNDED, SPLIT, CLAIMED, DISPUTED, or INVESTIGATING.

​
The happy path

1

AWAITING_PAYMENT / PENDING

The escrow was created via Create escrow. It can still be edited or deleted by the seller while in this state, and as the merchant you can set or change its additional (delivery) fee. This is the only state in which that charge is mutable.
2

OPENED / ONGOING

The buyer funded the escrow via Pay escrow. Funds are held by Payluk. The delivery window (maxDelivery + deliveryTimeline) starts counting.
3

CLOSED / COMPLETED

The buyer confirms delivery, releasing funds to the seller. Commission is charged on completion, and any additional (delivery) fee is credited to the merchant wallet in the same step.

​
Alternate outcomes

If the delivery window elapses and the buyer hasn’t confirmed, the seller can call Claim funds. This is only allowed when the escrow is OPENED and the window has passed.
Only the buyer can open a dispute while the escrow is OPENED; the seller can only respond once one is raised. The merchant then resolves it. Vault escrows can’t be disputed; a milestone escrow can be, over the milestones the buyer never confirmed.
When a merchant resolves a dispute in the buyer’s favour, funds are returned to the buyer and the escrow closes as REFUNDED. Any additional (delivery) fee is settled in the same pass, to whichever party the resolving merchant names with additionalFeeRefundable.
When a merchant resolves a dispute partly for each side, the held funds are divided between the seller and the buyer in the amounts the merchant names, and the escrow closes as SPLIT with a split object recording the division. The delivery fee is settled as it would be on a refund.

​
State reference

See the full status reference for how status values combine with each state, and How it works (end-to-end) for the exact endpoints to call at each stage. If you sell more than one unit off a single link, read Multi-quantity escrows.