Overview

The Premium API allows you to accept one-time payments, and to implement premium subscription models, using a supported mobile payment method.

In addition, it handles subscriptions to your campaign for you and allows you to charge your subscribers either through direct carrier billing or through premium SMS. Finally, it supports the delivery of Free-to-end-user(FTEU) content. It supports multiple opt-in methods, e.g. through MO or through PIN verification, as well as automatic SMS opt-outs and API opt-outs.

The available options provided by the API are presented below. Please note that some of the capabilities mentioned may NOT be supported in your country, due to regulatory reasons.

High-Level Overview

The Premium API allows content / service providers to accept mobile payments from mobile network subscribers, through different mobile payment methods.

API handles all the complexity of managing subscriptions (opt-ins and opt-outs), so that the Content Provider (CP) or Service Provider (SP) never has to worry about sending unsolicited messages to consumers.

Subscriptions

It handles customer subscriptions, through 3 optin methods:

- MO SMS opt-in flow (customer sends SMS message from their phone to initiate subscription),
- Web opt-in flow (customer inserts their mobile number on a web page to initiate subscription),
- Web opt-in flow with SMS invitation (customer inserts their mobile number on a web page to initiate subscription).

It provides the merchant with the API methods to receive incoming MOs (Mobile Originated messages), as well as verify the subscription using a PIN code or SMS invitation.

Depending on the regulatory requirements for a suitable opt-in process to your premium service, you can choose one of these opt-in methods.

Subscription through SMS

Two variations exist, depending on the flow of SMS required for a subscription to be considered complete: Single SMS Opt-in and Double SMS Opt-in.

Single SMS Opt-in

The consumer simply texts in to immediately be considered an active subscriber / participant of the service. The only action required to complete the opt-in is the sending of the (MO) SMS by the consumer.

Double SMS Opt-in

The consumer starts the subscription process by texting in to a short code. When a double opt-in mechanism is required, our platform will automatically reply with a confirmation SMS to the consumer, asking them to confirm that by this action they will be participating in the specific service and informing them about any premium costs involved, e.g. recurring weekly costs, etc.

The consumer is asked to reply back confirming their participation, in order to be considered as fully opted-in to this particular service.

Subscription through Web, with PIN verification

The merchant can initiate the subscription of a customer, e.g. when the customer inserts their mobile phone number in the merchant's web form.

The merchant uses the PIN verification functionality offered by the API, through the “send PIN” API endpoint. API is then responsible for sending an SMS to the customer containing a one-time use PIN code. The merchant should then request the PIN code from the customer (e.g. through a form in the web site) and then try to verify it through the “verify PIN” API endpoint.

If the verification was successful, the customer will be subscribed to the particular service.

Subscription through Web, with SMS invitation and MO reply verification

The merchant can initiate the subscription of a customer, e.g. when the customer inserts their mobile phone number in the merchant's web form.

The merchant uses the SMS Invite verification functionality offered by the API, through the “sendInviteMessage” API endpoint, in order to send a message asking consumers to confirm by replying back with an SMS. With this action the merchant informs the users that they will be subscribing to the specific service, which involves the specific costs/MT charges, etc.

If the consumer replies back he is considered as fully opted-in to this particular service.

Unsubscription

The customer can unsubscribe from the merchant’s service by sending an MO with the STOP keyword. The MO will be forwarded to the merchant to the registered URL for receiving MOs.

Also, the merchant can initiate the unsubscription of a specific customer, by calling the opt- out API endpoint to unsubscribe a customer.

Subscriber Protection & Regulatory Compliance

One of the main value propositions of API is the mechanism it has in place in order to protect the mobile network subscribers from any actions that are against the local regulations.

In turn, this is also protection for the Service Provider (SP) against the regulating body. Fines could be imposed on the SP and any of its international partners (e.g. Content Providers (CP)), for such actions, whether they were performed on purpose, or by mistake, or accident. Therefore, all partners can have peace of mind, because the API is responsible for enforcing these rules.

In particular, API, offers the following features:

● No Unsolicited Messages
● Enforce Maximum Spending / Maximum Charge Limits
● Enforce Free MT ratio

Unsolicited Messages

One of the main concerns for the telecoms regulating bodies in most countries is that the mobile network subscribers might be contacted (e.g. receive SMS messages, etc) from Value- Added Services (VAS) to which they have not opted-in to.

API solves this problem by taking control of the automated subscription / unsubscription process and maintaining the subscriber base internally, in its database.

In addition to this, API only accepts content for delivery to a particular mobile phone number in relation to a particular service id. At that point, it can confirm that the intended recipient is indeed a valid subscriber to the particular service. If not, the content is rejected.

Enforce Maximum Spending / Maximum Charge Limits

Another common regulation is that any mobile network subscriber cannot exceed a certain spending limit over a certain period, for a particular service. For example, there might be a limit of a maximum charge of 25 EUR per month, per subscriber, for each VAS.

Because the API handles all the payments coming through for the particular service, it is also in a position to enforce that this limit is never exceeded. Any extra attempts for a payment that would be taking the subscriber over the limit are rejected.

Enforce Free MT ratio

A number of Mobile Network Operators offer a number of Mobile Terminated (MT) SMS that can be sent back to the mobile subscribers at no charge for the service provider. This is usually in place for Mobile Originated (MO) billing Premium SMS short codes, where the subscriber pays for the MO but receives back a free MT. In those cases, the MTs are also free of charge for the service provider, and are calculated based on an MO/MT ratio.

For example, in the case where the MNO offers an 1/2 MO/MT ratio, the service provider can send up to 2 free MTs for each billable MO SMS received on the particular short code.

API has a mechanism in place that, when enabled, can ensure that this ratio is never exceeded and that the SP is always protected against such extra charges from the MNO.

DLR Callback

This section describes the various messages the API will send to the merchant and the responses the merchant must send back by implementing the respective receivers on their side.

The "Forward DLR" function forwards to the merchant a Delivery Report (DLR) that has been received and it is related to an MT they have sent to a subscriber.

For each DLR, the merchant will receive a POST HTTP callback to the DLR callback URL defined for the service. Posted parameters are:

To test your implementation:

curl -X POST "http://YOUR-DLR-URL"
    -H "accept: */*"
    -d "serviceId=0&subscriberId=0&messageId=0&paymentId=0&status=d&substatus=d&network=string"

Merchants must implement a DLR Receiver on their side that will accept the above requests and will reply with an HTTP status code "200 OK" if they managed to receive and process the DLR information properly or an error status code in any other case.

For more information about the possible values of the status and sub-status fields please refer to Appendix – Statuses and Sub-Statuses.

MO Callback

The "Forward MO" function forwards to the merchant an MO SMS that has been sent by a subscriber to one of their registered short codes.

For each MO, the merchant will receive a POST HTTP callback to the MO callback URL defined for the service. Posted parameters are:

To test your implementation:

curl -X POST "http://YOUR-MO-URL"
    -H "accept: */*"
    -d "serviceId=0&subscriberId=0&shortCode=string&text=string&moId=0&network=string&amount=0&currencyCode=string&optout=string&msisdn=string"

Merchants must implement an MO Receiver on their side that will accept the above requests and will reply with an HTTP status code "200 OK" if they managed to receive and process the MO information properly or an error status code in any other case.

charges/charge

Direct charge of the subscriber

charges/reverse

Reverse charge performed to subscriber, either direct or sms

messages/fteu

Send Free to end user message

messages/premium

Send premium message to subscriber

messages/sendInviteMessage

Send invitation message to end-user

pins/send

Send PIN via SMS, which can later be verified from a user, to become a subscriber

pins/verify

Verify a PIN that was previously submitted via SMS, in order for the end user to become a subscriber

subscribers/get

Get Subscriber information and details

subscribers/optout

Opt-out (unsubscribe) subscriber from service

Error Responses

All error responses have the HTTP status code in the range of 4XX (for client errors) or 5XX (for server errors) passed into 'response' parameter within the JSON object. The error responses contain a JSON entity in the following format:

{ "code": 0, "message":"error description", "respose": 401 }

The possible values for the error responses can be found in the following table:

Statuses

Describes all values of the status and substatus parameters of a forwarded DLR via the callback DLR URL specified for each VAS.

The possible values for the message (sub)statuses can be found in the following table: