> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# WhatsApp & Chat Commerce

> Accept M-Pesa payments in WhatsApp, Telegram, Discord, and AI sales bots via MCP.

Lipafy enables autonomous AI sales agents to sell products, negotiate pricing, and collect payments directly inside chat apps (WhatsApp, Telegram, Discord, Web Chat) using **M-Pesa STK Push**.

```
[Customer on WhatsApp]
"I want to buy 2 pairs of Air Jordans (Size 43)"
       │
       ▼
[AI Sales Agent (Claude / OpenAI / ElizaOS)]
"Total is KES 4,500. Shall I send the M-Pesa prompt to 0712345678?"
       │
       ▼ Customer: "Yes please"
[MCP Tool: lipafy_collect_payment]
{ phone: "0712345678", amount: "4500", order_reference: "ORD-402" }
       │
       ▼
[M-Pesa STK Push Appears on Customer's Phone Screen]
"Do you want to pay KES 4,500 to Lipafy Store? Enter M-Pesa PIN:"
       │
       ▼ Customer enters PIN
[Lipafy Telemetry Callback (< 3s)]
       │
       ▼
[AI Sales Agent on WhatsApp]
"✅ Payment confirmed! M-Pesa Ref: QHK892N1P.
 Your order #ORD-402 is confirmed and being packed for delivery!"
```

---

## 🛠️ MCP Tools for Chat Commerce

When you connect Lipafy's remote MCP server (`https://api.lipafy.xyz/mcp`), your agent gets access to dedicated merchant collection tools:

### 1. `lipafy_collect_payment`

Triggers an on-device M-Pesa STK push prompt on the customer's phone.

**Parameters:**

* `phone` *(string, required)*: The customer's Kenyan phone number (e.g. `0712345678`, `0112345678`, or `254712345678`).
* `amount` *(string, required)*: Amount in whole KES to collect (e.g. `"1500"`, `"4500"`).
* `order_reference` *(string, optional)*: Order ID or invoice narrative (e.g. `"ORD-402 - 2x Air Jordans"`).
* `customer_name` *(string, optional)*: Customer's display name.

**MCP Tool Invocation Example:**

```json
{
  "tool": "lipafy_collect_payment",
  "arguments": {
    "phone": "0712345678",
    "amount": "4500",
    "order_reference": "ORD-402"
  }
}
```

**Response:**

```json
{
  "collection": {
    "payment_request_id": "topup_9b4a102e-5c7f",
    "status": "pending",
    "amount": "4500",
    "customer_phone": "254712345678",
    "order_reference": "ORD-402",
    "instructions_for_agent": "M-Pesa STK prompt for KES 4500 has been sent to customer phone 254712345678. Advise the customer to enter their M-Pesa PIN on their phone. Use lipafy_get_payment_status to verify settlement before fulfilling orders.",
    "suggested_reply_to_customer": "I've sent an M-Pesa payment prompt for KES 4,500 to your phone (254712345678). Please enter your M-Pesa PIN on your device to confirm your order."
  }
}
```

---

### 2. `lipafy_get_payment_status`

Verifies whether the customer has completed their PIN entry and settled the payment.

**Parameters:**

* `payment_request_id` *(string, required)*: The unique ID returned by `lipafy_collect_payment`.

**Response (Settled):**

```json
{
  "payment": {
    "payment_request_id": "topup_9b4a102e-5c7f",
    "status": "completed",
    "amount": "4500",
    "mpesa_receipt": "QHK892N1P",
    "is_settled": true,
    "instructions_for_agent": "Payment of KES 4500 is fully confirmed and settled (M-Pesa Ref: QHK892N1P). You can now fulfill the customer's order and dispatch goods."
  }
}
```

---

## 🤖 Full TypeScript Agent Workflow (Claude / LangChain / ElizaOS)

```typescript
import { Lipafy } from '@lipafy/sdk'

const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_API_KEY })

// Step 1: When customer confirms purchase on WhatsApp
async function handleCustomerCheckout(customerPhone: string, orderAmountKes: number, orderId: string) {
  // Trigger interactive STK push
  const prompt = await lipafy.payments.collect({
    phone: customerPhone,
    amount: String(orderAmountKes),
    orderReference: orderId,
  })

  return `I've sent an M-Pesa prompt for KES ${orderAmountKes} to your phone. Please enter your PIN to complete the order!`
}

// Step 2: Webhook listener or status poller
async function verifyPaymentSettlement(paymentRequestId: string) {
  const check = await lipafy.payments.getCollectionStatus(paymentRequestId)
  
  if (check.status === 'completed') {
    // 1. Mark order as PAID in your database
    // 2. Automatically trigger delivery rider payout via M-Pesa B2C
    await lipafy.payments.create({
      paymentType: 'CONTRACTOR_PAYOUT',
      destination: '254700112233', // Rider phone number
      amountMinor: '35000', // KES 350.00 delivery fee
      currency: 'KES',
      purpose: `Delivery fee for Order ${paymentRequestId}`,
    })

    return `Payment verified (M-Pesa: ${check.mpesaReceipt})! Courier has been dispatched.`
  }

  return 'Waiting for PIN authorization...'
}
```

---

## ⚡ Key Benefits for WhatsApp & Social Merchants

1. **Zero Drop-off:** Customers don't need to copy-paste PayBill numbers or switch between banking apps. The STK prompt appears directly on their phone screen.
2. **Fraud Proof:** No risk of fake or photoshopped M-Pesa SMS messages because fulfillment is locked to server-verified telecom settlement.
3. **Automated Revenue Splits:** Collect from customer $\to$ automatically disburse delivery rider fee via M-Pesa B2C $\to$ pay supplier wholesale cost via Till.