Simulate an escrow event (sandbox)
Does what a buyer, seller, bank or KetaPay mediator would do, with the same rules and the same webhooks as the real thing (an action that would be refused for real is refused here too, so you see the same errors).
action | Acts as | Needs |
|---|---|---|
deliver | Seller | milestone_id |
release | Buyer | milestone_id |
auto_release | The clock: skips to the end of the auto-release window | milestone_id |
cancel | actor (buyer or seller) | |
open_dispute | actor | milestone_id optional, reason |
request_evidence | KetaPay | from (buyer, seller or both) |
resolve_dispute | KetaPay | outcome, refunded_amount for a partial refund |
open_chargeback | The buyer’s card bank | amount optional |
close_chargeback | The card bank | chargeback_status (won or lost) |
fail_payout | The seller’s bank | milestone_id |
fail_refund | The buyer’s card bank | milestone_id |
Authorizations
Authorization: Bearer <secret key>. Secret keys belong to your organisation, are shown
once when created in the dashboard, and are scoped (see x-required-scope on each
operation). Keep them on your server. Live keys are issued after your business is
verified. Publishable keys (pk_) are only for @ketapay/checkout and don't work here.
Headers
Unique key for this operation. Retries with the same key return the first result.
255"7f3e2a10-6c4d-4b8e-9a1f-2d5c8e7b6a40"
Path Parameters
Body
deliver, release, auto_release, cancel, open_dispute, request_evidence, resolve_dispute, open_chargeback, close_chargeback, fail_payout, fail_refund buyer, seller Buyer reasons: not_received (goods or work never arrived), not_as_agreed (differs
from what was agreed), damaged, incomplete (only part was delivered). Seller reason:
buyer_unresponsive (delivered, but the buyer won't release or respond). Either side:
other.
not_received, not_as_agreed, damaged, incomplete, buyer_unresponsive, other buyer, seller, both released, refunded, partially_refunded Amount in kobo
x >= 045000000
Amount in kobo
x >= 045000000
won, lost Response
The updated escrow
"escrow"active: money held, milestones in progress. disputed: the buyer reported a problem;
KetaPay is handling it. completed: ended with at least one milestone paid to the
seller. refunded: ended with everything returned to the buyer. An escrow only exists
once the buyer has paid.
active, disputed, completed, refunded Amount in kobo
x >= 045000000
"NGN"Totals for the whole escrow, in kobo. buyer_total = amount + buyer_fee + buyer_vat and
seller_payout = amount - seller_fee - commission. Until everything is released these
are what will apply; each milestone shows its own share.
What kind of deal this is. KetaPay uses it for risk checks and dispute handling.
goods, services, property, vehicle, digital, other KetaPay's copies of the images sent at checkout; the first is the cover
Send either file (an id from POST /files with purpose agreement) or url (an HTTPS
link KetaPay copies). JPEG, PNG, HEIC or WebP. Responses carry KetaPay's own url plus a
small thumbnail_url.
- Option 1
- Option 2
KetaPay's copies of the documents sent at checkout
Send either file (an id from POST /files) or url (an HTTPS link KetaPay copies, so
it survives your copy being deleted). Responses always carry KetaPay's own url.
- Option 1
- Option 2
In order. One entry for a single payment.
The seller, or your business when you sell your own goods
- Option 1
- Option 2
The dispute currently open, if any. GET /escrows/{id}/disputes lists them all.
A card chargeback currently being contested, if any
Whether you have flagged this escrow
What happened, oldest first
Your own id for this object, for example your order or project id. Filterable.
255"proj_4471"
Your own key-value pairs. KetaPay stores them and never reads them.
When it became completed or refunded