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.
- 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
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.
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
GET https://www.aspserver.com/ussd/ 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.
HTTP/1.1 200 OK Content-Type: text/html; charset=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 :
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.
GET https://www.aspserver.com/ussd/help.jsp?option=2 Accept: text/html User-MSISDN: tel:+225xxxxxxxxxxxx User-Language: fr User-SessionId: 430d4b0d8301648f3909e363a42dfb0f
HTTP/1.1 200 OK Content-Type: text/html; charset=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