curl --request POST \
  --url https://api.ketapay.com/v1/checkout_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 150000000,
  "category": "services",
  "title": "Company website",
  "description": "Five-page marketing site with blog, built on Next.js. Brief attached.",
  "attachments": [
    {
      "name": "Project brief.pdf",
      "url": "https://files.example.com/briefs/4471.pdf"
    }
  ],
  "milestones": [
    {
      "title": "Design",
      "description": "Homepage and inner page designs, two revision rounds",
      "amount": 40000000,
      "due_date": "2026-10-24"
    },
    {
      "title": "Build",
      "amount": 80000000,
      "due_date": "2026-11-14"
    },
    {
      "title": "Launch",
      "amount": 30000000,
      "due_date": "2026-11-21"
    }
  ],
  "buyer": {
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "email": "ada@example.com"
  },
  "seller": {
    "email": "tunde.bello@example.com",
    "phone": "+2348098765432",
    "name": "Tunde Bello"
  },
  "release": {
    "method": "buyer_confirms",
    "auto_release_hours": 168
  },
  "commission": {
    "rate_bps": 1000
  },
  "return_url": "https://example.com/projects/4471",
  "external_reference": "proj_4471"
}
'

{
  "id": "2c9a7f4e-1b3d-4e6a-8f2c-5d7b9e1a3c60",
  "object": "checkout_session",
  "livemode": false,
  "status": "open",
  "url": "https://app.ketapay.com/checkout/2c9a7f4e-1b3d-4e6a-8f2c-5d7b9e1a3c60",
  "amount": 150000000,
  "currency": "NGN",
  "fees": {
    "amount": 150000000,
    "buyer_fee": 2250000,
    "buyer_vat": 168750,
    "buyer_total": 152418750,
    "seller_fee": 2250000,
    "commission": 15000000,
    "seller_payout": 132750000
  },
  "category": "services",
  "title": "Company website",
  "description": "Five-page marketing site with blog, built on Next.js. Brief attached.",
  "images": [],
  "attachments": [
    {
      "name": "Project brief.pdf",
      "url": "https://files.ketapay.com/attachments/2c9a7f4e/brief.pdf"
    }
  ],
  "url_on_platform": null,
  "milestones": [
    {
      "title": "Design",
      "description": "Homepage and inner page designs, two revision rounds",
      "amount": 40000000,
      "due_date": "2026-10-24"
    },
    {
      "title": "Build",
      "description": null,
      "amount": 80000000,
      "due_date": "2026-11-14"
    },
    {
      "title": "Launch",
      "description": null,
      "amount": 30000000,
      "due_date": "2026-11-21"
    }
  ],
  "buyer": {
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "email": "ada@example.com"
  },
  "seller": {
    "email": "tunde.bello@example.com",
    "phone": "+2348098765432",
    "name": "Tunde Bello"
  },
  "release": {
    "method": "buyer_confirms",
    "auto_release_hours": 168
  },
  "commission": {
    "rate_bps": 1000,
    "min_amount": 0,
    "max_amount": null
  },
  "escrow_id": null,
  "return_url": "https://example.com/projects/4471",
  "cancel_url": null,
  "external_reference": "proj_4471",
  "metadata": {},
  "expires_at": "2026-10-11T09:30:00Z",
  "completed_at": null,
  "cancelled_at": null,
  "created_at": "2026-10-10T09:30:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "buyer.phone must be a Nigerian mobile number in E.164 format, like +2348012345678.",
    "param": "buyer.phone",
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "This API key is invalid or has been revoked.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "This key does not have the checkout_sessions:write scope.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the time in X-RateLimit-Reset.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

Checkout sessions

Create a checkout session

Starts checkout for one agreement. Call this from your server with your secret key.

What is agreed. title and description (both required) say what is being bought; images show it (the first is the cover on checkout, in messages and on the escrow); attachments hold documents such as a brief, a contract or title papers. KetaPay copies all of it when the session is created and keeps that copy with the escrow as evidence for any dispute, so later changes to your listing or record don’t change what was agreed.

Milestones. Pass milestones to split the payment into stages released one at a time, in order. Leave it out for a single payment: KetaPay creates one milestone for the whole amount. When you pass milestones, their amounts must add up to amount.

Release. release.method is buyer_confirms (the buyer releases each delivered milestone) or release_code (in person: the seller enters the buyer’s code). release.auto_release_hours releases a delivered milestone when the buyer neither releases nor reports a problem in that time; leave it null where silence should never pay the seller, such as legal or property work.

Parties. The buyer and the seller are people, each identified by an email address, a Nigerian phone number, or both. At least one is required; send both when you have them, because KetaPay messages people on every channel it knows (release codes and dispute deadlines are easy to miss in one inbox).

KetaPay matches each party to a KetaPay account by email first, then phone. Someone without an account gets one from what you send and claims it with a one-time code to that email or phone, so neither side has to install KetaPay. If the email and phone belong to two different KetaPay accounts, the request fails with party_identity_conflict; send just one. The buyer and seller must be different people (parties_must_differ). You never send the seller’s bank details: the seller adds them, with their own one-time code, on KetaPay’s pages or through POST /payout_accounts.

Fees. The buyer pays the amount plus KetaPay’s fee and VAT on that fee. The seller’s fee and your commission come out of each release. Nothing is charged to the seller or earned by you on money refunded to the buyer. The response shows every figure in fees.

Limits. Amounts above the buyer’s verification level are allowed here; the buyer is asked to verify their identity before paying (the hosted checkout does this for you).

POST

checkout_sessions

curl --request POST \
  --url https://api.ketapay.com/v1/checkout_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 150000000,
  "category": "services",
  "title": "Company website",
  "description": "Five-page marketing site with blog, built on Next.js. Brief attached.",
  "attachments": [
    {
      "name": "Project brief.pdf",
      "url": "https://files.example.com/briefs/4471.pdf"
    }
  ],
  "milestones": [
    {
      "title": "Design",
      "description": "Homepage and inner page designs, two revision rounds",
      "amount": 40000000,
      "due_date": "2026-10-24"
    },
    {
      "title": "Build",
      "amount": 80000000,
      "due_date": "2026-11-14"
    },
    {
      "title": "Launch",
      "amount": 30000000,
      "due_date": "2026-11-21"
    }
  ],
  "buyer": {
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "email": "ada@example.com"
  },
  "seller": {
    "email": "tunde.bello@example.com",
    "phone": "+2348098765432",
    "name": "Tunde Bello"
  },
  "release": {
    "method": "buyer_confirms",
    "auto_release_hours": 168
  },
  "commission": {
    "rate_bps": 1000
  },
  "return_url": "https://example.com/projects/4471",
  "external_reference": "proj_4471"
}
'

{
  "id": "2c9a7f4e-1b3d-4e6a-8f2c-5d7b9e1a3c60",
  "object": "checkout_session",
  "livemode": false,
  "status": "open",
  "url": "https://app.ketapay.com/checkout/2c9a7f4e-1b3d-4e6a-8f2c-5d7b9e1a3c60",
  "amount": 150000000,
  "currency": "NGN",
  "fees": {
    "amount": 150000000,
    "buyer_fee": 2250000,
    "buyer_vat": 168750,
    "buyer_total": 152418750,
    "seller_fee": 2250000,
    "commission": 15000000,
    "seller_payout": 132750000
  },
  "category": "services",
  "title": "Company website",
  "description": "Five-page marketing site with blog, built on Next.js. Brief attached.",
  "images": [],
  "attachments": [
    {
      "name": "Project brief.pdf",
      "url": "https://files.ketapay.com/attachments/2c9a7f4e/brief.pdf"
    }
  ],
  "url_on_platform": null,
  "milestones": [
    {
      "title": "Design",
      "description": "Homepage and inner page designs, two revision rounds",
      "amount": 40000000,
      "due_date": "2026-10-24"
    },
    {
      "title": "Build",
      "description": null,
      "amount": 80000000,
      "due_date": "2026-11-14"
    },
    {
      "title": "Launch",
      "description": null,
      "amount": 30000000,
      "due_date": "2026-11-21"
    }
  ],
  "buyer": {
    "phone": "+2348012345678",
    "name": "Ada Obi",
    "email": "ada@example.com"
  },
  "seller": {
    "email": "tunde.bello@example.com",
    "phone": "+2348098765432",
    "name": "Tunde Bello"
  },
  "release": {
    "method": "buyer_confirms",
    "auto_release_hours": 168
  },
  "commission": {
    "rate_bps": 1000,
    "min_amount": 0,
    "max_amount": null
  },
  "escrow_id": null,
  "return_url": "https://example.com/projects/4471",
  "cancel_url": null,
  "external_reference": "proj_4471",
  "metadata": {},
  "expires_at": "2026-10-11T09:30:00Z",
  "completed_at": null,
  "cancelled_at": null,
  "created_at": "2026-10-10T09:30:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "buyer.phone must be a Nigerian mobile number in E.164 format, like +2348012345678.",
    "param": "buyer.phone",
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "This API key is invalid or has been revoked.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "missing_scope",
    "message": "This key does not have the checkout_sessions:write scope.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the time in X-RateLimit-Reset.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

Authorizations

Authorization

string

header

default:sk_test_docs_246e232c64ccc7a001bf61ec0f2e6ab0

required

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

Idempotency-Key

string

required

Unique key for this operation. Retries with the same key return the first result.

Maximum string length: 255

Example:

"7f3e2a10-6c4d-4b8e-9a1f-2d5c8e7b6a40"

Body

application/json

amount

integer

required

The full agreed price in kobo, before KetaPay's fee. Must equal the sum of milestones when given.

Required range: x >= 1

Example:

45000000

title

string

required

What is being bought, in a few words

Required string length: 1 - 120

Example:

"Company website"

description

string

required

What was agreed, in enough detail for someone else to judge a dispute: condition, specification, scope of work, what is included. Shown to both sides.

Required string length: 20 - 2000

buyer

object

required

At least one of email and phone. Both is better.

Option 1
Option 2

Show child attributes

currency

enum<string>

default:NGN

Available options:

NGN

Response

Checkout session created

string<uuid>

required

object

string

required

Allowed value: "checkout_session"

livemode

boolean

required

status

enum<string>

required

open: waiting for payment. complete: paid, escrow_id is set. expired: not paid by expires_at. cancelled: you cancelled it.

Available options:

open,

complete,

expired,

cancelled

url

string<uri>

required

The hosted checkout. Open it with @ketapay/checkout or redirect the buyer to it.

Example:

"https://app.ketapay.com/checkout/2c9a7f4e-1b3d-4e6a-8f2c-5d7b9e1a3c60"

amount

integer

required

Amount in kobo

Required range: x >= 0

Example:

45000000

currency

string

required

Allowed value: "NGN"

fees

object

required

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.

Show child attributes

Basics

Endpoints

Create a checkout session

Authorizations

Headers

Body

Response