MNO Web Opt-in
Web Opt-in is practically a single-click opt-in, but it will ONLY work if the user is browsing via his/her mobile device while connected to the MNOs Mobile Data.
It will NOT work if the user is connected to the WiFi!
Mobivate currently provides the MNO Web Opt-In in the following regions
South Africa
Flow:
Redirect the user to the Lookup URL. Once the lookup is performed, user will be sent back to your Return URL.
Upon the return the user will already be subscribed to your service and you can start sending billed messages, but only if the status
variable is success
https://<content portal url>/lookup/za/
?shortcode={shortcode}&service={keyword}={product_id}&freq={billing frequency}
&campaign={campaign name}&amount={billing amount}&bl={brand logo}
&bc={background color}&tc={text colour}&return={your return URL}
Required Parameters
Attribute | Sample Value | Description |
---|---|---|
shortcode | 30000 | Your associated shortcode |
service | apple=aaaabbbbcccccddddd | Keyword and the ProductID |
freq | 1-7,31 | 1 -7 messages per week, or if 31 then it's single monthly billing |
campaign | Our Games | Campaign Description |
amount | 10 | Amount of Rand (ZAR) billed per billing request |
bl | http://yourdomain/logo.png | Full URL to your Header Image |
bc | ffffff | HEX value for the background colour |
tc | 000000 | HEX value for the text colour |
return | http://yourdomain/returned | Return URL |
Return URL Parameters
Parameter | Description |
---|---|
status | MNO subscription status, either success or failed |
message | Any message passed through from the MNO |
userid | If the MSISDN was detected, the fully qualified MSISDN |
network | MNO identifier |
Example
http://yourdomain/returned?status=success&userid=277123456789&network=vodacomsa
Nigeria
User Detection & Subscription in Nigeria
To subscribe a user in Nigeria, for Direct Carrier Billing, we must perform two separate steps.
- Redirect the user to the MSISDN Detection platform which will return to us ( if successful ) the Network and the User ID.
- Call the Subscribe method on the API providing the UserID and the ServiceID.
Requesting the UserID
To request the UserID, you should have the following information ready:
Return URL
(Your FULL URL, including the http://... . User will be sent back to this url upon completion.)MTN Product ID
(required for detecting MTN customers)Your Reference ID
(optional)
Flow: Redirect the user to the Lookup URL. Once the lookup is performed, user will be sent back to your Return URL
https://<content portal url>/lookup/ng/?return={RETURN_URL}&ad_id={MTN_PRODUCT_ID}&ref_id={YOUR_REFERENCE}
The user will return to the given Return URL with the following (GET) parameters appended.
Attribute | Example | Description |
---|---|---|
status |
success / failed | Describing the status of the lookup |
userid |
abcd4321_-$ | Returned only if status==success! A ASCII value unique to this subscriber, instead of the MSISDN. |
network |
mtnng / etisalatng | Returned only if status==success! Network name for the subscriber |
message |
Returned only if status==failed! Error description |
Examples
On Successful detection user will return to your domain:
http://www.yourdomain.com/nigeria-user-detection?status=success&userid=$abcd1234$&network=etisalatng
On failure, user will return to your domain while:
http://www.yourdomain.com/nigeria-user-detection?status=failed&message=Failed+to+detect+UserID.
Subscribing the User to the Service
Once you have the UserID you can request a subscription to your service. For this you can use our NetworkSubscription API.
For subscribing a MTN Customer request:
GET: https://<content portal url>/lookup/subscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}
For subscribing a Etisalat Customer request:
GET: https://<content portal url>/lookup/subscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}
Where the required parameters are:
Parameter | Description |
---|---|
userid |
The userid that was sent to your Return URL |
keyword |
The ProductID that you wish to subscribe the user to. Bare in mind, if subscribing the user to MTNNG, you must use the same MTN_PRODUCT_ID as you did when requesting the USER ID |
The Response All requests will return HTTP Code 200 and a JSON body.
Examples
On Success:
{
subscribed: true,
message: "Subscription request has been accepted!",
code: 202
}
or on Failure:
{
subscribed: false,
message: "Execution Error: Invalid Ad Id",
code: 400
}
Unsubscribing user from the Service
Unsubscription works the same way the Subscription request does except the URL endpoint is slightly different.
For un-subscribing a MTN Customer request:
GET: https://<content portal url>/lookup/unsubscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}
For un-subscribing a Etisalat Customer request:
GET: https://<content portal url>/lookup/unsubscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}
Error Codes
Code | Description |
---|---|
202 | Request has been accepted |
400 | Execution Error: ... |
409 | Network Generated Error (custom message follows) |
417 | Invalid response received |
501 | Unknown network |
600 | Missing UserID or Keyword parameters |
601 | Request failed for unknown reason |
Delivery Notifications
On successfully billed request, a notification will be sent to your nominated URL.
Example
GET: http://www.yourdomain.com/nigeria-notifications?user-identity=$abcd1234$&service-id=xyz&status=1
Where the possible status codes are:
Status | Description |
---|---|
0 | New subscription started |
1 | Positive Billing |
2 | Failed Billing, Insufficient funds |
3 | Inactive Subscription, User opted out |