Payments

WhatsApp & Chat Commerce

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:

1{
2  "tool": "lipafy_collect_payment",
3  "arguments": {
4    "phone": "0712345678",
5    "amount": "4500",
6    "order_reference": "ORD-402"
7  }
8}

Response:

1{
2  "collection": {
3    "payment_request_id": "topup_9b4a102e-5c7f",
4    "status": "pending",
5    "amount": "4500",
6    "customer_phone": "254712345678",
7    "order_reference": "ORD-402",
8    "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.",
9    "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."
10  }
11}

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):

1{
2  "payment": {
3    "payment_request_id": "topup_9b4a102e-5c7f",
4    "status": "completed",
5    "amount": "4500",
6    "mpesa_receipt": "QHK892N1P",
7    "is_settled": true,
8    "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."
9  }
10}

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

1import { Lipafy } from '@lipafy/sdk'
2
3const lipafy = new Lipafy({ apiKey: process.env.LIPAFY_API_KEY })
4
5// Step 1: When customer confirms purchase on WhatsApp
6async function handleCustomerCheckout(customerPhone: string, orderAmountKes: number, orderId: string) {
7  // Trigger interactive STK push
8  const prompt = await lipafy.payments.collect({
9    phone: customerPhone,
10    amount: String(orderAmountKes),
11    orderReference: orderId,
12  })
13
14  return `I've sent an M-Pesa prompt for KES ${orderAmountKes} to your phone. Please enter your PIN to complete the order!`
15}
16
17// Step 2: Webhook listener or status poller
18async function verifyPaymentSettlement(paymentRequestId: string) {
19  const check = await lipafy.payments.getCollectionStatus(paymentRequestId)
20  
21  if (check.status === 'completed') {
22    // 1. Mark order as PAID in your database
23    // 2. Automatically trigger delivery rider payout via M-Pesa B2C
24    await lipafy.payments.create({
25      paymentType: 'CONTRACTOR_PAYOUT',
26      destination: '254700112233', // Rider phone number
27      amountMinor: '35000', // KES 350.00 delivery fee
28      currency: 'KES',
29      purpose: `Delivery fee for Order ${paymentRequestId}`,
30    })
31
32    return `Payment verified (M-Pesa: ${check.mpesaReceipt})! Courier has been dispatched.`
33  }
34
35  return 'Waiting for PIN authorization...'
36}

⚡ 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.