MSISDN Forwarding Finland

From txtNation Wiki
Jump to: navigation, search

MSISDN Forwarding is a process that enables you to capture a phone number (the MSISDN) for billing the end user via an approved flow between the mobile networks (the MNOs), txtNation’s platform, and your server.

Now available in Finland for the first time, MSISDN Forwarding enables simpler premium rate services via txtNation's APIs, targeting 4.8 million mobile subscribers.

Please note that each of the MNOs in Finland implement MSISDN Forwarding in quite different ways, so you will need to ensure you take into account the differences. Our APIs will help you to integrate both kinds of implementation.

Sonera is the MNO with the largest market share in Finland. In the Sonera payment flow, we receive the MSISDN through header enrichment, which adds relevant information to the HTTP communications from Sonera.

The MSISDN is passed to your server via similar header enrichment, but we must register your receiving URL on your behalf so that you can receive this communication from Sonera.

Together, Elisa and Saunalahati control 37% of the Finnish mobile market. Elisa acquired Saunalahati in 2005. Saunalahati is an MVNO, or virtual operator, which has its own branding but is powered by the Elisa mobile network, which means the approach to these MNOs is the same.

To use Elisa/Saunalahati MSISDN Forwarding, you will need to call our Retrieval API to request the MSISDN. Unlike Sonera, you cannot receive the MSISDN directly via Elisa/Saunalahati header enrichment.

Once you have the MSISDN, either through an API call or header enrichment, you can use it to complete the charge against the end user’s phone bill.


Contents


Sonera

In order to get MSISDN forwarding enabled you will need to contact your account manager who can make the necessary arrangements with Sonera.

Once in place you should use our MSISDN decryption API to retrieve your MSISDNs.

Charging an end user on this network can be made possible by using our Sonera Direct Operator Billing API.

Elisa and Saunalahti

Elisa and Saunalahti use a transaction ID to enable direct operator billing instead of MSISDN forwarding. This means that the MSISDN is only available to you once a successful charge is made to the end user. In order to get a valid transaction ID there are three main actions: creating a session, redirecting the end user and retrieving the transaction ID.

For more details on how to charge an end user on this network, see our Elisa Direct Operator Billing API.


Transaction flow

Elisa Finland MSISDN Forwarding

Usage

Creating a session

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

   http://client.txtnation.com/finland/elisa_session.php.

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 My.txtnation.com.
return_url http://my.server.com/payment The URL to which the end user will be sent once the transaction ID is obtained n/a

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

   {
       "status": "ok",
       "ref_id": "55cdbc9279828",
       "redirect_url": "http://example.com"
   }

The ref_id returned from this request is your session ID. We use this to ensure that the result of the transaction ID generation is available to you at the end of the process. If the request is unsuccessful you will receive status: "error" in the response. An example of this is shown below:

   {
       "status": "error",
       "error_code": 1,
       "error_message": "Missing parameter: cc"
   }

Including the HTTP response headers, the full response may look like this:

HTTP/1.1 400 Bad Request
X-Served-By: Eos.txtnation.UK
Content-type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: Fri, 14 Aug 2015 14:43:49 GMT
Server: txtNation HTTP Server

{"status":"error","error_code":1,"error_message":"Missing parameter: cc"}

A full list of error codes are displayed below for your reference:

Error code HTTP code Description
1 400 There was a missing required parameter in the request. Further details about which parameter will be supplied in the error message.
2 400 One or more of the parameters sent was in an unexpected format, for example, ekey was not 32 characters in length.
3 403 Could not authenticate the company and ekey values you sent.
4 500 There was an internal error. If the problem persists please contact txtNation Support.

Redirecting the end user

Now that we have a ref_id for our session you can use this to redirect the end user to Elisa/Saunalahti so that they can generate a transaction ID. This is achieved by issuing an HTTP 302 redirect to:

   http://client.txtnation.com/finland/elisa_redirect.php?ref_id=XXXXXXXXXXXXXX.

Please note that you must pass your ref_id otherwise we will be unable to return the transaction ID of the end user at the end of the process.

Once the transaction ID has been generated, the end user will be redirected back to the return_url you provided during the initial call to elisa_session.

Retrieving the transaction ID

Once the user has returned to your return_url, you can call the retrieval API to obtain the transaction ID. The API is hosted at:

   http://client.txtnation.com/finland/elisa_get_transaction_id.php

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 My.txtnation.com.
ref_id 5243bc6ade5eedcdee The session ID returned during elisa_session n/a
ip 86.214.255.123 The IP address of the end user who is accessing your page n/a

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

   {
       "status": "ok",
       "ref_id": "55cdbc9279828",
       "transaction_id": "154289130250073169514852",
       "ip": "86.214.255.123",
   }

If the request is unsuccessful you will receive status: "error" in the response. An example of this is shown below:

   {
       "status": "error",
       "error_code": 1,
       "error_message": "Missing parameter: cc"
   }

Including the HTTP response headers, the full response may look like this:

HTTP/1.1 400 Bad Request
X-Served-By: Eos.txtnation.UK
Content-type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: Fri, 14 Aug 2015 14:48:34 GMT
Server: txtNation HTTP Server

{"status":"error","error_code":1,"error_message":"Missing parameter: cc"}

A full list of error codes are displayed below for your reference:

Error code HTTP code Description
1 400 There was a missing required parameter in the request. Further details about which parameter will be supplied in the error message.
2 400 One or more of the parameters sent was in an unexpected format, for example, ekey was not 32 characters in length.
3 403 Could not authenticate the company and ekey values you sent.
4 503 There was an internal error. If the problem persists please contact txtNation Support.
5 400 Could not find the transaction_id in our records.
6 400 No transaction ID was returned by Elisa/Saunalahti.

DNA

DNA is similar to Elisa/Saunalahti in that there are three main steps to take: creating a session, redirect the end user and retrieving the MSISDN. The big difference, however, is the method you need to use to redirect the end user. It is necessary to have the end user visit the URL directly rather than perform an HTTP 302. The latter method will not work on this network.

Charging an end user on this network can be made possible by using our DNA Direct Operator Billing API.

Transaction flow

DNA Finland MSISDN Forwarding

Usage

Create a session

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

   http://client.txtnation.com/finland/dna_session.php.

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 My.txtnation.com.
category 3 The type of content that is being accessed by the end user 1 = General services, 2 = Consulting and ordering services, 3 = Entertainment services, 4 = Adult services
return_url http://my.server.com/payment The URL to which the end user will be sent once the MSISDN is obtained n/a

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

   {
       "status": "ok",
       "ref_id": "55cdbc9279828"
   }

The ref_id returned from this request is your session ID. We use this to ensure that the result of the MSISDN discovery is available to you at the end of the process. If the request is unsuccessful you will receive status: "error" in the response. An example of this is shown below:

   {
       "status": "error",
       "error_code": 1,
       "error_message": "Missing parameter: cc"
   }

Including the HTTP response headers, the full response may look like this:

HTTP/1.1 400 Bad Request
X-Served-By: Eos.txtnation.UK
Content-type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: Fri, 03 Jun 2016 14:43:34 GMT
Server: txtNation HTTP Server

{"status":"error","error_code":1,"error_message":"Missing parameter: cc"}

A full list of error codes are displayed below for your reference:

Error code HTTP code Description
1 400 There was a missing required parameter in the request. Further details about which parameter will be supplied in the error message.
2 400 One or more of the parameters sent was in an unexpected format, for example, ekey was not 32 characters in length.
3 403 Could not authenticate the company and ekey values you sent.
4 500 There was an internal error. If the problem persists please contact txtNation Support.

Redirect the user

Unlike Elisa/Saunalahti you must make the end user visit the http://client.txtnation.com/finland/dna_redirect.php?ref_id=55cdbc9279828 URL, using the ref_id returned to you after the first API call to dna_session. HTTP 302 redirects do not work on DNA.

Once the user has visited this URL, and the MSISDN has been discovered, the end user will be redirected back to the return_url you provided during the initial call to dna_session.

Requesting the MSISDN

Once the user has returned to your return_url, you can call the retrieval API to obtain the MSISDN. The API is hosted at:

   http://client.txtnation.com/finland/dna_get_msisdn.php

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 My.txtnation.com.
ref_id 5243bc6ade5eedcdee The session ID returned during dna_session n/a
ip 86.214.255.123 The IP address of the end user who is accessing your page n/a

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

   {
       "status": "ok",
       "ref_id": "55cdbc9279828",
       "msisdn": "358468253836",
       "transaction_id": "I6543234567",
       "ip": "86.214.255.123",
   }

If the request is unsuccessful you will receive status: "error" in the response. An example of this is shown below:

   {
       "status": "error",
       "error_code": 1,
       "error_message": "Missing parameter: cc"
   }

Including the HTTP response headers, the full response may look like this:

HTTP/1.1 400 Bad Request
X-Served-By: Eos.txtnation.UK
Content-type: application/json; charset=utf-8
Transfer-Encoding: chunked
Date: Fri, 03 Jun 2016 14:48:34 GMT
Server: txtNation HTTP Server

{"status":"error","error_code":1,"error_message":"Missing parameter: cc"}

A full list of error codes are displayed below for your reference:

Error code HTTP code Description
1 400 There was a missing required parameter in the request. Further details about which parameter will be supplied in the error message.
2 400 One or more of the parameters sent was in an unexpected format, for example, ekey was not 32 characters in length.
3 403 Could not authenticate the company and ekey values you sent.
4 503 There was an internal error. If the problem persists please contact txtNation Support.
5 400 Could not find the transaction_id in our records.
6 400 No MSISDN was returned by DNA.
Personal tools