Docs / API reference

Payouts

Send money to a phone or a bank account from a wallet.

The Payout object

Money sent out from one of your wallets. Payouts cannot be recalled once they are sent.

Attributes

idstring
Unique identifier, starting pay_.
statusstring
Where the payout is. pending_approval means a second person must approve it first; the money is held meanwhile.
One of pending_approval, pending, sent, failed, canceled, rejected
amountinteger
Amount in the smallest unit.
currencystring
Always KES.
destinationobject
A phone number or a bank account.
wallet_idstring
The wallet the money came from.
referencestring | null
Your reference.
feeinteger
The fee charged for this payout, in the smallest unit.
approvalobject | null
Present when the payout needed approval: { required, requested_by, decided_by, decided_at }.
failureobject | null
A code and message when status is failed.
livemodeboolean
false in the sandbox.
created_atstring
ISO 8601 timestamp.

Example object

{
  "id": "pay_2xk9d7",
  "object": "payout",
  "status": "sent",
  "amount": 1200000,
  "currency": "KES",
  "destination": {
    "type": "phone",
    "phone": "+254722000000"
  },
  "wallet_id": "wal_payroll",
  "reference": "SALARY-OCT-0007",
  "reason": "salary",
  "fee": 2000,
  "approval": null,
  "failure": null,
  "metadata": {},
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}

POST/v1/payouts

Create a payout

Send money from a wallet.

The wallet must hold enough balance for the amount plus the fee. That money is held from the moment you create the payout. If the amount is above your approval threshold the payout starts as pending_approval and is only sent once a different person approves it in the portal (see the Approvals guide). Use an Idempotency-Key so a retry after a network error cannot pay twice.

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

amountintegerrequired
Amount in the smallest unit.
currencystringrequired
Always KES.
One of KES
wallet_idstringrequired
The wallet to pay from.
destinationobjectrequired
{ type: "phone", phone } or { type: "bank_account", account_number, bank_code }.
referencestring
Your reference.
reasonstring
For example salary, refund or supplier.

Errors

400 invalid_request
422 insufficient_funds
422 wallet_frozen
422 verification_required
503 service_stopped
409 idempotency_conflict
401 authentication_failed

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/payouts" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{
    "amount": 1200000,
    "currency": "KES",
    "wallet_id": "wal_payroll",
    "destination": {
      "type": "phone",
      "phone": "+254722000000"
    },
    "reference": "SALARY-OCT-0007",
    "reason": "salary"
  }'

{
  "id": "pay_2xk9d7",
  "object": "payout",
  "status": "pending",
  "amount": 1200000,
  "currency": "KES",
  "destination": {
    "type": "phone",
    "phone": "+254722000000"
  },
  "wallet_id": "wal_payroll",
  "reference": "SALARY-OCT-0007",
  "reason": "salary",
  "fee": 2000,
  "approval": null,
  "failure": null,
  "metadata": {},
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}

GET/v1/payouts/{id}

Retrieve a payout

Fetch one payout by id.

Path parameters

idstringrequired
The payout id.

Errors

404 not_found

See Errors for what each means.

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

{
  "id": "pay_2xk9d7",
  "object": "payout",
  "status": "sent",
  "amount": 1200000,
  "currency": "KES",
  "destination": {
    "type": "phone",
    "phone": "+254722000000"
  },
  "wallet_id": "wal_payroll",
  "reference": "SALARY-OCT-0007",
  "reason": "salary",
  "fee": 2000,
  "approval": null,
  "failure": null,
  "metadata": {},
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}

GET/v1/payouts

List payouts

Newest first.

Query parameters

statusstring
Filter by status.
One of pending_approval, pending, sent, failed, canceled, rejected
wallet_idstring
Only payouts from this wallet.
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/payouts" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "pay_2xk9d7",
      "object": "payout",
      "status": "sent",
      "amount": 1200000,
      "currency": "KES",
      "destination": {
        "type": "phone",
        "phone": "+254722000000"
      },
      "wallet_id": "wal_payroll",
      "reference": "SALARY-OCT-0007",
      "reason": "salary",
      "fee": 2000,
      "approval": null,
      "failure": null,
      "metadata": {},
      "livemode": false,
      "created_at": "2026-10-28T11:20:04+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

POST/v1/payouts/{id}/cancel

Cancel a payout

Stop a payout that has not been sent.

Only a payout that is still pending or waiting for approval can be canceled. Held money returns to the wallet. Once it is sent it cannot be recalled.

Path parameters

idstringrequired
The payout id.

Errors

404 not_found
400 invalid_request

See Errors for what each means.

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

{
  "id": "pay_2xk9d7",
  "object": "payout",
  "status": "canceled",
  "amount": 1200000,
  "currency": "KES",
  "destination": {
    "type": "phone",
    "phone": "+254722000000"
  },
  "wallet_id": "wal_payroll",
  "reference": "SALARY-OCT-0007",
  "reason": "salary",
  "fee": 2000,
  "approval": null,
  "failure": null,
  "metadata": {},
  "livemode": false,
  "created_at": "2026-10-28T11:20:04+03:00"
}