South Africa MSISDN Forwarding (Single Click)

From txtNation Wiki
Jump to: navigation, search

South Africa MSISDN Forwarding enables single click subscriptions and billing across Vodacom, MTN and CellC.


Transaction flow


Generating a Window

To create a window you should perform an HTTP GET request to:

The API expects the following parameters to be sent:

Variable Name Example Description Restrictions
cc joebloggs Your company name in our platform This must be between 2 and 30 alphanumeric characters
ekey 88C3CF364123A25BBAB687D4FE8EC628 Your ekey in our platform This will be provided on set up and is available in
app_id 1234 Your application-specific ID This will be provided to you by the txtNation team upon activation by the networks
success_url The URL to which the end user will be sent once they have subscribed successfully n/a
error_url The URL to which the end user will be sent if there is an error with the subscription n/a
fallback_url The URL to which the end user will be sent if we could not determine the MSISDN End users will be redirected here if their MSISDN could not be discovered in the process. In this URL you should request the MSISDN from the end user and pass it back to this API, along with with the other parameters, as a new request to continue the process.
msisdn 277272727272 The MSISDN of the end user (if known) If you do not know the MSISDN you should leave this parameter empty.

If the MSISDN could not be discovered in the process, the end user will be redirected to your fallback_url where you should request the MSISDN from the end user. This MSISDN should then be passed back into this API via a new request to continue the billing process.

A successful call to this API will return JSON in the format:

       status: "OK",
       redirect: "",
       id: "724e1a6a-3fef-4863-a77d-d68e9c29cb25"

The id returned to you in this response should be stored as any future communications about this transaction, including billing status, will be sent to you with this value. You should then redirect the end user to the redirect location using an HTTP 302 redirect.

An unsuccessful call to the API will result in an ERROR status, along with details explaining why the call was unsuccessful. For example:

        status: "ERROR",
        error_code: 1000,
        error_message: "Missing parameter in request: app_id"

Other errors that you could encounter are listed below:

Error code HTTP Code Description
1000 400 Your request did not contain all required parameters. The missing parameter will be mentioned in the error_message.
1001 400 Your request contained a parameter that did not match the format we were expecting. The bad parameter will be mentioned in the error_message.
1002 403 The authentication credentials (cc and ekey) you provided were incorrect.
1003 500 We could not generate a window at this time. Please try again later. If this problem persists then you should contact txtNation support.
1004 500 We could not generate a window at this time. Please try again later. If this problem persists then you should contact txtNation support.
5000 503 Service temporarily unavailable. If this problem persists then please contact txtNation for support.

Receiving the Callback

When the end user has finished on the window, after the billing attempt has been done, they will be forwarded to your success_url or your error_url depending on the status of the billing.

We will append the status and id parameters to your success_url so that you can associate this redirect with the id provided to you during Window Generation.

If the MSISDN of the end user cannot be determined they will be sent to your fallback_url with the id parameter.

A full list of status codes are provided below for your reference.

Status code Description
001 Billed Successfully (Further information below)
006 Double Opt-in requirement not completed
007 Subscription predates MSISDN reallocation
008 Insufficient credit
009 Unknown Subscriber/Invalid MSISDN
010 Validation failed (e.g. Unsupported subscriber type, wrong amount)
011 Billing not permitted (Blocked by network)
012 Billing frequency/limits exceeded
013 Transaction denied due to policy (e.g. adult content)
014 Monthly billing limits exceeded
015 Please contact support for further information
016 Transaction aborted
017 Transaction failed

Status 001 with Wi-Fi

In some cases, when a user completes the flow from your Fallback URL on Wi-Fi, we may pass them to your success URL with status=001 before they have completed the optin process. In these instances you will need to rely on the Delivery Report to give the billing status.

Network Status Codes (Deprecated)

The below status codes are no longer in use however, in the event you receive them for any reason, they are listed below.


Status code Description
EBO-006 SubscriberMSISDN is required
EBO-007 Access denied. Email address does not match with what is on record
EBO-008 Event Billing Partner [<<partnerID>>]/[<<partnerMSISDN>>] not found
EBO-009 Event Billing transactions not allowed for Event Billing Partner. Current Status = [<<partner.PARTNERSTATUS>>]
EBO-010 Double Opt-In amount may not exceed maximum [<<MaxOptInAmountCents>>]
EBO-011 Double Opt-In amount must be greater than 0
EBO-012 Double Opt-In expiryDate cannot be in the past
EBO-013 Double Opt-In expiryDate must be before ["+maxAllowedExpiryDateTime+"]
EBO-014 Unsupported content frequency [<<contentFrequency>>]
EBO-015 Opt-in is once-off. Recurrence [<<recurringContentFrequency>>] is not allowed
EBO-016 Opt-in is recurring. Recurrence must either be omitted or be greater than zero
EBO-017 Opt-in recurrence must be either or omitted or be greater than zero
EBO-018 Failed to generate new tokenID
EBO-019 Failed to generate new telkom transaction reference number
EBO-020 Unknown token [<<token_id>>]
EBO-021 Invalid token [<<token_id>>]. Subscriber [<<MSISDN>>] has been ceased.
EBO-022 Invlaid token [<<token_id>>]. Token is in an invalid state: [<<token_status>>]
EBO-023 Invalid request. Token [<<token_id>>] Partner MSISDN does not match request
EBO-024 Invalid request. Token [<<token_id>>] Partner ID does not match request
EBO-025 Invalid request. Requested amount exceeds opt-in maximum amount [<<token_max_amount>>]
EBO-026 Invalid request. Requested amount must be greater than 0
EBO-027 Invalid request. Token [<<tokenid>>] ContentID, content type and/or content description does not match request
EBO-028 Invalid request. Token ["+moi.tokenId+"] subscriberID does not match request
EBO-030 Failed to create double opt in
EBO-031 Failed to handle opt-out request properly: <<reason>>
EBO-050 Subscriber rejected opt-in: <<Subscriber Response>>
EBO-051 Timeout occurred checking subscriber status against IN platform
EBO-052 An error occurred lookin up subscriber against the IN platform
EBO-053 Subscriber not [ACTIVE]. OptIn not allowed
EBO-054 Timeout occurred waiting for the opt-in SMS delivery acknowledgement
EBO-055 An error occurred sending the opt-in SMS to subscriber
EBO-056 No opt-in SMS response was received from subscriber
EBO-057 An error occurred performing NotifyDoubleOptInResult/NotifySubscriberOptOut
EBO-058 Timeout occurred waiting for NotifyDoubleOptInResult result
EBO-059 An error occurred sending the NotifySubscriberOptOut request
EBO-060 Charge is pending. Please try again later
EBO-061 Duplicate charge found for [SubscriberID=<<>>]/[TransactionID=<<>>]: [ResultMsgCode: <<>>] [ResultMsg: <<>>]
EBO-062 Charge not allowed. Only possible after <<NextAllowedDateTime>>
EBO-063 Timeout occurred charging subscriber account
EBO-064 An error occurred charging the subscriber account
Huawei-4012 The account balance is insufficient for fee deduction when fees cannot be deducted forcibly
EBO-065 StartDate is not wellformed. Format expected [yyyy-MM-dd]
EBO-066 EndDate is not wellformed. Format expected [yyyy-MM-dd]
EBO-067 EndDate is not wellformed. Format expected [yyyy-MM-dd]
EBO-099 Token has expired
EBO-099 Unsupported SoapAction [SOAP_ACTION]


Status code Description
0 OK
201 Service Already Exists
202 Insufficient Funds
203 Subscriber Blacklisted
204 Duplicate Request - Pending subscriber Opt In
206 Charge Error – Permanent
208 Request Error – Permanent
209 Renotify success
210 Renotify exceeded - maximum allowed renotifications exceeded
211 Renotify exceeded - maximum allowed renotifications exceeded
212 Rejected by Filter – prohibited word
213 Maximum allowed charges exceeded
214 Incorrect charge interval
215 Incorrect Charge Code
216 addSubscription – Invalid MSISDN, lookup failed chargeSubscriber – Subscriber hotlined/suspended/churned
217 Invalid Content Type
218 Incorrect ServiceName / ContentProvider length
220 Service in Clearing Period - 24 hours
221 Subscription not found
223 Billing Error
224 No service id specified
225 Rejected, Subscriber rejected the subscription, in 24h clearing period
226 Cancelled, Subscription has been cancelled, in 24h clearing period
227 Churned, Subscriber churned, in 24h clearing period
228 Inactive Subscriber: Returned by CRM
230 Invalid Subscriber: Returned by CRM


Status code Description
SVC0001 Service Error: <Service Call>
SVC0010 Missing Data: <Field>
10 Double Opt-In request expired
12 Invalid ServiceCode
16 Invalid OperationCode
20 Double Opt-In request already exist
30 Double Opt-In Record does not exist
40 WASP Subscription already exists on ICAP
41 WASP Subscription does not yet exist on ICAP
51 REINFORM: Record does not exist in DOI_TRANSACTION table
108 Error calling BS_ExecuteTransaction: AuthRes is not equal to '05'
109 Error calling BS_ExecuteTransaction: RAB Price is not equal to WASP Price
110 Error Calling DOI RETRY operation
10002 No valid address(es) – This error is returned when a Vodacom backend system is unable to retrieve any information for the specific MSISDN, i.e. the MSISDN is not an active Vodacom MSISDN.


Status code Description
0 Successful
3800 System error
3801 Maximum number of redirections reached
3802 Internal configuration error
3810 Too many concurrent requests
3811 XRPC Timeout
3812 Bad Parameters
4622 The account login request failed, as the account is not authorized.
4623 WASP account disabled
4625 Login failed
4704 Bad parameters specified
4706 Invalid OTP
4707 Permission to login denied
4708 Partner ID or Link ID incorrect
4711 The account is not authorized to do the request
4712 Invalid debit amount specified
4713 Session Token is invalid
4714 Maximum requests exceeded
4715 Session has expired
4717 Debit amount not found in rating table
4718 TBB Logout failed
4719 Mediation failed
4720 Bad Response
4723 Request validation failed
4725 WASP account disabled
4726 Permission to login timeout
4727 Billing currency disallowed
4728 Zero Rated billing disallowed
4734 Incorrect HTTP Request Type
4735 Incorrect Service Type
4736 The subscriber declined the authorization.
4737 Incorrect bill interval
4742 Invalid Partner Identifier
4743 Invalid Partner Name
4744 Invalid Transaction ID
4745 Invalid MSISDN
4746 Invalid Content Type
4747 Invalid Content Description
4748 Invalid Content ID
4749 Invalid RSN
4755 Subscriber unknown
4756 Insufficient funds
4757 Request failed
4758 Daily credit limited reached for this subscriber
4761 Monthly credit limit reached for the subscriber
4762 Amount Requested Not Authorised
4763 Rating ID Invalid
4764 Service Provider ID Invalid
4767 Subscriber Barred
4769 Subscriber type not supported
4770 WASP Daily Limit reached
4771 WASP Monthly Credit Limit reached
4774 Subscriber not RICA verified
4775 Subscriber Suspended
4776 Unable to debit subscriber before the first billable date
4777 Unable to back bill a Once-Off token
4778 Invalid Recovery Day
4780 Token not found
4781 Adhoc token not found
4782 Token in Pending State
4783 Token is Suspended by subscriber
4784 Token is Suspended by MTN
4785 Token is Suspended by WASP
4786 Token is expired/invalid
4787 Token cannot be created, mandatory parameters missing.
4788 Token was declined by subscriber
4789 No approval received from the subscriber
4790 Token is invalid because Subscriber Disconnected
4791 Token maximum billing amount for service interval reached
4793 Invalid Service Interval
4794 Invalid Max Bill Amount
4795 Invalid Code
4796 Invalid Token ID
4797 Token is already in the Active State
4798 Invalid Free Days
4799 Backbilling Amount Not Authorised

Fallback URL

Also known as Web Billing, the user is automatically referred to your Fallback URL when they are browsing via Wifi or when their MSISDN is unobtainable via their data connection. It provides the opportunity to still bill the user outside of the Single Click page.

If the MSISDN could not be discovered in Single Click the process, the end user will be redirected to your fallback_url where you should request the MSISDN from the end user.

This MSISDN should then be passed back into the Single Click API (as above) in the first API call - adding the MSISDN parameter continues the billing process. The rest of the process is managed for you via a billing flow that is known as WORAR - Web Op-tin Requiring a Reply.

Message Type Message Text
Opt-in Single Click: User clicks button to agree.

or if no MSISDN detected:

WORAR: Reply YES to this message to complete your subscription to {service name} @R5 every 2 days. For help call {toll free customer support number}.

Welcome Message Welcome to {service name}. You are subscribed at a charge of R5/every 2 days. To unsubscribe reply STOP or SMS STOP to {shortcode}. For help call {toll free customer support number}.
Comfort Message You are subscribed to {service name} SMS at a charge of R5 every 2 days. To unsubscribe reply STOP or SMS STOP to {shortcode}. For help call {toll free customer support number}.
Termination Message You have been unsubscribed from {service name}. For help call {toll free customer support number}.

Users on MTN where no MSISDN is detected there are 2 USSD opt-in options available after the user has entered their MSISDN. The first is enabled as default:

Option 1) Direct USSD Message

After user has entered their MSISDN they are sent a USSD message as follows:

Please confirm your request for {service name} from {company name} at R3.00/week. 1. Accept 2. Decline

Option 2) SMS Message with Dial Prompt

SMS message sent to the user as follows:

"Dial *141*5*775# to confirm your subscription to {service name} @R3.00/week. Ignore this message to opt out. Assistance call {company name} on {customer service number}."

After completing the above a USSD message is received saying:

"{Company names} wants to charge you for {service name} and R3.00 per week. Press 1 to accept. Press 2 to decline."

With both Single Click and Web Billing all message flows are managed for you and do not require coding, however you do need to ensure that your fallback URL contains the regulatory information as listed here.

Should you wish to send content to the user you should perform a Gateway post as detailed on which will use standard rate message credits at your normal charge.

Billing Notifications

When your end users are billed for their purchases and subscriptions you will receive a notification from us in the same format as a delivery report from Gateway. This uses HTTP POST.

Parameter Description
action The type of notification. For the purposes of billing notifications, this value will always be mp_report.
id The id of original window request, as returned in Generating a Window.
number The MSISDN of the end user.
report The status of the billing attempt (see Delivery Report Statuses, below).
reason_id On failure we will provide you with a more specific code. This can be used by txtNation to assist you faster.

Delivery Report Statuses

Report Description
DELIVERED The end user was charged and their subscription should continue, if applicable.
FAILED We temporarily could not capture the funds from the end user.
INVALID_MSISDN We could not find the end user on a supported network.
NO_CREDIT The end user had insufficient funds to complete the transaction.

Opt outs

As with the billing notifications, we will send you opt out requests in the same format as Gateway. Again, these will be sent as an HTTP POST.

Parameter Description
action The type of notification. For the purposes of opt out notifications, this value will always be mpush_ir_message.
id The id of original window request, as returned in Generating a Window.
number The MSISDN of the end user.
network The network of the end user.
shortcode The short code from which we received the opt out request.
message This will be the stop request text, normally passed to you in the format: "ask <your_company_name> stop"
Personal tools