Cancel and refund the buyer

curl --request POST \
  --url https://api.ketapay.com/v1/escrows/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'KetaPay-Customer-Token: <api-key>' \
  --data '
{
  "reason": "Project cancelled by agreement"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'KetaPay-Customer-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: 'Project cancelled by agreement'})
};

fetch('https://api.ketapay.com/v1/escrows/{id}/cancel', 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/{id}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Project cancelled by agreement'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "KetaPay-Customer-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "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": "permission_error",
    "code": "customer_not_allowed",
    "message": "Only the buyer can release this milestone.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No escrow with id 3b1f6c2e-8d4a-4e7b-9c1d-2a5f8e6b7c90.",
    "param": "id",
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "dispute_open",
    "message": "This escrow has an open dispute. KetaPay will release or refund it when the dispute ends.",
    "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"
  }
}

Escrows

Cancel and refund the buyer

Refunds the buyer every milestone not yet released; released milestones stay paid. Money only ever goes back to the account that paid. KetaPay’s buyer fee and VAT are not refunded once the escrow is funded, the same rule as in the KetaPay app.

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.

Refused while a dispute is open (the seller can refund through POST /disputes/{id}/concede). Sends escrow.refunded, or escrow.completed if some milestones were already released.

POST

escrows

{id}

cancel

Cancel and refund the buyer

curl --request POST \
  --url https://api.ketapay.com/v1/escrows/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'KetaPay-Customer-Token: <api-key>' \
  --data '
{
  "reason": "Project cancelled by agreement"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'KetaPay-Customer-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: 'Project cancelled by agreement'})
};

fetch('https://api.ketapay.com/v1/escrows/{id}/cancel', 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/{id}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => 'Project cancelled by agreement'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "KetaPay-Customer-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "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": "permission_error",
    "code": "customer_not_allowed",
    "message": "Only the buyer can release this milestone.",
    "param": null,
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No escrow with id 3b1f6c2e-8d4a-4e7b-9c1d-2a5f8e6b7c90.",
    "param": "id",
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "dispute_open",
    "message": "This escrow has an open dispute. KetaPay will release or refund it when the dispute ends.",
    "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.

KetaPay-Customer-Token

string

header

required

Proof that your customer approved this call, from POST /customer_sessions/{id}/verify. Sent together with your secret key. Valid for 15 minutes, for that customer's escrows only.

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"

Path Parameters

string<uuid>

required

Body

application/json

reason

string | null

Maximum string length: 500

Response

The updated escrow

string<uuid>

required

object

string

required

Allowed value: "escrow"

livemode

boolean

required

status

enum<string>

required

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.

Available options:

active,

disputed,

completed,

refunded

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

Cancel and refund the buyer

Authorizations

Headers

Path Parameters

Body

Response