Escrow lifecycle

An escrow holds the buyer’s money until its milestones are released. Your key alone can read escrows and flag one for review. Delivering, releasing and cancelling also need the right customer’s proof.

Lifecycle

Funded

The buyer paid. The plan is now fixed: amounts and milestones can’t change. You get escrow.funded.

Delivered

The seller marks the current milestone delivered, with an optional note and files (a tracking number, a link to the work, a signed document). You get milestone.delivered.

Released

The buyer releases it and the seller is paid for that milestone. You get milestone.released, then payout.sent when the money lands.

Completed

When every milestone is settled, the escrow is completed and you get escrow.completed.

Release methods

Set on the checkout session with release.method: buyer_confirms (the buyer releases after delivery) or release_code for in-person deals. See Release codes and Milestones.

Acting for a customer

// The seller marks the milestone delivered
await ketapay.escrows.milestones.deliver(
  escrowId,
  milestoneId,
  { note: 'Shipped, GIG tracking 88123' },
  { customerToken: sellerToken },
)

// The buyer releases it
await ketapay.escrows.milestones.release(
  escrowId,
  milestoneId,
  {},
  { customerToken: buyerToken },
)

Customer tokens are covered in Customer tokens.

Cancel and refund

POST /escrows/{id}/cancel refunds the buyer every milestone not yet released; released milestones stay paid. It needs a customer token:

Seller’s token: any time (the seller gives up the rest of the deal).
Buyer’s token: only before any milestone is delivered or released. After that the buyer reports a problem instead.

You get escrow.refunded. Money only ever goes back to the account that paid. KetaPay’s buyer fee and VAT are not refunded once the escrow is funded.

Flag for review

If you remove a listing as fraudulent or ban a user, POST /escrows/{id}/flag asks KetaPay to review the escrow. KetaPay decides what happens, which can include holding releases while it looks into it. The buyer and seller are not told who flagged it.

Statuses

Escrow	Meaning
`active`	Money held, milestones in progress
`disputed`	A problem was reported; KetaPay is handling it
`completed`	Ended with at least one milestone paid to the seller
`refunded`	Ended with everything returned to the buyer

Milestones move through funded, delivered, released, and can end refunded, or sit disputed until a dispute closes.

Find an escrow

Every escrow keeps your external_reference and metadata from the session. List with GET /escrows?external_reference=order_7781, or fetch by id.

Get started

Accept payments

Escrow

Customers

After payment

Integrate

Lifecycle

Release methods

Acting for a customer

Cancel and refund

Flag for review

Statuses

Find an escrow

​Lifecycle

​Release methods

​Acting for a customer

​Cancel and refund

​Flag for review

​Statuses

​Find an escrow

Lifecycle

Release methods

Acting for a customer

Cancel and refund

Flag for review

Statuses

Find an escrow