Mark a milestone delivered

curl --request POST \
  --url https://api.ketapay.com/v1/escrows/{id}/milestones/{milestone_id}/deliver \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'KetaPay-Customer-Token: <api-key>' \
  --data '
{
  "note": "Designs ready for review. Figma link and exports attached.",
  "attachments": [
    {
      "name": "Homepage.png",
      "url": "https://files.example.com/proj_4471/homepage.png"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'KetaPay-Customer-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    note: 'Designs ready for review. Figma link and exports attached.',
    attachments: [
      {name: 'Homepage.png', url: 'https://files.example.com/proj_4471/homepage.png'}
    ]
  })
};

fetch('https://api.ketapay.com/v1/escrows/{id}/milestones/{milestone_id}/deliver', 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}/milestones/{milestone_id}/deliver",
  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([
    'note' => 'Designs ready for review. Figma link and exports attached.',
    'attachments' => [
        [
                'name' => 'Homepage.png',
                'url' => 'https://files.example.com/proj_4471/homepage.png'
        ]
    ]
  ]),
  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

Mark a milestone delivered

The seller says their part of this milestone is done, with the seller’s customer token. When you sell your own goods (the escrow’s seller is your business), your key alone delivers it; without a token on anyone else’s escrow it is customer_token_required. Only the current milestone (the first one not yet released) can be delivered. Moves no money: the buyer then releases it, reports a problem, or (with auto_release_hours) lets the time run out. Sends milestone.delivered.

POST

escrows

{id}

milestones

{milestone_id}

deliver

Mark a milestone delivered

curl --request POST \
  --url https://api.ketapay.com/v1/escrows/{id}/milestones/{milestone_id}/deliver \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'KetaPay-Customer-Token: <api-key>' \
  --data '
{
  "note": "Designs ready for review. Figma link and exports attached.",
  "attachments": [
    {
      "name": "Homepage.png",
      "url": "https://files.example.com/proj_4471/homepage.png"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'KetaPay-Customer-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    note: 'Designs ready for review. Figma link and exports attached.',
    attachments: [
      {name: 'Homepage.png', url: 'https://files.example.com/proj_4471/homepage.png'}
    ]
  })
};

fetch('https://api.ketapay.com/v1/escrows/{id}/milestones/{milestone_id}/deliver', 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}/milestones/{milestone_id}/deliver",
  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([
    'note' => 'Designs ready for review. Figma link and exports attached.',
    'attachments' => [
        [
                'name' => 'Homepage.png',
                'url' => 'https://files.example.com/proj_4471/homepage.png'
        ]
    ]
  ]),
  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

milestone_id

string<uuid>

required

Body

application/json

note

string | null

What was delivered, for the buyer

Maximum string length: 160

attachments

object[]

Maximum array length: 10

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

Show child attributes

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

Mark a milestone delivered

Authorizations

Headers

Path Parameters

Body

Response