Introduction to MTN API

MTN exposes API to 3rd parties through a global platform, exposing API to various service across it’s entire African and Middle-eastern footprint. Our platform provider for the platform, and sponsor at the 2018 TADHack Johannesburg, Huawei, will also be showcasing and helping developers test-drive MTN’s API.

As a start, for those developers that are keen to get an early start on the API, here is a quick guide on some of the key API that will be made available at the event.

A quick overview of all the API available can be found at the MTN Developer Community site.

The three most used API, which we will introduce are:

  • SMS
  • USSD
  • Payments

SMS

The SMS API allows third parties to send and receive SMS messages from their applications using a ParlayX 2.1 API standard.

Endpoint: http://<API Server>/SendSmsService/services/SendSms

Sample SOAP payload:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://www.huawei.com.cn/schema/common/v2_1" xmlns:loc="http://www.csapi.org/schema/parlayx/sms/send/v2_2/local">
   <soapenv:Header>
      <v2:RequestSOAPHeader>
         <v2:spId>2711111111</v2:spId>
         <v2:spPassword>22222222222</v2:spPassword>
         <v2:bundleID/>
         <v2:serviceId/>
         <v2:timeStamp>20181005124019</v2:timeStamp>
         <v2:OA>tel: 27VVVVVVVVVV</v2:OA>
         <v2:FA>tel: 27VVVVVVVVVV</v2:FA>
      </v2:RequestSOAPHeader>
   </soapenv:Header>
   <soapenv:Body>
      <loc:sendSms>
         <loc:addresses>tel:27VVVVVVVVVV</loc:addresses>
         <loc:senderName>8393006881433</loc:senderName>
         <loc:message>Good Afternoon, TADHACK test</loc:message>
      </loc:sendSms>
      <loc:receiptRequest>
         <endpoint>http://yourserver:8888/notifySmsDeliveryReceipt</endpoint>
         <interfaceName>SmsNotification</interfaceName>
         <correlator>12344</correlator>
      </loc:receiptRequest>
   </soapenv:Body>
</soapenv:Envelope>

USSD

Like the SMS API, The USSD API allows third parties to send and receive USSD messages from their applications using a ParlayX 2.1 API standard.

Endpoint: http://<API Server>/USSDNotificationManagerService/services/USSDNotificationManager

Sample SOAP Payload (Notification Manager):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/osg/ussd/notification_manager/v1_0/local">
   <soapenv:Header>
      <tns:RequestSOAPHeader xmlns:tns="http://www.huawei.com.cn/schema/common/v2_1">
               <spId>27111111111</spId>
      <spPassword>2222222222222</spPassword>
         <tns:serviceId></tns:serviceId>
         <tns:timeStamp>20181005124019</tns:timeStamp>
      </tns:RequestSOAPHeader>
   </soapenv:Header>
   <soapenv:Body>
      <loc:startUSSDNotification>
         <loc:reference>
            <endpoint>http://yourserver:9092/notifyUssdReception</endpoint>
            <interfaceName>startUssdNotification</interfaceName>
            <correlator>1233217686888768</correlator>
         </loc:reference>
         <loc:ussdServiceActivationNumber>156*8378*336</loc:ussdServiceActivationNumber>
         <loc:criteria>default</loc:criteria>
      </loc:startUSSDNotification>
   </soapenv:Body>
</soapenv:Envelope>

Endpoint: http://<API Server>/SendUssdService/services/SendUssd

Send USSD:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/ussd/send/v1_0/local">
     <soapenv:Header>
      <RequestSOAPHeader>
      <spId>271111111111</spId>
      <spPassword>2222222222</spPassword>
        <serviceId></serviceId>
        <linkid>29131656075600717021</linkid>    
         <timeStamp>20181005124019</timeStamp>
         <OA>27VVVVVVVVVVV</OA>
         <FA>27VVVVVVVVVVV</FA>
      </RequestSOAPHeader>
   </soapenv:Header>
   <soapenv:Body>
      <loc:sendUssd>
         <loc:msgType>1</loc:msgType>
         <loc:senderCB>FFFFFFFF</loc:senderCB>
         <loc:receiveCB>356881895</loc:receiveCB>
         <loc:ussdOpType>1</loc:ussdOpType>
         <loc:msIsdn>27VVVVVVVVVVV</loc:msIsdn>
         <loc:serviceCode>156*8378*336</loc:serviceCode>
         <loc:codeScheme>68</loc:codeScheme>
         <loc:ussdString>1 SMS 2 MMSC</loc:ussdString>
 <loc:extenionInfo> 
        <loc:item> 
          <loc:key>Coding_High_Bits</loc:key>  
          <loc:value>0</loc:value> 
        </loc:item>  
        <loc:item> 
          <loc:key>Coding_Low_Bits</loc:key>  
          <loc:value>0</loc:value> 
        </loc:item>  
        <loc:item> 
          <loc:key>Next_Menu_State</loc:key>  
          <loc:value>0</loc:value> 
        </loc:item> 
      </loc:extenionInfo>
      </loc:sendUssd>
   </soapenv:Body>
</soapenv:Envelope>

Payments (charging)

The payments API is also based on the ParlayX standard and allows a 3rd party to invoke charges to a user.

Endpoint: http://<API Server>/AmountChargingService/services/AmountCharging

Amount Charge example SOAP Payload:

<soapenv:Envelope xmlns:loc="http://www.csapi.org/schema/parlayx/payment/amount_charging/v2_1/local" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <RequestSOAPHeader xmlns="http://www.huawei.com.cn/schema/common/v2_1">
      <spId>271111111111</spId>
      <spPassword>2222222222222222</spPassword>
      <timeStamp>20181005124019</timeStamp>
    </RequestSOAPHeader>
  </soapenv:Header>
  <soapenv:Body>
    <loc:chargeAmount>
      <loc:endUserIdentifier>27VVVVVVVVVVVV</loc:endUserIdentifier>
      <loc:charge>
        <description>charge</description>
        <currency>ZAR</currency>
        <amount>1</amount>
      </loc:charge>
      <loc:referenceCode>5114689627</loc:referenceCode>
    </loc:chargeAmount>
  </soapenv:Body>
</soapenv:Envelope>

For more information, feel free to post questions below or find the Huawei desk at the event where the experts will help you setup an account, and implement the API you require for your hack. 

Leave a Reply

Your email address will not be published. Required fields are marked *