Mpesa Xpress and SMS Pay

End points for Mpesa Payment Confirmation and include payment details in the SMS.

Mpesa Express

The Mpesa Express feature allows users to initiate an instant STK Push to collect payments from a specified phone number. Unlike SMS Pay, which sends a payment link, Mpesa Express directly prompts the payer to input their Mpesa PIN and complete the transaction.

---

Use Case:

• Suitable when the user knows the payer’s phone number and amount to be paid.

• Ideal for scenarios requiring fast, immediate payments through Mpesa.

---

Endpoint: Mpesa Express

POST /api/payment/mpesa/express

Request Body:

{
  "phoneNumber": "254712345678",    // Phone number of the payer  
  "amount": 500,                   // Amount to be paid  
  "transactionName": "Order123",   // Name of the transaction  
  "transactionId": "TXN12345",     // Unique transaction ID  
  "callbackUrl": "https://yourapp.com/callback", // URL for payment notification  
  "description": "Payment for Order #123"       // Optional description of the payment  
}

---

Workflow:

1. The user provides the payer’s phone number and amount.

2. Tuku Pay initiates an STK Push request directly to the payer’s Mpesa app.

3. The payer receives a payment prompt on their phone and inputs their Mpesa PIN to authorize the transaction.

4. Tuku Pay sends the payment status to the callbackUrl provided by the user.

---

Response:

• 201 Created

{
  "status": "success",
  "message": "Mpesa Express initiated successfully.",
  "details": {
    "phoneNumber": "254712345678",
    "amount": 500,
    "transactionId": "TXN12345",
    "status": "pending",
    "callbackUrl": "https://yourapp.com/callback"
  }
}

• 400 Bad Request If required fields like phoneNumber or amount are missing.

---

SMS Pay

The SMS Pay feature allows users to send SMS messages with embedded payment links, providing multiple payment options to the recipient. This feature supports Mpesa, Visa/MasterCard, PayPal, and Mcoop Cash payments, making it versatile for different payer preferences.

---

Use Case:

• Ideal for situations where the payer may not have Mpesa funds but can pay via card, PayPal, or Mcoop Cash.

• Can be used for general purposes such as product payments, donations, or subscription fees.

---

Endpoint: SMS Pay

POST /api/sms/pay

Request Body:

{
  "senderId": "TUKUPAY",                // Sender ID selected by the user  
  "recipients": ["254712345678"],       // Array of phone numbers  
  "message": "Pay for your order via {paymentLink}.", // SMS body with a placeholder  
  "paymentMethods": {                  
    "mpesa": true,                     // Include Mpesa link  
    "onlineCheckout": true,            // Include online checkout link  
    "card": true,                      // Include card payment link  
    "mcoopCash": true                  // Include Mcoop Cash payment link  
  },
  "amount": 5000,                      // Amount to pay (optional for online checkout)  
  "transactionName": "Order123",       // Name of the transaction  
  "transactionId": "TXN12345",         // Unique transaction ID  
  "callbackUrl": "https://yourapp.com/callback", // For payment notifications  
  "expiryTime": "2024-12-20T23:59:59"  // Optional: Expiry time for payment links  
}

---

Sample SMS

"Dear Customer, Pay Kes 500 via one of the below methods:

• Mpesa: http://short.url
• Card Payment: http://short.url
• Online Checkout: http://short.url
• Mcoop Cash: http://short.url

Amount: Ksh 5000 Powered by Tuku Pay and Coop Bank."

Workflow:

1. Link Generation: Tuku Pay generates unique links for each payment method:

   • Mpesa Link: A URL for STK Push.

   • Online Checkout Link: Redirects to a hosted page for various payment methods.

   • Card Payment Link: A link for card payment through Visa/MasterCard.

   • Mcoop Cash Link: Prompts the payer to input their PIN in their Mcoop Cash app for Coop Bank users.

2. The links are shortened and dynamically replaced in the SMS body at the {paymentLink} placeholder.

3. The SMS is sent to the recipient(s).

4. Payment notifications are sent to the callbackUrl.

5. Transactions are recorded in the outbox with their statuses, timestamps, and costs.

---

Response:

• 201 Created

{
  "status": "success",
  "message": "SMS Pay message sent successfully.",
  "details": {
    "senderId": "TUKUPAY",
    "recipients": ["254712345678"],
    "transactionId": "TXN12345",
    "links": {
      "mpesa": "https://short.url/mpesa",
      "onlineCheckout": "https://short.url/checkout",
      "card": "https://short.url/card",
      "mcoopCash": "https://short.url/mcoop"
    },
    "expiryTime": "2024-12-20T23:59:59"
  }
}

• 400 Bad Request If required fields like amount for Mpesa or callbackUrl are missing.

---

Additional Notes for Developers

1. Mpesa Express vs SMS Pay:

   • Use Mpesa Express for immediate, direct Mpesa payments where the phone number and amount are predetermined.

   • Use SMS Pay for flexible payments with multiple options, allowing payers to choose their preferred method.

2. Custom Payment Links: For online checkout, you can pass additional metadata (like order details) in the callbackUrl to receive enriched notifications.

3. Shortened URLs: Tuku Pay automatically shortens URLs for better readability in SMS messages.

4. Mcoop Cash Integration: Coop Bank users can pay directly via their Mcoop Cash app. Ensure the payer has the app installed for this option to function.