.wpb_animate_when_almost_visible { opacity: 1; }
#303# My Store
Create and distribute your USSD service on #303# My Store to reach all Orange customers in the Middle East & Africa, including feature phone users.
1.0

This document describes each step of the whole process to programmatically display USSD messages to an Orange subscriber, through the Orange #303# My Store API.

Terminology:

  • service provider : individual or organization that aim at offering a USSD service through #303# My Store
  • service: your application that offers a USSD service by providing a set of USSD menus
  • service URL: your application URL endpoint, that that provides USSD menus by delivering usual xHTML pages

Before starting

In order to be able to provide a USSD service to Orange subscribers through the Orange #303# My Store API, you need first to sign a contract with our local business unit. Please contact our B2B Sales team by filling this form and they will put you through our local business unit. Once you have signed a contract you can start developing your service to publish it on #303# My Store.

Using the API

The Orange #303# My Store API enables a simple and straight-forward way to provide a USSD service to Orange subscribers: a USSD service is a standard web application that delivers HTML pages.

Since there is no standard API for USSD, Orange #303# My Store API is based on a subset of xHTML: Orange back-end server sends HTTP GET requests to service provider using SSL, on behalf of the mobile user, exactly like a web browser does. Service provider is expected to reply with xHTML pages.

Token

Contrary to others API such as the SMS one, no token is required. This is because within the USSD case, the HTTP client is on Orange side and the HTTP server is your application.

Complementary information & useful tips

  • After contract signature, ask Orange to provide you the complete #303# My Store API Interface Contract, to have all technical details regarding the usage of this API; these “Getting Started” and Interface contract documents are both useful for your developments;
  • MSISDN format : the MSISDN format of the end-users uses the international format, for e.g. +225 12345678 for Ivory Coast, i.e. prefixed with the country code.
  • UTF-8 charset usage is mandatory;
  • Don’t put special characters in your text flows;

Now, let's appreciate the #303# My Store API simplicity!

You are now ready to receive requests from #303# My Store, on behalf of Orange subscribers. Below are the options your service USSD may choose while replying to incoming GET HTTPs requests.

Displaying a menu

Incoming requests follows always the same scheme. For example below is an example of access to the main menu of your application. Pages may contain text and one or more menu items at the same time

Request

GET https://www.aspserver.com/ussd/ HTTP/1.1
Accept: text/html
User-MSISDN: tel:+225xxxxxxxxxxxx  User-Language: fr
User-SessionId: 430d4b0d8301648f3909e363a42dfb0f

Your application just has to reply with an xHTML file describing the menu. Typical result on the subscriber's phone is displayed on the right.

Answer

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 
<?xml version="1.0" encoding="UTF-8"?> <html>
  <head>
    <title>Main page</title>
  </head>
  <body>
Welcome to my service<br/>
Please select:<br/>
    <a href="menuOne.html">Activate</a><br/>
    <a href="misc/menuTwo.html">Options</a><br/>
    <a href="help.jsp?option=2" accesskey="9">Contact</a>
  </body>
</html>

The Title tag is not accepted.

Menu choices constraints :

don’t put menu numbers as in the below example :

<html><body>مرحبا<br/>USSD app menu:<br/>1-Test<br/>2-B<br/>3-D<br/>4-MMMM<br/>5-GGGG<br/>…<br/>9-OTHER<form action="orange_ussd.php"><input type="text" name="response"/></form></body></html>

but use (only) href word, as in the below example : enter image description here

The local USSD gateway may add links for navigation commands, e.g. 0:Back, 00:Home. This is a country dependant feature and cannot be changed through the #303# My Store browsing API.

Displaying a plain text

Pages may contain just plain text.

Request

GET https://www.aspserver.com/ussd/help.jsp?option=2 HTTP/1.1
Accept: text/html
User-MSISDN: tel:+225xxxxxxxxxxxx  User-Language: fr
User-SessionId: 430d4b0d8301648f3909e363a42dfb0f

Answer

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 
<?xml version="1.0" encoding="UTF-8"?> <html>
  <body>
Contact information: <br/>
Please contact customer support at +2xx xxxxxxxx
  </body>
</html>

Asking for user input

When user input is required, the application server can request the user to enter some free text, using the tags

& . The content of the form will be sent to the ASP using a HTTP GET.

Request

GET https://www.aspserver.com/ussd/askForZipcode.html HTTP/1.1
Accept: text/html
User-MSISDN: tel:+225xxxxxxxxxxxx  User-Language: fr
User-SessionId: 430d4b0d8301648f3909e363a42dfb0f

Answer

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 
<?xml version="1.0" encoding="UTF-8"?> <html>
  <body>
Please enter your zip code:<br/>
    <form action="enter_zip.jsp">
        <input type="text" name="response"/>
    </form>
  </body>
</html>

Once the user has dialled its response, Orange back-end APIs calls back the ASP on the URL indicated in the form:

GET https://www.aspserver.com/ussd/enter_zip.jsp?response=38400

Constraints:

  • The tag is fixed and must contains type="text" name="response"
  • The user answer is always carried using the "response" parameter If navigation commands (0:Back, 00:Home) are provided by the local USSD browser, then navigation keys are evaluated first : in the above example (into the frame), 0 or 00 are understood as navigation shortcuts, and not replies to the question; so, “form action” works only if there is only one data input, and not a list of choices.

Closing a session

When the user sequence is finished, with no possibility to reach another page, then the session can be ended by the ASP using the tag and the specific name/value pair: "nav / end"

Request

GET https://www.aspserver.com/ussd/byeMessage.html HTTP/1.1
Accept: text/html
User-MSISDN: tel:+225xxxxxxxxxxxx  User-Language: fr
User-SessionId: 430d4b0d8301648f3909e363a42dfb0f

Answer

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 
<?xml version="1.0" encoding="UTF-8"?> <html>
<head>
  <meta name="nav" content="end"/>
</head>
  <body>
Thanks for using my Service<br/>
Goodbye !
  </body>
</html>