USSD Integration Guide

This section provides details on how to integrate with the USSD service API endpoints, primarily focusing on generating dynamic USSD codes for specific user interactions or campaigns.

Generate USSD Codes

This endpoint allows you to dynamically generate one or more unique USSD codes that users can dial.

Request

  • Method: POST
  • URL: https://api.weflexfy.com/api/v1/ussd/generate/ussd-codes
  • Headers:
    • Content-Type: application/json
    • access_key: YOUR_APP_ACCESS_KEY (Replace with the Access Key generated for your USSD-enabled App)
    • accept: */*
  • Body (JSON):
    • count (integer, required): The number of USSD codes to generate.
    • expiresAfter (integer, optional): The time in minutes after which the generated codes should expire. If omitted, codes might have a default expiration or none.

Successful Response (201 Created)

On successful generation, the API returns a JSON object containing the generated codes.

  • Body (JSON):
    • status (string): Indicates success (e.g., "ok").
    • message (string): A confirmation message.
    • codes (array of strings): An array containing the generated USSD codes.

Example Response Body


{ 
  "status": "ok", 
  "message": "USSD codes generated successfully", 
  "codes": [ 
    "*797*50*20#", 
    "*797*50*18#" 
  ] 
}

Get Generated USSD Codes

This endpoint retrieves a list of USSD codes that were previously generated using your access key, along with their current status and expiration time.

Request

  • Method: GET
  • URL: https://api.weflexfy.com/api/v1/ussd/get/generated/ussd-codes
  • Headers:
    • access_key: YOUR_APP_ACCESS_KEY (Replace with the Access Key generated for your USSD-enabled App)
    • accept: */* (Or specify expected content type like application/json)
  • Body: None

Successful Response (200 OK)

If successful, the API returns a JSON object containing a list of your generated USSD codes and their details.

  • Body (JSON):
    • status (string): Indicates success (e.g., "ok").
    • message (string): A confirmation message.
    • codes (array of objects): An array where each object represents a USSD code and contains:
      • ussdCode (string): The actual USSD code string.
      • status (string): The current status of the code (e.g., "ACTIVE", "EXPIRED", "USED").
      • expiresAt (string, ISO 8601 format): The timestamp when the code expires or expired.

Example Response Body


{
  "status": "ok",
  "message": "USSD codes fetched successfully",
  "codes": [
    {
      "ussdCode": "*797*50*1#",
      "status": "ACTIVE",
      "expiresAt": "2025-05-28T04:31:42.808Z"
    },
    {
      "ussdCode": "*797*50*3#",
      "status": "ACTIVE",
      "expiresAt": "2025-05-28T04:31:42.808Z"
    },
    {
      "ussdCode": "*797*50*4#",
      "status": "ACTIVE",
      "expiresAt": "2025-05-28T04:31:42.808Z"
    },
    {
      "ussdCode": "*797*50*5#",
      "status": "ACTIVE",
      "expiresAt": "2025-05-28T04:36:15.689Z"
    }
    // ... more codes potentially
  ]
}

USSD Webhook Interaction

The USSD Webhook is the core of your interactive USSD service. When a user dials your USSD code and interacts with the menu, our platform sends HTTP POST requests to the secure Webhook URL you configured for your App. Your application needs to process this request and return a JSON response to dictate the next step in the USSD session.

Payload Received from Platform

Your webhook endpoint will receive a JSON payload with the following structure:


{
  "sessionId": "unique_session_identifier",
  "msisdn": "user_phone_number", 
  "input": "user_dialed_input",
  "newRequest": true_or_false 
}
  • sessionId (string): A unique identifier for the current USSD session. You'll need to include this in your response.
  • msisdn (string): The phone number (MSISDN) of the user interacting with the USSD service.
  • input (string): The data entered by the user in the previous step. This could be a menu choice (e.g., "1", "2") or text input. For the very first request of a session, this might be empty or contain the initial dial string.
  • newRequest (boolean): Indicates if this is the very first request for this session (true) or a subsequent request within the same session (false).

Response Sent to Platform

Your application MUST respond synchronously with a JSON payload. The structure of the response determines whether the session continues, ends, or ends with a payment initiation.

Response to Continue Session

To display a menu or prompt to the user and keep the session open, return the following structure:


{
  "text": "Text to display to the user (e.g., menu options or prompt)",
  "message": "(Optional) Alternative message, often same as text",
  "action": "FC",
  "sessionid": "unique_session_identifier_received",
  "continuesession": true,
  "apptimestamp": "YYYY-MM-DD HH:MM:SS" 
}
  • text / message (string, required): The text that will be displayed on the user's phone screen. Keep it concise due to screen limitations.
  • action (string, required): Must be "FC" (Free Continue) to indicate the session should continue without charge beyond standard network fees.
  • sessionid (string, required): The same sessionId received in the request payload.
  • continuesession (boolean, required): Must be true to keep the session active.
  • apptimestamp (string, required): The timestamp (e.g., in YYYY-MM-DD HH:MM:SS format, preferably in UTC or with timezone offset) when your application processed the request. This helps in tracking and debugging.

Response to End Session

To display a final message and terminate the session, return the following structure:


{
  "text": "Final message to display to the user",
  "message": "(Optional) Alternative message, often same as text",
  "action": "FB",
  "sessionid": "unique_session_identifier_received",
  "continuesession": false,
  "apptimestamp": "YYYY-MM-DD HH:MM:SS"
}
  • text / message (string, required): The final text displayed to the user before the session closes.
  • action (string, required): Must be "FB" (Free Bye) to indicate the session should end without charge beyond standard network fees.
  • sessionid (string, required): The same sessionId received in the request payload.
  • continuesession (boolean, required): Must be false to terminate the session.
  • apptimestamp (string, required): The timestamp when your application processed the request.

Response to End Session with MOMO Payment

To display a final message, terminate the session, AND initiate a Mobile Money payment request to the user's phone number, return the following structure:


{
  "text": "Message confirming payment initiation (e.g., Please approve payment)",
  "message": "(Optional) Alternative message, often same as text",
  "action": "FB", 
  "sessionid": "unique_session_identifier_received",
  "continuesession": false,
  "canPay": true,
  "paymentData": { ... payment details ... },
  "apptimestamp": "YYYY-MM-DD HH:MM:SS"
}
  • text / message (string, required): The final message displayed before the session ends (e.g., prompting the user to approve the payment on their phone).
  • action (string, required): Must be "FB" (Free Bye). Even though payment is involved, the USSD session itself ends freely.
  • sessionid (string, required): The sessionId from the request.
  • continuesession (boolean, required): Must be false.
  • canPay (boolean, required): Must be true to signal a payment initiation.
  • paymentData (object, required): An object containing the details for the MOMO payment. See structure below.
  • apptimestamp (string, required): The timestamp when your application processed the request.

Important Note on Payment Tracking: The sessionId provided in the initial USSD webhook request for this session should be treated as the unique identifier for the payment attempt. If you are also using our Payments API and its webhook system, this sessionId will correspond to the requestToken in payment status notifications for this transaction.

Payment Data Structure

The paymentData object requires the following fields:


{
  "amount": 100.00,
  "currency": "RWF",
  "billName": "Customer Name or Service Description",
  "billEmail": "customer@example.com", // Optional
  "billPhone": "user_phone_number", // Often the same as msisdn from request
  "billCountry": "RW", // Or relevant country code
  "transfers": [
    {
      "percentage": 100,
      "recipientNumber": "your_registered_momo_number",
      "payload": {} // Optional, for additional transfer metadata if needed
    }
    // Potentially more transfers if splitting payment
  ]
}
  • amount (number, required): The amount to be charged.
  • currency (string, required): The currency code (e.g., "RWF").
  • billName (string, optional): A name or description for the bill/service, shown to the user during payment approval.
  • billEmail (string, optional): The customer's email address.
  • billPhone (required, optional): The customer's phone number (often the msisdn from the incoming request). Must be in E.164 format (e.g., +250xxxxxxxxx).
  • billCountry (string, optional): The 2-letter ISO country code (e.g., "RW").
  • transfers (array, required): An array defining where the collected funds should go. For a simple payment to one account:
    • percentage (number): Typically 100 for a single recipient.
    • recipientNumber (string): Your registered Mobile Money number where the funds should be deposited. Must be in E.164 format (e.g., +250xxxxxxxxx).
    • payload (object, optional): Any additional data related to the transfer.

Important: Your application must respond to the webhook request quickly (ideally within a few seconds) to avoid timeouts on the user's end.