South Africa OBS

South Africa OBS

Originally provided by Vodacom, Online Billing Services (OBS) is a cross-network service that enables you to subscribe and charge customers for your digital content in South Africa.

Through this direct operator billing platform, customers can pay for digital services in just a few seconds and, with "Silent Billing", can manage subscription billing with no requirement for MT billing messages.

Subscription flow

Generating a Window

We recommend that you use the HTTPS endpoint when sending requests to our API. This will ensure all communications between your server and our API endpoint are encrypted. If you'd prefer not to use the secure version, the non-HTTPS version is also available.

https://client.txtnation.com/za/

The HTTP GET variables you need to use to generate an OBS window are as follows:

Variable Name Example Description
cc

joebloggs

Your company name on 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 my.messagecloud.com.

app_id

1234

Your application-specific ID. This will be provided to you by the MessageCloud team upon activation by the networks.

success_url

http://my.server.com/payment.

The URL to which the customer will be sent once they have subscribed successfully.

error_url

http://my.server.com/error

The URL to which the customer will be sent if there is an error in the subscription.

fallback_url

http://my.server.com/fallback

Customers will be redirected here if their MSISDN could not be discovered in the process.

In this URL you should request the MSISDN from the customer 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 customer (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 customer will be redirected to your fallback_url where you should request the MSISDN from the customer. This MSISDN should then be passed back to 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: "http://client.txtnation.com/za/redirect.php?id=83de3efb8d8795fa",
    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 customer 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 MessageCloud support.

1004

500

We could not generate a window at this time. Please try again later. If this problem persists then you should contact MessageCloud support.

5000

503

Service temporarily unavailable. If this problem persists then please contact MessageCloud for support.

Receiving the Callback

When the customer 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.

http://your-success-url.com/?status=001&id=724e1a6a-3fef-4863-a77d-d68e9c29cb25

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 the window generation.

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

http://your-fallback-url.com/?id=d68e9c29cb25-a77d-6348-3fef-724e1a6a

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

Status code Description
001

Billed Successfully (more information below).

006

Double opt-in requirement not completed.

007

Subscription predates MSISDN reallocation.

008

Insufficient credit.

009

Unknown subscriber or invalid MSISDN.

010

Validation failed (e.g. Unsupported subscriber type, wrong amount).

011

Billing not permitted (typically, blocked by the 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 customer 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 opt-in process. In these instances, you will need to rely on the delivery report to give the billing status.

Fallback URL

Also known as Web Billing, the customer is automatically referred to your fallback_url when they are browsing on Wi-Fi or when their MSISDN is unobtainable via their mobile data connection. It provides the opportunity to bill them outside of the single click flow.

If the MSISDN could not be discovered in the single click process, the customer will be redirected to your fallback_url where you should request the MSISDN from them. This MSISDN should then be passed back into the Window Generation API (as above) by adding the msisdn parameter. The rest of the process is managed for you via a billing flow that is known as WORAR — Web Opt-in Requiring a Reply.

Message Texts

During the process, there are several SMS messages that could be sent to the customer. The text of these messages is shown below.

Message Type Message Text

Opt-in
(where MSISDN is not found)

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}.

Customers on MTN have a slightly different message flow when no MSISDN is detected. There are 2 USSD opt-in options available after the customer has entered their MSISDN. The first is enabled by default:

Message Type Text

Direct USSD Message

After the customer 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

Once accepted, the customer will receive another USSD to confirm the charge:

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

SMS Message with Dial Prompt

SMS message sent to the customer 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}.

With both Single Click and Web Billing all chargable messages are managed for you and do not require coding. However, you will need to ensure that your fallback_url contains the regulatory information as listed here.

Should you wish to send other content to the customer you should use Gateway. This will use standard rate messaging credits.

Billing Notifications

When your customers are billed for their purchases and subscriptions you will receive a notification from us in the same format as a Gateway delivery report. See Gateway for more information.

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 customer.

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 MessageCloud to assist you faster.

Delivery Report Statuses

Report Description

DELIVERED

The customer was charged and their subscription should continue, if applicable.

FAILED

We temporarily could not capture the funds from the customer.

INVALID_MSISDN

We could not find the customer on a supported network.

NO_CREDIT

The customer 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 customer.

network

The network of the customer.

shortcode

The shortcode 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"

Event Notifications

Optionally, you can choose to receive SUBSCRIBE and UNSUBSCRIBE event notifications. Please inform the support team if you wish to receive these.

Event notifications can inform your platform when the following conditions have been met:

SUBSCRIBED Notification

  • The double opt-in process has been completed.
  • The subscriber has been added to the subscription service.
  • Welcome messages have been dispatched.
  • Subscriber billing has been initiated. A billing result callback will notify you of the outcome.

UNSUBSCRIBED Notification

  • The subscriber has been removed from the subscription service.
  • Any pending billing operations have been cancelled.
  • Termination messages have been dispatched.
  • The network operator’s opt-out process has been initiated.

The following table describes how the HTTP POST will be sent to your chosen URL:

Parameter Description

action

This will always be notification.

id

The id that you were provided with after making the initial window request.

msisdn

The MSISDN of the customer.

network

The network of the end user.

date

An ISO 8601 UTC timestamp of when the notification was received, e.g. 2018-08-03T10:30:02+00:00

status

This will be SUBSCRIBED or UNSUBSCRIBED depending on the event being notified.