Docs / API reference

Statements and fees

Every settled movement of money as lines, and the fees we charged.

The Statement line object

One line per movement. A collection with a fee produces two lines that share a reference: the money in and the fee out. Amounts are signed: money in is positive, money out is negative.

Attributes

idstring
Unique identifier, starting ln_.
kindstring
What the line is.
One of collection, payout, settlement, fee, adjustment
amountinteger
Signed amount in the smallest unit.
wallet_idstring
The wallet affected.
referencestring
Shared by every line from the same transaction.
descriptionstring
Plain-language description.
created_atstring
ISO 8601 timestamp.

Example object

{
  "id": "ln_7b2k9x",
  "object": "statement_line",
  "kind": "fee",
  "amount": -250,
  "wallet_id": "wal_main",
  "reference": "PTS-8F3K2Q",
  "description": "Collection fee",
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}

GET/v1/statement

List statement lines

Newest first, filtered on the server.

Query parameters

wallet_idstring
Only this wallet.
kindstring
Only this kind of line.
One of collection, payout, settlement, fee, adjustment
fromstring
Start date, YYYY-MM-DD.
tostring
End date, YYYY-MM-DD.
limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed
400 invalid_request

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/statement" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ln_7b2k9x",
      "object": "statement_line",
      "kind": "fee",
      "amount": -250,
      "wallet_id": "wal_main",
      "reference": "PTS-8F3K2Q",
      "description": "Collection fee",
      "livemode": false,
      "created_at": "2026-10-28T11:20:04+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

GET/v1/fees

List fees

Only the fee lines.

The same as the statement filtered to kind=fee, so you can reconcile what you were charged against your own records.

Query parameters

wallet_idstring
Only this wallet.
fromstring
Start date, YYYY-MM-DD.
tostring
End date, YYYY-MM-DD.
limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/fees" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "ln_7b2k9x",
      "object": "statement_line",
      "kind": "fee",
      "amount": -250,
      "wallet_id": "wal_main",
      "reference": "PTS-8F3K2Q",
      "description": "Collection fee",
      "livemode": false,
      "created_at": "2026-10-28T11:20:04+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

POST/v1/collections/{id}/query

Check a pending collection

Ask the network what happened.

Use it on a collection that has been pending longer than expected. We ask the provider and update the collection. Never create a second collection to retry.

Path parameters

idstringrequired
The collection id.

Errors

404 not_found

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/collections/ID_FROM_RESPONSE/query" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "id": "col_8f3k2q",
  "object": "collection",
  "status": "succeeded",
  "amount": 250000,
  "currency": "KES",
  "source": "paybill",
  "reference": "INV-204117",
  "description": "Order 1042",
  "customer": {
    "phone": "+254712000000"
  },
  "wallet_id": "wal_main",
  "shortcode_id": "sc_4012345",
  "match": {
    "state": "matched",
    "sale_id": "sale_1042"
  },
  "routing": {
    "gateway": "daraja",
    "attempts": 2,
    "failed_over": true
  },
  "failure": null,
  "metadata": {
    "order_id": "1042"
  },
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}