# ShujaaPay Full Developer & Agentic Integration Specifications

This document provides complete, machine-readable specifications of ShujaaPay's REST API endpoints, security authentication, and autonomous payment protocol interfaces, including the native Model Context Protocol (MCP) server.

## Official Platform Resources
- Platform Root: https://shujaapay.me/
- Core Products: https://shujaapay.me/product
- Developer Portal: https://shujaapay.me/developers
- AgentsPay (AI Agent Finance): https://shujaapay.me/agentspay
- Financial Inclusion & Corridors: https://shujaapay.me/inclusion
- Executive Leadership & Team: https://shujaapay.me/team
- Industry Use Cases: https://shujaapay.me/use-cases
- Bank-Grade Compliance & AML/CFT: https://shujaapay.me/compliance
- Academic Research: https://shujaapay.me/research
- Technical Whitepapers: https://shujaapay.me/whitepapers
- Concise LLM Briefing: https://shujaapay.me/llms.txt

---

## Authentication & Headers

ShujaaPay uses JSON Web Tokens (JWT) for user-facing actions and **GNAP (RFC 9635)** scoped access tokens for API keys and autonomous AI agent operations.

### Headers Required for Private Endpoints
- `Content-Type`: `application/json`
- `Authorization`: `Bearer <token>`
- `Content-Digest`: RFC 9530 SHA-256 digest signature of payload (Optional in dev, enforced on transactions in prod).
- `Signature`: RFC 9421 signature of HTTP headers (Optional in dev).

---

## API Endpoints Reference

### 1. User Authentication & Profile

#### POST /api/auth/register
Registers a new user and auto-provisions their default ILP wallet (KES for East African numbers, USD otherwise).
- **Request Body**:
  ```json
  {
    "name": "E2E Test User",
    "email": "user@example.com",
    "password": "StrongPassword123!",
    "phone": "+254712345678"
  }
  ```
- **Response (201 Created)**:
  ```json
  {
    "user": {
      "id": "cuid_string",
      "name": "E2E Test User",
      "email": "user@example.com",
      "phone": "+254712345678",
      "kycTier": "BASIC",
      "totpEnabled": false,
      "createdAt": "2026-05-29T00:00:00.000Z"
    },
    "accessToken": "jwt_string",
    "refreshToken": "hex_string"
  }
  ```

#### POST /api/auth/login
- **Request Body**:
  ```json
  {
    "email": "user@example.com",
    "password": "StrongPassword123!"
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "requires2FA": false,
    "user": {
      "id": "cuid_string",
      "name": "E2E Test User",
      "email": "user@example.com",
      "phone": "+254712345678",
      "kycTier": "BASIC",
      "createdAt": "2026-05-29T00:00:00.000Z"
    },
    "accessToken": "jwt_string",
    "refreshToken": "hex_string"
  }
  ```

#### PATCH /api/auth/profile (Authenticated)
Updates the user profile data including nickname and avatar image.
- **Request Body**:
  ```json
  {
    "name": "John Doe",
    "nickname": "AlphaAgent",
    "phone": "+254712345678",
    "avatarUrl": "data:image/png;base64,iVBORw0KGgoAAA..."
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "id": "cuid_string",
    "name": "John Doe",
    "nickname": "AlphaAgent",
    "email": "user@example.com",
    "phone": "+254712345678",
    "avatarUrl": "data:image/png;base64,iVBORw0KGgoAAA..."
  }
  ```

#### GET /api/auth/referrals/stats (Authenticated)
Retrieve tracking statistics of referred sign-ups and earnings balance.
- **Response (200 OK)**:
  ```json
  {
    "referralCode": "REF_ALPHA",
    "clicks": 142,
    "signups": 15,
    "earnings": 45.50,
    "cashedOut": 20.00,
    "pending": 25.50
  }
  ```

#### POST /api/auth/referrals/cashout (Authenticated)
Request disbursement of referral rewards to the user's default wallet.
- **Response (200 OK)**:
  ```json
  {
    "status": "SUCCESS",
    "amount": 25.50,
    "walletId": "wallet_id_string",
    "transactionId": "tx_ref_cashout_123"
  }
  ```

---

### 2. Multi-Currency Wallets

#### GET /api/wallets (Authenticated)
Lists all wallets owned by the authenticated user.
- **Response (200 OK)**:
  ```json
  {
    "wallets": [
      {
        "id": "wallet_id_string",
        "name": "E2E Test User's USD Wallet",
        "assetCode": "USD",
        "assetType": "FIAT",
        "scale": 2,
        "isDefault": true,
        "createdAt": "2026-05-29T00:00:00.000Z"
      }
    ]
  }
  ```

#### POST /api/wallets (Authenticated)
Creates a new wallet for a specific currency asset.
- **Request Body**:
  ```json
  {
    "name": "My USD Savings Wallet",
    "assetCode": "USD"
  }
  ```
- **Response (201 Created)**:
  ```json
  {
    "id": "wallet_id_string",
    "userId": "user_id_string",
    "name": "My USD Savings Wallet",
    "assetCode": "USD",
    "assetType": "FIAT",
    "scale": 2,
    "isDefault": false,
    "createdAt": "2026-05-29T00:00:00.000Z"
  }
  ```

---

### 3. FX & Quotes Engine

#### GET /api/fx/currencies (Public)
Lists all currencies and stablecoins supported by ShujaaPay.
- **Response (200 OK)**:
  ```json
  {
    "currencies": [
      { "code": "KES", "name": "Kenyan Shilling", "type": "FIAT", "flag": "🇰🇪" },
      { "code": "USD", "name": "US Dollar", "type": "FIAT", "flag": "🇺🇸" },
      { "code": "USDC", "name": "USD Coin", "type": "STABLECOIN", "network": "Solana/Base/Ethereum" }
    ],
    "count": 3
  }
  ```

#### POST /api/fx/quote (Authenticated)
Obtains a guaranteed exchange quote.
- **Request Body**:
  ```json
  {
    "from": "USD",
    "to": "KES",
    "amount": 100
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "quote": {
      "from": "USD",
      "to": "KES",
      "amount": 100,
      "rate": 129.4688,
      "sendAmount": 100,
      "receiveAmount": 12882.15,
      "fee": 0.5,
      "feePercent": 0.5,
      "expiresAt": "2026-05-29T08:45:00.000Z"
    }
  }
  ```

---

### 4. Virtual Cards Management

#### POST /api/cards (Authenticated)
Programmatically issue a new virtual Visa/Mastercard linked to a specific wallet.
- **Request Body**:
  ```json
  {
    "walletId": "wallet_id_string",
    "brand": "MASTERCARD",
    "cardholderName": "John Doe",
    "limitAmount": 500
  }
  ```
- **Response (201 Created)**:
  ```json
  {
    "id": "card_id_string",
    "brand": "MASTERCARD",
    "last4": "4242",
    "expiryMonth": 12,
    "expiryYear": 2029,
    "cardholderName": "John Doe",
    "status": "ACTIVE",
    "dailyLimit": 500,
    "balance": 0
  }
  ```

#### GET /api/cards (Authenticated)
List all virtual cards issued under the authenticated user.
- **Response (200 OK)**:
  ```json
  {
    "cards": [
      {
        "id": "card_id_string",
        "brand": "MASTERCARD",
        "last4": "4242",
        "expiryMonth": 12,
        "expiryYear": 2029,
        "status": "ACTIVE"
      }
    ]
  }
  ```

#### PATCH /api/cards/:id/freeze (Authenticated)
Freeze or unfreeze a virtual card.
- **Request Body**:
  ```json
  {
    "freeze": true
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "id": "card_id_string",
    "status": "FROZEN"
  }
  ```

#### PATCH /api/cards/:id/limits (Authenticated)
Update daily and per-transaction limits.
- **Request Body**:
  ```json
  {
    "dailyLimit": 1000
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "id": "card_id_string",
    "dailyLimit": 1000
  }
  ```

---

### 5. Payments & Payouts (Authenticated)

#### POST /api/payments/deposit
Initiate a deposit callback or redirect request (M-Pesa, Card, crypto).
- **Request Body**:
  ```json
  {
    "walletId": "wallet_id_string",
    "method": "MOBILE_MONEY",
    "amount": 1500,
    "phoneNumber": "+254712345678"
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "checkoutRequestId": "ws_CO_220622_123456",
    "status": "PENDING",
    "message": "STK push query sent successfully."
  }
  ```

#### POST /api/payments/withdraw
Initiate withdrawal from wallet to local bank accounts, mobile money, or stablecoin crypto address.
- **Request Body**:
  ```json
  {
    "walletId": "wallet_id_string",
    "method": "MOBILE_MONEY",
    "amount": 20,
    "destination": "+254712345678"
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "transactionId": "tx_with_99827",
    "status": "SUCCESS",
    "amount": 20,
    "fee": 0.1
  }
  ```

#### POST /api/payments/bulk
Execute multiple payouts programmatically.
- **Request Body**:
  ```json
  {
    "walletId": "wallet_id_string",
    "recipients": [
      { "destination": "+254711223344", "amount": 10, "method": "MOBILE_MONEY" },
      { "destination": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "amount": 50, "method": "CRYPTO" }
    ]
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "batchId": "batch_9817a",
    "recipientsCount": 2,
    "totalVolume": 60,
    "status": "PROCESSING"
  }
  ```

---

### 6. Claim Links

#### POST /api/claim-links (Authenticated)
Lock funds into an escrow hold and generate a redemption token.
- **Request Body**:
  ```json
  {
    "walletId": "wallet_id_string",
    "amount": 25,
    "note": "Payment for freelance task"
  }
  ```
- **Response (201 Created)**:
  ```json
  {
    "id": "claim_link_id_string",
    "amount": 25.00,
    "token": "escrow_token_xyz_123",
    "claimUrl": "https://shujaapay.me/claim?token=escrow_token_xyz_123",
    "status": "UNCLAIMED"
  }
  ```

#### POST /api/claim-links/:token/claim (Public)
Claim the locked escrow funds directly to a mobile money wallet or bank account.
- **Request Body**:
  ```json
  {
    "method": "MOBILE_MONEY",
    "destination": "+254712345678"
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "status": "CLAIMED",
    "transactionId": "tx_claim_9281a",
    "message": "Funds successfully disbursed to +254712345678."
  }
  ```

---

## Model Context Protocol (MCP) Server

AI agents can directly interface with wallets and payouts using ShujaaPay's native Model Context Protocol (MCP) server.

### Connection Parameters
- **SSE Transport Endpoint**: `https://api.shujaapay.me/mcp`
- **Messages Route**: `https://api.shujaapay.me/mcp/messages`
- **Authentication**: Set the `x-api-key` header (or pass `?apiKey=<key>` query parameter).

### Expose Tools Schema Reference

#### 1. `fx_quote`
Get real-time exchange rates for target African currencies.
- **Inputs**:
  - `currency` (string, e.g., `KES`, `NGN`, `ZAR`)
  - `amount_usd` (number)
- **Output JSON**:
  ```json
  {
    "base": "USD",
    "target": "KES",
    "rate": 130.5,
    "amount_usd": 100,
    "amount_target": 13050,
    "timestamp": "2026-06-22T14:49:00.000Z"
  }
  ```

#### 2. `get_supported_corridors`
List supported payment options for a target country code.
- **Inputs**:
  - `country_code` (string, ISO 2-letter, e.g., `KE`, `NG`)

#### 3. `kyc_verify`
Validate African identities against government records.
- **Inputs**:
  - `phone_number` (string)
  - `id_number` (string)
  - `country_code` (string)

#### 4. `seller_payout_status`
Query status of blockchain USDC wallet FIAT payouts.
- **Inputs**:
  - `seller_wallet` (string)

#### 5. `execute_payout`
Trigger programmatic withdrawals or payments.
- **Inputs**:
  - `destination` (string, e.g., phone number or account)
  - `amount` (number)
  - `currency` (string, e.g., `USDC`, `KES`, `NGN`)
  - `method` (string: `MOBILE_MONEY`, `BANK_TRANSFER`, `CRYPTO`)

#### 6. `create_agent_wallet`
Spin up a new sub-wallet for an AI agent with spend limits.
- **Inputs**:
  - `agent_name` (string)
  - `daily_limit_usdc` (number, optional, default = 500)

---

## Coding Agent Guidelines (.cursorrules / ai-instructions.md)

If you are a coding agent (Cursor, Windsurf, Copilot) developing integrations for ShujaaPay, follow these guidelines:

### 1. Environment & API URL
- Production API Base URL: `https://shujaapay.me`
- All secure B2B calls require the developer secret key passed as Bearer Token:
  `Authorization: Bearer sk_live_...`
- CLI Tool: `npm install -g @shujaapay/cli`

### 2. Core Integration Endpoints
- Hosted B2B Checkout Session: `POST /api/b2b/checkout`
  Payload format:
  ```json
  {
    "amount": 100.0,
    "currency": "USDC",
    "customerEmail": "customer@example.com",
    "redirectUrl": "https://yoursite.com/success",
    "metadata": { "orderId": "XYZ-123" }
  }
  ```
  Returns: `{ "checkoutUrl": "...", "sessionId": "..." }`

- Ledger B2B Payout (Mobile Money / Bank): `POST /api/b2b/payout`
  Payload format:
  ```json
  {
    "amount": 2500.0,
    "currency": "KES",
    "payoutMethod": "mpesa",
    "phoneNumber": "+254712345678",
    "metadata": { "referenceId": "PAY-889" }
  }
  ```

- Webhook HMAC-SHA256 Signature Verification:
  Validate header `Shujaa-Signature: t=timestamp,v1=signature`.
  Compute Hex HMAC-SHA256 of `timestamp.payloadString` using your webhook secret.
+
## Managed M-Pesa Collections

Use `POST /api/b2b/collections` with `Authorization: Bearer sk_test_...`, `Idempotency-Key`, and JSON containing a positive whole-KES `amount`, `currency: "KES"`, `paymentMethod: { "type": "mpesa_stk", "phoneNumber": "254..." }`, and a merchant `reference`. Use `GET /api/b2b/collections/:id` or cursor-paginated `GET /api/b2b/collections` to retrieve status.

Creation returns `201 PENDING` after provider acceptance, `202 INITIATING` for an ambiguous provider result, `422 FAILED` for definitive rejection, and `409` if an idempotency key is reused with changed input. Never create a second STK Push after `202`; retry the original request with the same key.

Test-key simulator phones: `254700000001` succeeds, `254700000002` cancels, `254700000003` has insufficient funds, and `254700000004` times out. Subscribe to `collection.succeeded` and `collection.failed`; verify `Shujaa-Signature` against the raw body and deduplicate at-least-once deliveries using `eventId`. The full integration guide is available in the repository at `docs/managed-collections.md`, and executable examples are in `/shujaapay-postman-collection.json`.