Transactions

Query transaction history and check payment status.

/v3/transactions/

GET /v3/transactions/ Auth Required

List Transactions

Get paginated transaction history with optional filters.

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number
`limit`	integer	No	Results per page
`status`	string	No	pending, completed, failed, cancelled
`transaction_type`	string	No	incoming or outgoing
`channel_id`	integer	No	Filter by channel
`date_from`	string	No	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (YYYY-MM-DD)
`amount_min`	number	No	Minimum amount
`amount_max`	number	No	Maximum amount
`phone_number`	string	No	Filter by phone
`order_by`	string	No	created_at_desc (default), created_at_asc, amount_desc, amount_asc

Example Response

JSON

{
    "success": true,
    "data": {
        "transactions": [
            {
                "id": 789,
                "transaction_type": "incoming",
                "amount": 100,
                "currency": "KES",
                "status": "completed",
                "reference_number": "INV-12345",
                "external_reference": "INV-12345",
                "checkout_request_id": "ws_CO_...",
                "merchant_request_id": "12345-67890",
                "mpesa_receipt_number": "ABC123XYZ",
                "phone_number": "254712345678",
                "service_fee": 5,
                "channel": {
                    "id": 1,
                    "name": "Main Paybill",
                    "type": "paybill"
                },
                "transaction_date": "2024-12-31 12:30:00",
                "created_at": "2024-12-31 12:29:00"
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 5,
            "total_records": 95,
            "limit": 20,
            "has_next": true,
            "has_prev": false
        },
        "filters_applied": {
            "status": "completed"
        }
    },
    "timestamp": "2024-12-31T12:00:00+03:00"
}

cURL Example

bash

curl -X GET 'https://swiftwallet.co.ke/v3/transactions/?status=completed&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET /v3/transactions/?mpesa_receipt=ABC123XYZ Auth Required

Check Transaction Status

Look up a specific transaction by M-Pesa receipt, checkout request ID, or your external reference. If the row is still pending, SwiftWallet queries M-Pesa on this request (STK is synchronous; B2C/B2Pochi with a receipt may remain pending because Transaction Status is async). Repeated polls within ~15 seconds skip a new Daraja call. The list endpoint does not query M-Pesa.