Mobily KSA

There are two flows available for Mobily KSA.

• SMS API is available only to send a service URL (usually this will be some type of dynamic URL).
• No Delete API available (Please see HTTP Notifications below).
• No MO Flow.
• No Refund API.

Checkout Hosted Flow

The Checkout flow is the standard flow offered and follows the same usage as most operators.

Merchant Hosted Flow

This flow is available on approval basis.

• MSISDN Retrieval API is available on approval basis.
• The flow will be PIN flow.
• Mobily Anti Fraud script must be added to both MSISDN and PIN pages.

Typical Flow

1. User lands on landing page.
2. Mobily Anti Fraud Script is loaded and click_id is retrieved.
3. MSISDN is retrieved or User can enter their MSISDN.
4. Merchant calls the PIN API with additional click_id as parameter.
5. User is directed to PIN entry page.
6. Mobily Anti Fraud script is loaded with click_idpassed into script, and newclick_id is retrieved.
7. User enters received PIN.
8. Merchant calls Check Transaction API with token that was retrieved from loading the script on the PIN page.
9. Merchant calls Create API with additional click_id as parameter.
10. Subscription will be created with processing status if successful
11. Merchant grants or denies access to content based on the response from Create API call.
12. A notification will be sent once subscription status has been updated.
13. An additional notification of charge will also be sent.

PIN API

Pin Flow (OTP) with Mobily KSA has one minor difference from the standard API call in that a click_id parameter must be included in your API call, that is retrieved from loading the Mobily Anti Fraud script on your MSISDN capture page.

Create API

Subscription Create API with Mobily KSA has one minor difference from the standard API call in that a click_id parameter must be included in your API call, that is retrieved from loading the Mobily Anti Fraud script on your PIN capture page. This parameter will be different from the one retrieved on your previous page. Passing the token as fraud token may also be required.

Mobily Anti-Fraud Script

Add the javascript to the head section of your payment page

<script src="https://fd.sla-alacrity.com/wcrzq8rz8p2b.js"></script>

You then need to retrieve a click_id that will be used with your PIN/Create API call. You do this by calling mobilyDetector(ids, partner, service, click_id) before the page loads.

Our javascript will insert an HTML element with the id mobilyDetectorIsLoaded so that you can check that everything has loaded before submitting your form. Once loaded our javascript will also add a hidden input to your form with the name click_id and the value equal to the returned click_id. A token will also be returned on the PIN page, for you to check with the Check Transaction API before the create API.

Below is a full example using vanilla javascript of initialising the mobilyDetector, adding a listener to your form, checking that mobilyDetectorIsLoaded, and then submitting your form (with the hidden token field). Follow the below example for both of your pages, adding the click_idvariable on your PIN page.

      var ids = {
          form: 'purchase_form',
          confirm_button: 'form_submit_btn',
          cancel_button: 'form_cancel_btn',
          loading_gif: 'loading'
      };
      var partner = 'partner:00000000000000';
      var service = 'campaign:0000000000000'';
  
  	// click_id retrived from msisdn page should be added here on PIN page
      var click_id = null;

      const mobilyDetector = new MobilyDetector(ids, partner, service, click_id);
      mobilyDetector.mobily_setup();

      window.addEventListener("DOMContentLoaded", (event) => {
        var form = document.getElementById(ids['form']);
        form.addEventListener("submit", function(e) {
            e.preventDefault();

            var loadingGif = document.getElementById(ids['loading_gif']);
            loadingGif.style.display = 'block';
            var submit = document.getElementById(ids['confirm_button']);
            submit.style.background = '#f8f9fa';

            function mobilyDetectorLoaded() {
                var loaded = document.getElementById('mobilyDetectorIsLoaded');
                if (loaded && loaded.value == 'yes') {
                    form.submit();
                } else if ('requestIdleCallback' in window) {
                    var submit = document.getElementById(ids['confirm_button']);
                    submit.setAttribute('disabled', true);
                    submit.setAttribute('value', 'Loading...');
                    requestIdleCallback(mobilyDetectorLoaded);
                } else {
                    var submit = document.getElementById(ids['confirm_button']);
                    submit.setAttribute('disabled', true);
                    submit.setAttribute('value', 'Loading...');
                    setTimeout(mobilyDetectorLoaded, 100);
                }
            }
            mobilyDetectorLoaded();
        });
      });

HTTP Notifications

For subscriptions, you will receive notifications when a subscription event occurs.

Go to the HTTP Notifications page for further information

Additional Parameter for Unsub

In addition to the usual parameters, an added parameter will be added to your notification unsub_link

This parameter contains a link you can direct your subscribers to should they wish to unsubscribe. They will then just need to follow the on-screen instructions to complete the un-subscription.

Example Notifications

{
   "success":{
      "type":"subscription",
      "uuid":"05e01521-feb0-432e-846b-xxxxx",
      "bill_id":"559c26dxxxx",
      "operator":"mobily-sa",
      "merchant":"partner:xxxxx",
      "campaign":"campaign:xxxx",
      "environment":"production",
      "msisdn":"966xxxxxxx",
      "currency":"SAR",
      "amount":"0.7",
      "mode":"API",
      "frequency":"weekly",
      "unsub_link":"my.test.sla-alacrity.com/unsub/ABC123",
      "transaction":{
         "status":"SUCCESS"
      }
   }
}

{
   "success":{
      "type":"subscription",
      "uuid":"05e01521-feb0-432e-846b-xxxx",
      "bill_id":"559c26d24a46",
      "operator":"mobily-sa",
      "merchant":"partner:xxxxx",
      "campaign":"campaign:xxxxx",
      "environment":"production",
      "msisdn":"966xxxxxxxx",
      "currency":"SAR",
      "amount":"0.7",
      "mode":"API",
      "frequency":"weekly",
      "next_payment_timestamp":"2020-12-10T09:20:34Z",
      "unsub_link":"my.test.sla-alacrity.com/unsub/ABC123",
      "transaction":{
         "status":"CHARGED",
         "bill_id":"559cxxxxx",
         "timestamp":"2020-12-03T09:20:34Z",
         "transaction_id":"9066xxxx"
      }
   }
}

{
   "success":{
      "type":"subscription",
      "uuid":"05e01521-feb0-432e-846b-xxxxx",
      "operator":"mobily-sa",
      "merchant":"partner:xxxxx",
      "campaign":"campaign:xxxxx",
      "environment":"production",
      "msisdn":"966xxxxx",
      "currency":"SAR",
      "amount":"0.7",
      "mode":"OPCO_API",
      "frequency":"weekly",
      "transaction":{
         "status":"DELETED"
      }
   }
}

Send SMS - SMS API

📘

Info

Usage of the SMS API for Mobily KSA is by approval basis only.

The SMS API for Mobily KSA is the same with one exception of an optional parameter. Using this optional parameter will then insert your text into the operator's customer care portal which the user will receive in the SMS (usually this will be some type of URL for your service).

All HTTP request parameters should be passed in URL Query String - query_params.

HTTP Request

POST /v2.2/sms?msisdn={msisdn}&campaign={campaign}&merchant={merchant}&correlator={correlator}&text={text}&dynamic_sms={true/false}

Request Parameters

POST /v2.2/sms?
msisdn=966987654321&
campaign=campaign:56yhws-87e376-yuio43-45yhh7&
merchant=partner:00ow34-al6g67-12o6hh-00ff66&
correlator=we78fehjke8erwhjkre78&
text=welcome&dynamic_sms=true 
HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "error":
  {
    "category": "SMS API",
    "cdoe": "8001",
    "message": "SMS sending failed"
  }
}

❗️

Warning

Please note that if the result of sending the SMS message fails for any reason the SMS message will NOT be sent.
Please also note that the SMS API must NOT be used for marketing purposes.