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.
• Fraud Prevention script must be added to both MSISDN and PIN pages.

Typical Flow

1. User lands on landing page.
2. Fraud Prevention Script is loaded and token is retrieved. You will be using the Dual Page Integration
3. MSISDN is retrieved or User can enter their MSISDN.
4. Merchant calls the PIN API with additional fraud_token as parameter.
5. User is directed to PIN entry page.
6. Fraud Prevention script is loaded with fraudTokenpassed into script, and token is retrieved again.
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 fraud_token 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 fraud_token parameter must be included in your API call, that is retrieved from loading the Fraud Prevention 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 fraud_token parameter must be included in your API call, that is retrieved from loading the Fraud Prevention script on your PIN capture page.

Fraud Prevention

You are required to follow Dual Page Integration with our Fraud Prevention integration. This requires you to add our Fraud Prevention JavaScript to both of your MSISDN capture page and PIN capture page, and pass the given token as fraud_token to our PIN API and Create API or One Off Charge API

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.