API Playground Dashboard

Wallet

Manage wallet balances and initiate top-ups/deposits.

/v3/wallet/

Wallet Types

service

Service wallet used for fees and subscriptions

payments

Payments wallet used for B2C disbursements

GET /v3/wallet/ Auth Required

Get Wallet Balance

Get current wallet balances (no transaction list).

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`

Query Parameters

Parameter	Type	Required	Description
`balance`	string	No	service, payments, payment, service_wallet_balance, or payments_wallet_balance

Example Response

JSON

{
    "success": true,
    "data": {
        "user_id": 123,
        "balances": {
            "service_wallet_balance": 850,
            "payments_wallet_balance": 5000
        }
    },
    "timestamp": "2024-12-31T12:00:00+03:00"
}

cURL Example

bash

curl -X GET 'https://swiftwallet.co.ke/v3/wallet/' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST /v3/wallet/ Auth Required

Wallet Operations

Initiate a payments wallet deposit or service wallet top-up.

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`action`	string	Yes	deposit or topup
`wallet_type`	string	No	Optional override: service or payments
`amount`	number	Yes	Amount to top up/deposit
`phone_number`	string	Yes	Phone for STK Push
`user_callback_url`	string	No	Optional callback for wallet deposit updates

Example Response

JSON

{
    "success": true,
    "data": {
        "message": "Payment request sent to your phone. Please enter your M-PESA PIN to complete.",
        "reference_number": "TOPUP-123-1704020000",
        "amount": 500,
        "phone_number": "254712345678",
        "wallet_type": "service"
    },
    "timestamp": "2024-12-31T12:00:00+03:00"
}

cURL Example

bash

curl -X POST 'https://swiftwallet.co.ke/v3/wallet/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "deposit",
    "wallet_type": "service",
    "amount": 500,
    "phone_number": "254712345678"
  }'

GET /v3/wallet/status Auth Required

Wallet Deposit Status

Check the status of a wallet deposit/top-up by reference number.

Headers

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`

Query Parameters

Parameter	Type	Required	Description
`reference`	string	Yes	Reference number from wallet deposit response

Example Response

JSON

{
    "success": true,
    "data": {
        "reference_number": "TOPUP-123-1704020000",
        "status": "pending",
        "amount": 500,
        "phone_number": "254712345678",
        "created_at": "2024-12-31 12:00:00",
        "updated_at": "2024-12-31 12:00:00",
        "message": "Your deposit is being processed. Please wait a moment."
    },
    "timestamp": "2024-12-31T12:00:00+03:00"
}

cURL Example

bash

curl -X GET 'https://swiftwallet.co.ke/v3/wallet/status?reference=TOPUP-123-1704020000' \
  -H 'Authorization: Bearer YOUR_API_KEY'