Each endpoint returns a standardized set of data. Below are their definitions and usage.

​
Top-level Data

KeyDefinitionRequired
ussdMessageA string that contains the display message that should be shown to the user.Yes
ussdOptionsAn array of objects that contains the mapping of the options available to the user.No
ussdConfirmAn object that contains details to confirm a request when options are not available.No

Data payloads can either contain ussdOptions and/or ussdConfirm. At least one of the objects will be returned with each response.

​
ussdOptions

A ussdOption object gives you the details of the option order, the request url to confirm the option and the type of request to make.

Example payload:

{
  "ussdMessage": "Select an investment option:\n 1. Stocks\n 2. My Portfolio\n 3. Back",
  "ussdOptions": [
    {
      "option": 1,
      "requestUrl": "https://api.staging.pipevest.com/v1/ussd/instruments?customerId=123456",
      "requestType": "GET"
    },
    {
      "option": 2,
      "requestUrl": "https://api.staging.pipevest.com/v1/ussd/portfolio?customerId=123456",
      "requestType": "GET"
    }
  ]
}
KeyDefinition
optionThe order of the option chosen by the user
requestUrlThe url endpoint to call to confirm the chosen option
requestTypeThe request type to used to make the request

​
uusdConfirm

The ussdConfirm object is returned for the following reasons:

  1. There are no options available for the user interaction.
  2. The user has to manually input some value (ex: purchase/sell amount, searching stock symbol, etc…)

Example payload:

{
  "ussdMessage": "Zamtel Message\n Your asset purchase request has been delivered. You will receive a confirmation shortly.",
  "ussdConfirm": {
    "requestUrl": "https://api.staging.pipevest.com/v1/ussd/home?customerId=123456",
    "requestType": "GET"
  }
}
KeyDefinition
requestUrlThe url endpoint to call to return the user to a specified view
requestTypeThe request type used to make the request