# Mpesa Xpress and SMS Pay

#### **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**:

```json
{
  "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**

```json
{
  "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**:

```json
{
  "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**

```json
{
  "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.
