Transactions API

Check status by identifiers and query transaction history with rich filters.

Status Filter

Filter by transaction status: completed, pending, failed

Type Filter

Filter by transaction type: STK, B2C, wallet

Date Range

Filter by date range: from_date, to_date

Amount Range

Filter by amount range: min_amount, max_amount

Base Endpoint

GET

/v3/transactions/

Status Check

Search by one of:

GET

/v3/transactions/?mpesa_receipt=ABC123DEF456

GET

/v3/transactions/?checkout_request_id=ws_CO_...

GET

/v3/transactions/?external_reference=PAY-001

{
  "success": true,
  "data": {
    "transaction": { /* ... see README ... */ },
    "search_type": "mpesa_receipt",
    "search_value": "ABC123DEF456"
  },
  "timestamp": "2024-01-15T14:35:00+00:00"
}

History & filtering

GET /v3/transactions/?status=completed&date_from=2024-01-01&date_to=2024-01-31&channel_id=1&limit=50&page=1&order_by=amount_desc

status: pending | completed | failed | cancelled
transaction_type: incoming | outgoing
date_from, date_to (YYYY-MM-DD)
amount_min, amount_max
phone_number, channel_id
order_by: created_at_desc (default), created_at_asc, amount_desc, amount_asc, transaction_date_desc, transaction_date_asc

Examples

# Verify by receipt
        curl -X GET "http://localhost/pay-app/v3/transactions/?mpesa_receipt=ABC123DEF456" \
          -H "Authorization: Bearer YOUR_API_KEY"

        # Today completed
        curl -X GET "http://localhost/pay-app/v3/transactions/?status=completed&date_from=2024-01-15&date_to=2024-01-15" \
          -H "Authorization: Bearer YOUR_API_KEY"