About Us

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 preformed, user will be sent back to your Return URL

 https://content.mobivate.com/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.mobivate.com/lookup/subscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}

For subscribing a Etisalat Customer request:

GET: https://content.mobivate.com/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.mobivate.com/lookup/unsubscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}

For un-subscribing a Etisalat Customer request:

GET: https://content.mobivate.com/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