curl --request GET \
--url https://api.ketapay.com/v1/escrows \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.ketapay.com/v1/escrows', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ketapay.com/v1/escrows",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"object": "list",
"has_more": true,
"next_cursor": "<string>",
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "escrow",
"livemode": true,
"status": "active",
"amount": 45000000,
"currency": "NGN",
"fees": {
"amount": 45000000,
"buyer_fee": 2250000,
"buyer_vat": 168750,
"buyer_total": 152418750,
"seller_fee": 2250000,
"commission": 15000000,
"seller_payout": 132750000
},
"category": "other",
"title": "<string>",
"description": "<string>",
"images": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"thumbnail_url": "<string>",
"alt": "<string>"
}
],
"attachments": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Project brief.pdf",
"url": "<string>"
}
],
"milestones": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "milestone",
"position": 2,
"title": "<string>",
"description": "<string>",
"amount": 45000000,
"due_date": "2023-12-25",
"status": "funded",
"delivery": {
"note": "<string>",
"attachments": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Project brief.pdf",
"url": "<string>"
}
],
"delivered_at": "2023-11-07T05:31:56Z"
},
"auto_release_at": "2023-11-07T05:31:56Z",
"seller_fee": 45000000,
"commission": 45000000,
"seller_payout": 45000000,
"payout": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payout",
"livemode": true,
"escrow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 45000000,
"status": "awaiting_account",
"bank_name": "<string>",
"account_number_last4": "6789",
"sent_at": "2023-11-07T05:31:56Z",
"failure_reason": "Account closed"
},
"refund": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "refund",
"livemode": true,
"escrow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 45000000,
"destination": "card",
"status": "processing",
"last4": "4081",
"sent_at": "2023-11-07T05:31:56Z",
"failure_reason": "Card expired"
},
"released_at": "2023-11-07T05:31:56Z",
"refunded_at": "2023-11-07T05:31:56Z"
}
],
"buyer": {
"email": "ada@example.com",
"phone": "+2348012345678",
"name": "<string>",
"has_claimed_account": true
},
"seller": {
"email": "ada@example.com",
"phone": "+2348012345678",
"name": "<string>",
"has_claimed_account": true
},
"release": {
"method": "buyer_confirms",
"auto_release_hours": null
},
"checkout_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"open_dispute_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"open_chargeback_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"flagged": true,
"timeline": [
{
"type": "funded",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"occurred_at": "2023-11-07T05:31:56Z"
}
],
"external_reference": "proj_4471",
"metadata": {
"project_id": "4471"
},
"created_at": "2023-11-07T05:31:56Z",
"funded_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z"
}
]
}{
"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": "rate_limit_error",
"code": "rate_limited",
"message": "Too many requests. Retry after the time in X-RateLimit-Reset.",
"param": null,
"request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
}
}List escrows
Escrows started from your checkout sessions, newest first.
curl --request GET \
--url https://api.ketapay.com/v1/escrows \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.ketapay.com/v1/escrows', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ketapay.com/v1/escrows",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"object": "list",
"has_more": true,
"next_cursor": "<string>",
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "escrow",
"livemode": true,
"status": "active",
"amount": 45000000,
"currency": "NGN",
"fees": {
"amount": 45000000,
"buyer_fee": 2250000,
"buyer_vat": 168750,
"buyer_total": 152418750,
"seller_fee": 2250000,
"commission": 15000000,
"seller_payout": 132750000
},
"category": "other",
"title": "<string>",
"description": "<string>",
"images": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"thumbnail_url": "<string>",
"alt": "<string>"
}
],
"attachments": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Project brief.pdf",
"url": "<string>"
}
],
"milestones": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "milestone",
"position": 2,
"title": "<string>",
"description": "<string>",
"amount": 45000000,
"due_date": "2023-12-25",
"status": "funded",
"delivery": {
"note": "<string>",
"attachments": [
{
"file": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Project brief.pdf",
"url": "<string>"
}
],
"delivered_at": "2023-11-07T05:31:56Z"
},
"auto_release_at": "2023-11-07T05:31:56Z",
"seller_fee": 45000000,
"commission": 45000000,
"seller_payout": 45000000,
"payout": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "payout",
"livemode": true,
"escrow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 45000000,
"status": "awaiting_account",
"bank_name": "<string>",
"account_number_last4": "6789",
"sent_at": "2023-11-07T05:31:56Z",
"failure_reason": "Account closed"
},
"refund": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"object": "refund",
"livemode": true,
"escrow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount": 45000000,
"destination": "card",
"status": "processing",
"last4": "4081",
"sent_at": "2023-11-07T05:31:56Z",
"failure_reason": "Card expired"
},
"released_at": "2023-11-07T05:31:56Z",
"refunded_at": "2023-11-07T05:31:56Z"
}
],
"buyer": {
"email": "ada@example.com",
"phone": "+2348012345678",
"name": "<string>",
"has_claimed_account": true
},
"seller": {
"email": "ada@example.com",
"phone": "+2348012345678",
"name": "<string>",
"has_claimed_account": true
},
"release": {
"method": "buyer_confirms",
"auto_release_hours": null
},
"checkout_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"open_dispute_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"open_chargeback_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"flagged": true,
"timeline": [
{
"type": "funded",
"milestone_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"occurred_at": "2023-11-07T05:31:56Z"
}
],
"external_reference": "proj_4471",
"metadata": {
"project_id": "4471"
},
"created_at": "2023-11-07T05:31:56Z",
"funded_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z"
}
]
}{
"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": "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: 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.
Query Parameters
1 <= x <= 100The next_cursor from the previous page
Only items with this external_reference
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 Only escrows created at or after this time
Only escrows created before this time