Netherlands Subscriptions

Netherlands Subscriptions

Please contact MessageCloud business development team, before attempting to follow this integration guide. Email:  business@messagecloud.com or +44 (0)330 1130 243 switchboard option 2

The instructions on this page, are an additional requirement to the main MessageCloud Gateway API here. This page outlines how to interact with our Netherlands subscription API. This API specifically handles WORAR (Web Opt-in Requiring a Reply), enabling the following consumer flow:

  1. Customer enters their number on your website
  2. You obtain the consumers mobile network provider by implementing either a selection option on the web page or by using HLR Lookup
  3. You request to start a subscription using this API
  4. You should send a free text message with instructions of how to complete their opt in using the MessageCloud Gateway API. The message must be in the Dutch language e.g. ‘Now text OK to 1234 for your subscription to ABCD ring tones. 3 items/wk, €6 /wk. Info: www.xyz.nl. Want to unsubscribe? Text STOP to 1234. Now text OK to 1234!’ ( Nu de tekst OK naar 1234 voor je abonnement op ABCD beltonen. 3 items / week, 6 € / week. Info: www.xyz.nl. Wilt afmelden? Tekst STOP naar 1234. Nu de tekst OK naar 1234! )
  5. Customer replies to the SMS with OK
  6. MessageCloud confirm subscription and send you the confirmation MO message via the Gateway
  7. You can then use Gateway to send billing messages to your customer to take payment according to your billing cycle
  8. You must send reminder messages and any other messages the regulations may require.

API Endpoint

Our API endpoint can accept HTTP POST or GET requests and will return JSON: http://client.txtnation.com/nl/index.php

The Parameters

The parameters you will need to send to our API endpoint through HTTP are:

Variable Contents Required Description
cc Company code  Yes This is your unique account name with us.
ekey Your ekey Yes This is the same as the ekey provided to you for accessing the Gateway API. If you do not have one, please contact MessageCloud Support.
msisdn MSISDN of the end user Yes This is the mobile number of your customer, e.g. 79683000999
network One of: KPN, TELE2, VODAFONE, TELLFORT, TMOBILE Yes The mobile network of the MSISDN
subid Subscription ID of service (to be provided by MEssageCloud on application) Yes The subid is your Netherlands subscription Id. This will be provided to you upon approval of your service.
action One of:  pending | start | stop Yes The action to take. Start will attempt to begin a subscription; stop will opt the end user out of their existing subscription.
price For example:  3.00 Yes This is the amount the end user will be charged in Euros for every charge in the subscription.
currency This will always be  EUR for Netherlands Yes The currency the network will bill in, e.g. EUR, USD, GBP.
shortcode The shortcode on which the service is hosted Yes This is the shortcode for your service.

Set a Subscription to Pending

An example of an HTTP request that will notify the networks you wish to set up a subscription for this MSISDN. 
http://client.txtnation.com/nl/index.php?cc=txtNationAccountName&ekey=fd1b05c1fcbe06caXXXf1a2c133e3368&msisdn=79683000999&network=VODAFONE&subid=15164325185&action=pending&price=3.00&currency=eur&shortcode=000000

Start a Subscription

An example of an HTTP request that will start a subscription. 
http://client.txtnation.com/nl/index.php?cc=txtNationAccountName&ekey=fd1b05c1fcbe06caXXXf1a2c133e3368&msisdn=79683000999&network=VODAFONE&subid=15164325185&action=start&price=3.00&currency=eur&shortcode=000000

Stop a Subscription

An example of an HTTP request that will stop a subscription. Note that the parameters: price, currency and shortcode are not required to stop a subscription.

http://client.txtnation.com/nl/index.php?cc=txtNationAccountName&ekey=fd1b05c1fcbe06caXXXf1a2c133e3368&msisdn=79683000999&network=VODAFONE&subid=15164325185&action=stop

API Return Value

Once you have sent a start or stop request the API will return JSON in the format:

{ status: 0, status_text: "OK" }

If the action was not successful, another status number will be returned. A list of these other status's are provided below.

Status Codes

If you do not recieve status:0 then you will recieve one of the status's below. Your script should handle each of these status's or at least assume that if status:0 is not returned then the action has not worked or changed the MSISDN's subscription.

Code Description
-1 Unknown Error
1 Missing Parameter:
2 Empty Parameter:
3 Parameter in wrong format:
5 Could not contact network
6 Subscription request already pending
7 Authentication error
8 Internal error
9 Pending subscription not found
10 User already has a pending subscription
11 End user not part of an active subscription
12 Could not start a subscription
13 Unknown action
14 Could not opt out the end user
15 Could not find shortcode/tariff
16 Unknown network in network parameter

Receiving notifications

You will receive notifications in the same method to a normal  MessageCloud Gateway MO notifications. See the Gateway documentation for further details or an example below:
Variable Contents
action mpush_ir_message
id The unique message ID
number The originating telephone number (MSISDN)Full International form without leading zeros or + sign.
network The originating network
message The contents of the message this will be "OK {keyword assigned by MessageCloud}"
shortcode The incoming short code of the message (if available)
country The 2 digit ISO country code (e.g. UK, US, ES)
billing The network billing type (if available)

A full URL string example:

http://yourserver.com/?action=mpush_ir_message&id=12345&billing=MT&country=NL&number=79683000999&network=VODAFONE&shortcode=XXXX&message=OK+TXTEST