Buy SMS

This end points allows users to Buy SMS for their Accounts.

Overview

This API allows users to purchase SMS bundles to top up their SMS wallet. The value of the SMS bundle purchased will be stored, and the system will calculate the number of SMS messages based on the cost per SMS. The SMS purchase can be done either from the App Level or directly through Tuku Pay.

1. Buy SMS (Top Up SMS Wallet)

• Method: POST

• URL: /api/sms-wallet/topup

Request Body:

{
  "userId": "user123",  
  "purchaseAmount": 400,
  "paymentMethod": "mpesa",
  "paymentReference": "TUKUPAY1234567890",
  "appId": "app123",  // Optional, required if buying through app
  "paymentStatus": "success",
  "transactionId": "txn123",
  "topupDate": "2024-12-13T00:00:00Z"
}

Request Body Fields:

Field	Type	Required	Description
userId	string	Yes	The user who is purchasing SMS bundles.
purchaseAmount	number	Yes	The amount in KES spent on purchasing the SMS bundle.
paymentMethod	string	Yes	The payment method used (e.g., mpesa, visa, paypal, etc.).
paymentReference	string	Yes	The reference or transaction ID from the payment provider.
appId	string	Optional	The app ID if the purchase is done through an app.
paymentStatus	string	Yes	The status of the payment (e.g., success, failure).
transactionId	string	Yes	The unique transaction ID for the top-up.
topupDate	datetime	Yes	The date and time the top-up was completed.

Response:

{
  "status": "success",
  "smsAdded": 1000,
  "newSmsBalance": 1200,
  "userId": "user123",
  "purchaseAmount": 400,
  "unitCost": 0.4,
  "message": "Your SMS wallet has been topped up successfully."
}

Response Fields:

Field	Type	Description
status	string	The status of the top-up transaction (success, failure).
smsAdded	number	The number of SMS added to the wallet after purchase.
newSmsBalance	number	The new SMS balance after the top-up.
userId	string	The user who made the purchase.
purchaseAmount	number	The amount spent on SMS purchase (KES).
unitCost	number	The cost per SMS at the time of purchase (KES).
message	string	A success or failure message describing the top-up process.

---

2. Check SMS Balance

• Method: GET

• URL: /api/sms-wallet/balance

Query Parameters:

Field	Type	Required	Description
userId	string	Yes	The user whose SMS balance is being checked.

Response Example:

{
  "userId": "user123",
  "smsBalance": 1200,
  "unitCost": 0.4,
  "lastUpdated": "2024-12-13T00:00:00Z"
}

Response Fields:

Field	Type	Description
userId	string	The user whose SMS balance is being checked.
smsBalance	number	The current SMS balance in the user's SMS wallet.
unitCost	number	The cost per SMS at the time of the balance check.
lastUpdated	datetime	The last time the SMS balance was updated.

---

3. Set SMS Alert Threshold

• Method: POST

• URL: /api/sms-wallet/set-threshold

Request Body:

{
  "userId": "user123",
  "thresholdAmount": 5000,
  "alertType": "sms", // Can also be "email" or both
  "notificationMethod": "sms",  // Or email
  "alertMessage": "Your SMS balance is below the threshold amount.",
  "createdBy": "admin123"
}

Request Body Fields:

Field	Type	Required	Description
userId	string	Yes	The user setting the SMS threshold alert.
thresholdAmount	number	Yes	The SMS balance threshold that triggers the alert (e.g., 5000 SMS remaining).
alertType	string	Yes	Type of alert: sms, email, or both.
notificationMethod	string	Yes	The method used to notify the user (sms, email).
alertMessage	string	Yes	The custom message to send when the threshold is reached.
createdBy	string	Yes	The user who set the threshold (typically an admin).

Response Example:

{
  "status": "success",
  "userId": "user123",
  "thresholdAmount": 5000,
  "alertType": "sms",
  "message": "SMS alert threshold set successfully."
}

---

Implementation Notes

1. SMS Wallet Balancing: Each time a user purchases SMS, the system will calculate the number of SMS messages based on the pricePerSms from the sms-costs table.

2. Top-Up and Deductions: The smsAdded field indicates how many SMS credits were added to the user's SMS wallet. These credits will be deducted when an SMS is sent.

3. Payment Methods: When buying SMS, the payment can be made via MPESA, Visa/MasterCard, PayPal, or App Checkout. These methods will update the SMS wallet once the payment is processed successfully.

4. Low SMS Balance Alerts: When the SMS balance falls below the specified threshold, an alert will be triggered and sent via the configured notificationMethod (SMS or Email).

5. Default Costs: If no specific cost is defined for a user, the default SMS cost (0.8 KES) will apply