Russia Subscriptions

From txtNation Wiki
Jump to: navigation, search

Prior approval is required in order to use this DOB / DCB service. A service description must be submitted for approval, and upon successful approval, you will be provided specific supplemental details by txtNation Networks coordinatior as detailed below. (This process is likely to take a number of days)

Preamble / Contents

This page details how to connect to our Russia subscriptions API. Like some other countries, Russia uses a web opt in to verify end user subscriptions.

Contents


Transaction Flow

The transaction flow should be as listed below:

  1. Request a double opt in URL from our window generation API ( http://client.txtnation.com/russia/window.php )
  2. Redirect the end user to the provided URL ( see Response below )
  3. End user (consumer) confirms or denies subscription service
  4. txtNation notify you of the transaction status ( see Callback below)
  5. End user redirected back to your return URL ( see Redirect below) (txtNation Networks coordinatior advises initial billing has been made to consumer at this point.)
  6. Carry out ongoing subscription billing and consumer notifications as per txtNation Gateway API ( see Subscription Billing below) and the (https://txtnation.zendesk.com/entries/183596-Russia-Premium-SMS-Regulations Russia regulations / Spend Limits / Message Flow)

Window Generation

Request

In order to generate a window, you should send an HTTP GET or POST to the following URL:

   http://client.txtnation.com/russia/window.php

An example HTTP POST

   http://client.txtnation.com/russia/window.php?company={txtNation_Account_Name}&password=fd1b05c1fcbe06caXXXf1a2c133e3368&service_id={provided_by_txtNation_Networks_Coordinator}&return_url=gateway.txtnation.com&callback_url=http://your_url.com/logpostdata.php&landing_page_url=http://your_url.com/landing_page.php&user_ip=127.0.0.1&msisdn=79683000999&network={provided_by_txtNation_Networks_Coordinator}

Example HTTP POST variables required.

  http://client.txtnation.com/russia/window.php?
  company={txtNation Account Name}
  &password=fd1b05c1fcbe06caXXXf1a2c133e3368
  &service_id={provided by txtNation Networks Coordinator}
  &return_url=gateway.txtnation.com
  &callback_url=http://your_url.com/logpostdata.php
  &landing_page_url=http://your_url.com/landing_page.php
  &user_ip=127.0.0.1
  &msisdn=79683000999
  &network={provided by txtNation Networks Coordinator}

The following parameters are required when calling this API:

Variable Description
company Your company code with txtNation.
password The password you use to access txtNation services, e.g. Control Panel, MD5 encoded.
service_id The ID of your service. This will be provided by txtNation on application. (txtNation Networks coordinatior to provide.)
return_url The page the end user should be sent to after the opt in has taken place,
callback_url The URL to which txtNation should post the transaction status
landing_page_url The page on which the end user found the service
user_ip The IP address of the end user
msisdn The MSISDN of the end user
network The network of the end user. These values will be provided on application. (txtNation Networks coordinatior to provide.)

Response

If your request was successful you will see a JSON object in the document response body.

   { "token": "12345", "status": "0", "redirect_url": "http://example.com/" }

You will need to store the token of the result so that you can link subsequent transactions and callbacks.


If the result was not successful you will be given a JSON object like the following:

   { "error": 201, "message": "Authentication error" }

The following other error results could be returned:

Error code Description
101 Missing GET/POST parameter in the request
102 A parameter in the request was in an incorrect format
201 The authentication details you supplied (company/password) were not correct. If you continue to see this error you should contact txtNation.
801, 802, 810 Invalid parameter found when generating a window
803 The service ID was not valid
805 Return URL was not formatted correctly
806 The URL for your landing page was not formatted correctly
807 End user IP was not formatted correctly
815 Not a valid network for the subscription service
821 This end user or network did not support the subscription service
823 The MSISDN does not exist
824 The network returned an error
825 The end user was already subscribed to this service ID
903 The service is temporarily unavailable.
901, 902, 999 Other error. Please contact txtNation if you continue to see this error.


Callback

When the end user has confirmed or rejected the subscription, txtNation will send your supplied callback URL an HTTP POST with the following details:

Variable Description
token The ID of the transaction. This is the value that we returned in the window generation stage.
status Either SUBSCRIBED or REJECTED depending on the end user action
msisdn The MSISDN of the end user


We recommend that you store these details so that when the end user is sent to your return URL you can display a page according to their subscription status.

Redirect URL

Once the double opt in process is completed the end user will be redirected to your return URL (provided in the original request). We will append two parameters onto the end of the request so that you can find the transaction:

   http://your_return_url/?status=0&token=12345

Subscription Billing

You should use the txtNation Gateway API to perform the billing for your subscription.

Personal tools