Build with the SMPLY PAY API

Overview

Every path on this page (e.g. /api/v1/wallets/:wallet_id/balance) is relative to that base URL — so a full request is, for example, POST https://api.smplypay.com/api/v1/wallets/:wallet_id/withdrawals.

The public API (/api/v1/...) covers the same core capabilities the authenticated dashboard gives a logged-in user: deposits, withdrawals, escrow, transaction history, and webhook registration. Every /api/v1/... handler is a thin wrapper around the identical function the session-authenticated dashboard calls — there is no second, independently-maintained copy of a balance check, fee calculation, or OTP flow behind the two surfaces to drift out of sync.

A crypto deposit itself still has no “initiate” endpoint — a deposit always happens by sending crypto directly to a wallet's own address on the relevant network; nothing about that changes here. What crypto payment requests add is a way to get that address and track a specific expected payment against it programmatically, without needing the dashboard. Still not exposed via the public API: currency conversion (crypto ↔ KES) is currently session-only, with no /api/v1 equivalent — worth flagging honestly rather than documenting an endpoint that doesn't exist.

Authentication

Every request must carry four headers, and the signature covers the request's method, path, body, a timestamp, and a nonce — not just proof you possess a key, but proof you authored this exact request.

1. Get an API key

From the authenticated dashboard's Developer page (POST /developer/api-keys, session-authenticated), create a key with a label. The response includes key_id (safe to store/display) and secret — shown exactly once. There is no “view secret again” endpoint; if you lose it, revoke the key and create a new one.

2. Required headers

3. What gets signed

Build this exact string, newline-separated, then HMAC-SHA256 it with your secret and hex-encode the result:

{timestamp}\n{method}\n{path_and_query}\n{nonce}\n{body}

# method:        HTTP method, upper case ("POST", "GET")
# path_and_query: request path including query string, no scheme/host
#                 (e.g. "/api/v1/wallets/abc-123/balance")
# body:           exact raw request body bytes, UTF-8 — empty string
#                 for a body-less GET, never "null" or omitted

The fields are joined with a plain newline (\n) — not concatenated directly — so a value containing the delimiter can never shift a later field's boundary.

4. Timestamp tolerance & replay protection

A request is only accepted if its X-Timestamp is within 300 seconds of the server's clock, in either direction (this is configurable server-side; 300s/5 minutes is the default). That alone doesn't stop a captured request being replayed within that window — a second layer does: every (key_id, nonce) pair is recorded on first use, and a request presenting a nonce that key has already used is rejected outright, regardless of how fresh its timestamp still reads. Never reuse a nonce.

Complete, correct examples

These are runnable — adapted directly from this project's own scripts/sign_and_call.py sample client, not simplified pseudocode.

import hashlib, hmac, os, secrets, time, urllib.request

key_id = os.environ["SMPLY_API_KEY_ID"]
secret = os.environ["SMPLY_API_SECRET"]
base_url = "https://api.smply-pay.example.com"

def canonical_string(timestamp, method, path_and_query, nonce, body):
    return "\n".join([timestamp, method, path_and_query, nonce, body])

def sign(secret, message):
    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()

path = "/api/v1/wallets/YOUR_WALLET_ID/balance"
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)   # fresh, random, every request
body = ""                        # empty for this GET

message = canonical_string(timestamp, "GET", path, nonce, body)
signature = sign(secret, message)

request = urllib.request.Request(
    url=base_url + path,
    headers={
        "X-Api-Key-Id": key_id,
        "X-Signature": signature,
        "X-Timestamp": timestamp,
        "X-Nonce": nonce,
    },
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY=""
MESSAGE="$TIMESTAMP\nGET\n/api/v1/wallets/YOUR_WALLET_ID/balance\n$NONCE\n$BODY"
SIGNATURE=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SMPLY_API_SECRET" -hex | sed 's/^.* //')

curl "https://api.smply-pay.example.com/api/v1/wallets/YOUR_WALLET_ID/balance" \
  -H "X-Api-Key-Id: $SMPLY_API_KEY_ID" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $NONCE"

A full, dependency-free reference client (Python standard library only) also lives at scripts/sign_and_call.py in this project's own repository — copy it directly rather than re-implementing signing from scratch.

Deposits

{
  "phone_number": "254712345678",
  "amount": "500"
}

{
  "id": "e2add425-10c7-45ab-8931-a9698c2f2365",
  "wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "status": "pending",
  "checkout_request_id": "ws_CO_...",
  "merchant_request_id": "29115-...",
  "amount": "500",
  "phone_number": "254712345678",
  "result_description": null,
  "created_at": "2026-08-31T12:00:00Z",
  "updated_at": "2026-08-31T12:00:00Z"
}

{
  "business_short_code": "174379",
  "account_number": "SP7K2M9Q"
}

Wallet balance

Requires View-level access. Returns every currency this platform supports — sixteen rows: KES, the native coin of each of the five crypto networks, and USDT and USDC on each of those five networks — regardless of whether the wallet actually holds a non-zero balance in each one; a freshly-created wallet returns sixteen rows all reading "0", not an empty array or a filtered list. Rows are sorted by currency string (so KES first). Crypto currencies are identified as "{network}:{symbol}" (e.g. "ethereum:ETH", "polygon:USDT") — not the bare symbol alone, since the same symbol exists on more than one network.

[
  { "currency": "KES", "amount": "500.000000000000000000" },
  { "currency": "celo:CELO", "amount": "0" },
  { "currency": "celo:USDC", "amount": "0" },
  { "currency": "celo:USDT", "amount": "0" },
  { "currency": "ethereum:ETH", "amount": "0" },
  { "currency": "ethereum:USDC", "amount": "0" },
  { "currency": "ethereum:USDT", "amount": "0" },
  { "currency": "optimism:OP", "amount": "0" },
  { "currency": "optimism:USDC", "amount": "0" },
  { "currency": "optimism:USDT", "amount": "0" },
  { "currency": "polygon:POL", "amount": "0" },
  { "currency": "polygon:USDC", "amount": "0" },
  { "currency": "polygon:USDT", "amount": "12.500000000000000000" },
  { "currency": "solana:SOL", "amount": "0" },
  { "currency": "solana:USDC", "amount": "0" },
  { "currency": "solana:USDT", "amount": "0" }
]

Amounts are full-precision decimal strings, not floats — every non-zero amount on this page carries the underlying column's full NUMERIC(38,18) scale (e.g. "500.000000000000000000", not "500"), confirmed directly against live responses. Other examples on this page are shown at reduced precision for readability — parse them as decimals, never as JSON numbers/floats, either way.

Withdrawals

{
  "amount": "500",
  "destination_type": "phone",
  "phone_number": "0712345678"
}

{
  "amount": "500",
  "destination_type": "paybill",
  "business_number": "888880",
  "account_number": "ABC123"
}

{
  "amount": "500",
  "destination_type": "buy_goods",
  "till_number": "999999"
}

{
  "amount": "0.1",
  "destination_type": "crypto",
  "network": "ethereum",
  "address": "0xAbC123...",
  "token_symbol": null
}

{
  "id": "430d3909-8400-432c-bb03-dc8082866508",
  "wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "status": "pending",
  "currency": "KES",
  "amount": "200.000000000000000000",
  "fee_amount": "4.000000000000000000",
  "net_amount": "196.000000000000000000",
  "destination_type": "phone",
  "destination_description": "phone 254712345678",
  "destination_caveat": null,
  "provider_reference": null,
  "result_description": null,
  "created_at": "2026-08-31T19:30:34Z",
  "updated_at": "2026-08-31T19:30:34Z",
  "settled_at": null
}

{ "code": "123456" }

Transaction history

With wallet_id: recent ledger entries for that one wallet (requires View-level access). Without it: a genuine aggregation across every wallet you belong to, newest first — the one endpoint with no single-wallet session-dashboard equivalent to wrap.

[
  {
    "id": "f1a2...",
    "wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
    "entry_type": "stk_deposit",
    "currency": "KES",
    "amount": "500",
    "reference_id": "0b6f19c2-5d4e-4a7b-9c1e-2f8d7a6b5c40",
    "created_at": "2026-08-31T12:00:00Z"
  }
]

amount is signed: credits are positive, debits negative. reference_id is the record the entry belongs to — the withdrawal id for withdrawal entries, the escrow id for escrow entries, the transfer id for transfer entries — or null when there is none. For M-Pesa deposits it is an internal receipt-record id (not the STK deposit id), useful only as a stable identifier. Use it to fetch details the entry doesn't carry — for example, a withdrawal_debit is the gross amount (payout plus fee); fetch GET /api/v1/withdrawals/:reference_id for its fee_amount and net_amount. Entry types include stk_deposit, paybill_deposit, crypto_deposit, withdrawal_debit, withdrawal_reversal, the escrow entries (escrow_funding_debit, escrow_release_credit, escrow_commission_credit, escrow_refund_credit, …) and transfer_debit/transfer_credit.

Escrow

{
  "receiver_wallet_id": "b8f3...",
  "manager_wallet_id": null,
  "currency": "KES",
  "amount": "10000",
  "commission_rate_percentage": "2.5",
  "reference": "order-4821"
}

{
  "id": "c4d5...",
  "depositor_wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "receiver_wallet_id": "b8f3...",
  "manager_wallet_id": null,
  "currency": "KES",
  "amount": "10000",
  "commission_rate_percentage": "2.5",
  "receiver_amount": "9750",
  "commission_amount": "250",
  "status": "funded",
  "caller_roles": ["depositor"],
  "confirmations": [],
  "reference": "order-4821",
  "result_description": null,
  "created_at": "2026-08-31T12:00:00Z",
  "updated_at": "2026-08-31T12:00:00Z",
  "released_at": null,
  "disputed_at": null,
  "refunded_at": null
}

{
  "escrows": [
    { "receiver_wallet_id": "b8f3...", "manager_wallet_id": "9a1c...", "currency": "KES",
      "amount": "6000", "commission_rate_percentage": "5", "reference": "order-4821" },
    { "receiver_wallet_id": "d2e7...", "manager_wallet_id": "9a1c...", "currency": "KES",
      "amount": "4000", "commission_rate_percentage": "5", "reference": "order-4822" }
  ]
}

{ "confirmation_type": "receiver" }

{ "amount": "1500", "reason": "One item out of stock" }

{ "resolution": "release" }

Wallet transfers

{
  "destination_wallet_id": "b8f3...",
  "currency": "KES",
  "amount": "2500",
  "reference": "iou-payment-7781",
  "description": "IOU INV-7781 repayment"
}

{
  "id": "5b0e...",
  "source_wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "destination_wallet_id": "b8f3...",
  "currency": "KES",
  "amount": "2500",
  "reference": "iou-payment-7781",
  "description": "IOU INV-7781 repayment",
  "debit_ledger_entry_id": "7c1d...",
  "credit_ledger_entry_id": "8e2f...",
  "created_at": "2026-09-23T10:00:00Z"
}

Crypto payment requests

A trackable “I'm expecting a crypto payment for this amount/reference” object — built for accepting crypto payments programmatically (your own checkout flow, or another business system) rather than watching a wallet's balance by hand. Why this exists on top of a wallet's own deposit address: a wallet's crypto deposit address is reused for its entire lifetime (one address per key family — the same address covers Ethereum, Polygon, Celo, and Optimism at once), so a bare address alone can't tell two payments you're expecting at the same time apart. A payment request gives each expected payment its own trackable record, resolved automatically once a matching deposit confirms.

{
  "wallet_id": "b7c3e0b6-6fd6-4cc9-b311-1f08c3717fed",
  "network": "ethereum",
  "token_symbol": null,
  "expected_amount": "0.05",
  "reference": "order-9F2K",
  "expiry_minutes": 60
}

{
  "id": "b79c0d3c-0369-43d8-aa00-a9953834243a",
  "wallet_id": "b7c3e0b6-6fd6-4cc9-b311-1f08c3717fed",
  "network": "ethereum",
  "currency": "ethereum:ETH",
  "expected_amount": "0.050000000000000000",
  "reference": "order-9F2K",
  "status": "pending",
  "matched_deposit_ledger_entry_id": null,
  "deposit_address": "0xd0510003A76Eebff3948219902D21F345BE38521",
  "expires_at": "2026-09-01T14:51:00.224738Z",
  "created_at": "2026-09-01T13:51:00.225528Z",
  "updated_at": "2026-09-01T13:51:00.225528Z"
}

[
  {
    "id": "b79c0d3c-0369-43d8-aa00-a9953834243a",
    "wallet_id": "b7c3e0b6-6fd6-4cc9-b311-1f08c3717fed",
    "network": "ethereum",
    "currency": "ethereum:ETH",
    "expected_amount": "0.050000000000000000",
    "reference": "order-9F2K",
    "status": "pending",
    "matched_deposit_ledger_entry_id": null,
    "deposit_address": "0xd0510003A76Eebff3948219902D21F345BE38521",
    "expires_at": "2026-09-01T14:51:00.224738Z",
    "created_at": "2026-09-01T13:51:00.225528Z",
    "updated_at": "2026-09-01T13:51:00.225528Z"
  }
]

On matching more than one open request at once, stated honestly: an incoming deposit is matched by amount (this platform's chain integrations carry no memo/tag field to disambiguate by anything else). An exact amount match always wins; if you open more than one concurrent request for the same wallet/currency, give each a distinct expected_amount (a unique trailing decimal digit is enough) to guarantee an incoming payment can never be mismatched between them.

Webhook registration

Registers a callback URL for your account. The URL is validated against a public, non-private address at registration time (and again immediately before every delivery, since DNS can change in between).

{ "url": "https://your-service.example.com/webhooks/smply-pay" }

{
  "id": "d6e7...",
  "url": "https://your-service.example.com/webhooks/smply-pay",
  "secret": "shown-exactly-once...",
  "created_at": "2026-08-31T12:00:00Z"
}

secret is shown exactly once, the same as an API key's own secret — see Verifying deliveries for what it's for.

Creating accounts & wallets

Signed the same way as every other request on this page (HMAC-SHA256, see Authentication), just with a partner key's own key_id/secret instead of a regular API key's — the canonical string format and headers are identical. A partner key can only create accounts (plus the two narrow, same-partner-only actions below) — every other action on an account (balance checks, deposits, withdrawals) goes through that account's own ordinary API key, returned below, using the exact same /api/v1/... surface documented above. Never reuse the partner key itself for those calls. A partner can only ever act on accounts it itself created — every route below rejects a request from a different partner's key, even one that's otherwise validly signed.

Source-IP allowlist. SMPLY PAY can restrict a partner's keys to the IP addresses or CIDR ranges your integration calls from. Once an allowlist is set for your partner account, any partner-key request from another address is refused with 403 ("requests for this partner are not allowed from this IP address"), even if it's correctly signed. Send us your servers' outbound IPs before going live, and tell us before they change. With no allowlist set, requests are accepted from any IP.

{
  "email": "enduser@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "0712345678",
  "webhook_url": "https://your-service.example.com/webhooks/smply-pay"
}

{
  "email": "accounts@smplypay-innovation.example.com",
  "business_name": "SMPLYPAY INNOVATION LIMITED"
}

{
  "user_id": "b6e2...",
  "wallet_id": "43d7...",
  "display_name": "SMPLYPAY INNOVATION LIMITED",
  "api_key_id": "3f2c...",
  "api_key_secret": "shown-exactly-once...",
  "webhook_id": "9d2a...",
  "webhook_secret": "shown-exactly-once...",
  "created_at": "2026-09-16T12:00:00Z"
}

{
  "wallet_id": "9d2a...",
  "owner_user_id": "b6e2...",
  "created_at": "2026-09-16T12:10:00Z"
}

{
  "api_key_id": "7c1e...",
  "api_key_secret": "shown-exactly-once...",
  "created_at": "2026-09-16T12:05:00Z"
}

Events & payloads

Every registered endpoint receives a delivery for each of these events, fanned out per event to every endpoint you've registered.

{
  "wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "entry_type": "stk_deposit",
  "amount": "500",
  "currency": "KES",
  "new_balance": "13000",
  "ledger_entry_id": "f1a2...",
  "reference_id": "0b6f19c2-5d4e-4a7b-9c1e-2f8d7a6b5c40"
}

{
  "wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "amount": "500",
  "currency": "KES",
  "destination": "phone 254712345678",
  "new_balance": "12500"
}

{
  "escrow_id": "c4d5...",
  "status": "released",
  "reference": "order-4821",
  "currency": "KES",
  "amount": "10000",
  "receiver_amount": "9750",
  "commission_amount": "250",
  "commission_rate_percentage": "2.5",
  "depositor_wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "receiver_wallet_id": "b8f3...",
  "manager_wallet_id": null,
  "result_description": null
}

Amounts and parties are included so you can reconcile without a follow-up GET. For a refunded escrow, receiver_amount and commission_amount are "0"; after a partial refund, amount is the remaining escrowed amount. deposit.settled carries ledger_entry_id (unique per deposit — a safe dedupe key) and reference_id (an internal source-record id, when there is one — for M-Pesa this is the processed-receipt record, not the STK deposit id).

{
  "transfer_id": "5b0e...",
  "source_wallet_id": "43d71324-0af8-4efa-8211-c43cb9c47423",
  "destination_wallet_id": "b8f3...",
  "currency": "KES",
  "amount": "2500",
  "reference": "iou-payment-7781",
  "description": "IOU INV-7781 repayment"
}

{
  "payment_request_id": "f50a4e9e-4afd-46ab-b78a-4f0b86bc2e83",
  "wallet_id": "b7c3e0b6-6fd6-4cc9-b311-1f08c3717fed",
  "status": "confirmed",
  "paid_amount": "0.05",
  "currency": "ethereum:ETH",
  "ledger_entry_id": "cc2db2c5-cb8a-4ead-b1b5-fbe0104e0002"
}

{
  "payment_request_id": "f50a4e9e-4afd-46ab-b78a-4f0b86bc2e83",
  "wallet_id": "b7c3e0b6-6fd6-4cc9-b311-1f08c3717fed",
  "status": "expired"
}

Delivered to the API key owner who created the request specifically — unlike deposit.settled/withdrawal.*/escrow.*/transfer.completed above, which fan out to every Manage-level member of the wallet(s) involved, a payment request is your own integration's object from the moment you create it, so only your own registered endpoint(s) hear about it.

Verifying deliveries

Yes — outbound webhook deliveries are genuinely signed, using the identical HMAC scheme inbound API requests use (same canonical-string format, same headers), so you can verify a delivery actually came from SMPLY PAY rather than trusting the source IP or TLS alone. This is not a hypothetical/planned feature — it's the current implementation, confirmed directly in crates/api/src/webhooks.rs.

Recompute the signature the same way inbound requests are verified — canonical string {timestamp}\nPOST\n{path}\n{nonce}\n{body}, HMAC-SHA256 with your webhook secret (from the registration response, shown once), hex-encoded — and compare it to X-Signature using a constant-time comparison, not ==.

Retries & backoff

A delivery that fails (non-2xx response, or a transport-level error) is retried with exponential backoff — 30s, 1m, 2m, 4m, 8m — up to 6 attempts total. If the 6th attempt also fails, the delivery is dead-lettered (no further retries) roughly 15 minutes after the first attempt. Your endpoint should be idempotent per delivery (keyed by the delivery's X-Nonce) in case a retry succeeds on your end but the response is lost in transit.

Error responses

Every non-2xx response has the same shape:

{ "status": "error", "message": "human-readable description" }

Rate limits

A rate-limited request returns 429 with the standard error shape above.