smartWebs API

Version 1.0 · REST · JSON · TZS only

Authentication

Include your API key in the Authorization header:

Authorization: Bearer sw_live_your_key_here

Base URL: https://smartwebs.swifttest.space/public/api/v1

Dual Wallet Model

Payment Wallet

Receives full gross amount on successful collections. Used as source for payouts.

Service Wallet

Debited for all Snippe gateway fees and smartWebs platform fees. Must be funded before API operations.

Fee Reservation & Auto-move

Before collections, deposits, top-ups, or withdrawals, estimated gateway + platform fees are reserved on the service wallet (available = balance - reserved). When service available balance falls below your threshold, funds auto-move from the payment wallet if enabled.

Wallet Operations

POST

/wallets/payment/deposit

Fund payment wallet via Snippe mobile/card

POST

/wallets/payment/withdraw

Withdraw from payment wallet to mobile money

POST

/wallets/payment/transfer

Transfer to another merchant ({ to_email, amount })

POST

/wallets/payment/move-to-service

Move funds payment → service wallet

POST

/wallets/service/topup

Top up service wallet via Snippe collection

GET

/wallets/operations

List wallet operations

GET

/wallets/operations/{id}

Get operation status

Deposit Example

curl -X POST https://smartwebs.swifttest.space/public/api/v1/wallets/payment/deposit \
  -H "Authorization: Bearer sw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": "mobile",
    "details": { "amount": 10000, "currency": "TZS" },
    "phone_number": "255781000000"
  }'

Endpoints

GET

/wallets

Get payment and service wallet balances

GET

/wallets/transactions

List wallet ledger entries (?wallet_type=payment|service)

POST

/payments

Create payment (mobile, card, dynamic-qr) — forwards to Snippe

GET

/payments

List payments

GET

/payments/{reference}

Get payment status

POST

/payments/{reference}/push

Retrigger USSD push

POST

/payouts/send

Send payout to mobile money or bank

GET

/payouts/{reference}

Get payout status

GET

/payouts/fee?amount=5000

Calculate payout fees + service wallet check

Create Payment Example

curl -X POST https://smartwebs.swifttest.space/public/api/v1/payments \
  -H "Authorization: Bearer sw_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{
    "payment_type": "mobile",
    "details": { "amount": 5000, "currency": "TZS" },
    "phone_number": "255781000000",
    "metadata": { "order_id": "ORD-001" }
  }'

Send Payout Example

curl -X POST https://smartwebs.swifttest.space/public/api/v1/payouts/send \
  -H "Authorization: Bearer sw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "recipient_name": "John Doe",
    "recipient_phone": "255781000000",
    "narration": "Salary payment"
  }'

Webhooks

smartWebs receives Snippe webhooks, settles dual wallets, then forwards events to your configured webhook URL with header X-SmartWebs-Event.

payment.completed — credits payment wallet (gross), debits service wallet (fees)
payment.failed / payment.expired
payout.completed / payout.failed

Error Codes

Code	HTTP	Description
unauthorized	401	Invalid API key
insufficient_service_balance	402	Service wallet cannot cover fees
insufficient_payment_balance	402	Payment wallet cannot cover payout
rate_limit_exceeded	429	Too many requests