POS API Documentation

Integration Capabilities

POS includes secure server-side integrations for Paysasa checkout requests, STK initiation, and reconciliation operations. Sensitive keys remain in store settings and are never exposed to browsers.

Security Model

• POS users authenticate with session cookies and RBAC permissions.
• POS server proxies calls to Paysasa using stored business credentials.
• Paysasa validates API key business scope for every operation.
• Checkout payment initiation uses idempotency keys to reduce duplicates.

Checkout Request Flow

Cashier sends a checkout request to customer identifier (phone/wallet), receives hosted URL and QR, and can optionally trigger STK on that same checkout session.

http

POST /api/integrations/airsoko-pay/checkout-request
Content-Type: application/json

{
  "amount": 1250.00,
  "currency": "KES",
  "recipient": "254712345678",
  "description": "POS checkout request - KES 1,250.00"
}

json

{
  "session_id": "ses_01...",
  "checkout_reference": "CHKOUT_...",
  "hosted_url": "https://pay.airsoko.com/checkout/ses_01...",
  "checkout_qr_url": "https://quickchart.io/qr?...",
  "mpesa_paybill_number": "174379",
  "mpesa_account_number": "CHK-..."
}

Cashier STK Shortcut

After a checkout session is created, cashier can trigger M-Pesa STK push directly to customer phone.

http

POST /api/integrations/airsoko-pay/checkout-session/stk
Content-Type: application/json

{
  "sessionId": "ses_01...",
  "phone": "254712345678",
  "customerName": "Jane Customer"
}

Reconciliation Queue Integration

Store members with reconciliation permission can review unmatched C2B callbacks and match to checkout sessions.

http

GET /api/integrations/airsoko-pay/reconciliation?status=pending_review

http

POST /api/integrations/airsoko-pay/reconciliation/{unmatchedId}/match
Content-Type: application/json

{
  "checkoutSessionId": "ses_01...",
  "force": false
}

Related Paysasa Docs

Full external API reference is available at Airsoko Pay docs and Paysasa docs.