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
- User lands on landing page.
- Mobily Anti Fraud Script is loaded and
click_id
is retrieved. - MSISDN is retrieved or User can enter their MSISDN.
- Merchant calls the PIN API with additional
click_id
as parameter. - User is directed to PIN entry page.
- Mobily Anti Fraud script is loaded with
click_id
passed into script, and newclick_id
is retrieved. - User enters received PIN.
- Merchant calls Check Transaction API with
token
that was retrieved from loading the script on the PIN page. - Merchant calls Create API with additional
click_id
as parameter. - Subscription will be created with processing status if successful
- Merchant grants or denies access to content based on the response from Create API call.
- A notification will be sent once subscription status has been updated.
- 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.
Parameter | Description | Example |
---|---|---|
ids | The HTML id's of your payment form, confirmation button, and cancel button | form: 'purchase_form' confirm_button: 'form_submit_btn' cancel_button: 'form_cancel_btn' |
partner | Your Alacrity partner URI | partner:h7j9w4n8-97a4-4eb7-9ec1-4333131805cb |
service | Your Alacrity service URI | campaign:2a73f22ed63c1f8e40925632b7n10w6fed611779 |
click_id | The value is not required on your MSISDN page. The value is required on your PIN page. You should pass the value of the click_id you retrieved from loading the script on the MSISDN page. | null or c092a833-3848-43da-ac16-4e30e12c127c |
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_id
variable 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
Name | Description | Type | Usage |
---|---|---|---|
msisdn | The subscriber MSISDN that you want to send the SMS to. | string | mandatory |
campaign | The Alacrity service URI that identifies the service that this transaction belongs to. | string | mandatory |
merchant | The Alacrity merchant URI that identifies which merchant this transaction belongs to. | string | mandatory |
correlator | A unique string for this transaction. The correlator guards against accidental duplicate transactions. | string | mandatory |
text | If dynamic_SMS is passed as true the URL should be passed. The string will be displayed in the operator's customer care portal. | string | mandatory |
dynamic_sms | A flag to indicate whether the SMS is a dynamic link to be inserted into the operator's customer care portal | boolean | optional |
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.
Updated 2 months ago