Core concepts

The objects

Object	What it is	Created by
Checkout session	One agreement waiting to be paid: price, plan, buyer and seller	Your server
Escrow	The paid agreement. KetaPay holds the money until it is released or refunded	KetaPay, when the buyer pays
Milestone	A part of the escrow with its own amount, delivered and released on its own	You, on the session
Party	The buyer or the seller, known by email or phone	You, on the session
Customer session	A one-time code sent to a buyer or seller, exchanged for a customer token	Your server
Dispute	A problem reported on a milestone; freezes it until settled	The buyer or seller
Payout account	Where a seller’s money goes; only the seller can add one	The seller
Event	A record of something that changed, sent to your webhook endpoints	KetaPay

How money moves

Checkout session: open

Your server creates a session with the amount, milestones, buyer and seller. Nothing is charged yet.

Escrow: funded

The buyer pays buyer_total (the amount plus KetaPay’s buyer fee and VAT). KetaPay holds the amount and sends escrow.funded.

Milestones: delivered, then released

The seller marks each milestone delivered; the buyer releases it. Each release pays the seller that milestone’s amount, less KetaPay’s seller fee and your commission.

Escrow: completed or refunded

When every milestone is settled the escrow ends completed. Money returned to the buyer goes back the way it came.

Who can do what

Your secret key acts for your platform. Your customers’ decisions need their own proof.

Action	Your key alone	Needs the customer
Create and read checkout sessions	Yes
Read escrows, disputes, events	Yes
Flag an escrow for review	Yes
Deliver a milestone		Seller’s token
Release a milestone		Buyer’s token, or the buyer’s release code
Cancel an escrow		Seller’s token, or buyer’s before delivery
Open, concede or withdraw a dispute		That party’s token
Add a payout account		Seller’s token and their code

Your platform is never a party to an escrow, so a leaked secret key can’t pay one out.

Sandbox and live

There is one API. sk_test_ keys work on test money (the sandbox), sk_live_ keys on real money. Every object carries livemode, and objects from one never show up in the other. See Testing.

Amounts

Every amount is an integer in kobo: 250000 is ₦2,500.00. Currency is always NGN.

Get started

Accept payments

Escrow

Customers

After payment

Integrate

The objects

How money moves

Who can do what

Sandbox and live

Amounts

​The objects

​How money moves

​Who can do what

​Sandbox and live

​Amounts

The objects

How money moves

Who can do what

Sandbox and live

Amounts