API Documentation

Mobile Billing / Premium SMS / MNO Web Opt-in

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!

MNO Web Opt-In Flow

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.

  1. Redirect the user to the MSISDN Detection platform which will return to us ( if successful ) the Network and the User ID.
  2. 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

← Previous Page - Next Page →