Docs / API reference

Collections

Take a payment from any source. The customer pays, Pitisha records it and matches it to the sale.

The Collection object

A payment from a customer into one of your wallets. It starts pending and settles to succeeded or failed. Money goes straight into your own till, so a collection is a record of that payment, not funds held by Pitisha.

Attributes

idstring
Unique identifier, starting col_.
statusstring
Where the payment is.
One of pending, succeeded, failed, reversed
amountinteger
Amount in the smallest unit. 250000 is KES 2,500.00.
currencystring
Always KES.
sourcestring
How the customer paid.
One of till, paybill, qr, bank, airtel
referencestring | null
Your reference, for example an invoice or account number.
customerobject
Who paid: a phone number for mobile money, or account details for bank transfers.
wallet_idstring
The wallet the payment landed in.
shortcode_idstring | null
The paybill or till it was paid to.
matchobject | null
How the payment matched your sales. match.state is matched, pile or no_match. See Matching.
routingobject
Which gateway took the payment, how many attempts it needed, and whether the smart switch failed over. See Gateways and failover.
failureobject | null
Present when status is failed: a code and a message.
metadataobject
Up to 20 key-value pairs of your own.
livemodeboolean
false in the sandbox.
created_atstring
ISO 8601 timestamp.

Example object

{
  "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"
}

POST/v1/collections

Create a collection

Ask a customer to pay and record the result.

For till, paybill and QR sources this sends a payment request to the customer's phone. Pitisha routes it through a healthy gateway and, if that gateway fails, moves it to the next one without you retrying. The response is pending until the customer approves; you learn the outcome from the collection.recorded or collection.failed webhook.

Headers

Idempotency-Keystring
A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.
Pitisha-Sandbox-Scenariostring
Sandbox only. Force an outcome: success, insufficient_funds, customer_cancelled or no_response.

Body parameters

amountintegerrequired
Amount in the smallest unit.
currencystringrequired
Always KES.
One of KES
sourcestringrequired
How the customer pays.
One of till, paybill, qr, bank, airtel
customerobjectrequired
For mobile money, { phone } in international format.
shortcode_idstring
Which shortcode to collect on. Defaults to your primary one for the source.
referencestring
Your reference. Shown to the customer on a paybill.
descriptionstring
Shown in your portal.
metadataobject
Your own key-value pairs.

Errors

400 invalid_request
401 authentication_failed
422 shortcode_inactive
422 wallet_frozen
409 idempotency_conflict
429 rate_limited

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/collections" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "amount": 250000,
    "currency": "KES",
    "source": "paybill",
    "customer": {
      "phone": "+254712000000"
    },
    "reference": "INV-204117",
    "description": "Order 1042",
    "metadata": {
      "order_id": "1042"
    }
  }'

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

GET/v1/collections/{id}

Retrieve a collection

Fetch one collection by id.

Path parameters

idstringrequired
The collection id.

Errors

404 not_found
401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/collections/ID_FROM_RESPONSE" \
  -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"
}

GET/v1/collections

List collections

Newest first, with filters.

Query parameters

statusstring
Filter by status.
One of pending, succeeded, failed, reversed
sourcestring
Filter by source.
One of till, paybill, qr, bank, airtel
match_statestring
Filter by how it matched.
One of matched, pile, no_match
wallet_idstring
Only payments into this wallet.
created_gtestring
ISO 8601. Created on or after.
created_ltestring
ISO 8601. Created on or before.
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/collections" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

POST/v1/collections/{id}/match

Resolve a payment in the pile

Choose which sale a pile payment belongs to.

A collection lands in the pile when more than one sale could fit it. Send the sale it belongs to and it becomes matched. A collection with no match can be matched the same way once you find the sale.

Path parameters

idstringrequired
The collection id.

Headers

Idempotency-Keystring
A unique value per logical request, up to 255 characters. Retrying with the same key returns the original result instead of creating a second one.

Body parameters

sale_idstringrequired
The sale this payment paid for.

Errors

404 not_found
400 invalid_request
409 idempotency_conflict

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/collections/ID_FROM_RESPONSE/match" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "sale_id": "sale_1042"
  }'

{
  "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"
}