Strex Norway with One-click Subscriptions

Strex Norway with One-Click Subscriptions

This document has been written to help you integrate Strex – the mobile billing platform used in Norway – into your application.

Before you begin…

You will need to have a MessageCloud account to complete this process. If you have not yet signed up, please visit https://my.messagecloud.com/register to get your free API key. You will also need to speak to our team to register your service. You will need to provide the following information:

Your company name
The name of the service
The type of content that is being purchased; games, access, competitions, etc.
How the service will appear on the customer's bill
If the service should be age-restricted
A redirect URL to which the customer will be sent after completing or cancelling the payment.
The welcome message you want to send to customers
The frequency of the subscription charge; daily, weekly, monthly, etc

Once these details have been configured, we will provide you with a service ID that you must use when making API calls. This will help us to identify which service is being used.

Transaction Flow

The below flow chart details the API calls that should be made to achieve a one-click transaction.

The customer visits the merchant's website and chooses to subscribe to your service.
The merchant creates a new Strex one-click window.
MessageCloud provides the merchant with a URL to which the customer should be redirected.
The customer completes the Strex transaction.
The customer is redirected to the return URL provided to MessageCloud with an id and status parameter.
Merchant checks the status of the transaction if the status is success. If the transaction was cancelled, status will be cancelled.
If the transaction was completed successfully, the statusCode returned by the View Status API will be DELIVERED. Other possible error codes are provided in Status Codes, below.
According to the subscription interval, further charges can be made to the customer by calling the Send DOB method.
The customer can opt-out of the subscription by sending STOP [KEYWORD]. This will be forwarded to your Gateway URL in the form of an MO message. See Receiving a Message for more information.

Integration Details

The following API calls are used during the one-click subscription process.

New One-click Window API

Request

To generate a new Strex window, you should send an HTTP GET to https://client.txtnation.com/no/one-click/new with the following parameters:

Variable	Type	Contents
`campaign_name`	string	This is the same as the cc provided to you for accessing the MessageCloud Gateway API. If you do not have one, please contact MessageCloud Support.
`api_key`	string	This is the same as the ekey provided to you for accessing the MessageCloud Gateway API. If you do not have one, please contact MessageCloud Support.
`service_id`	string	This is the service ID provided to you upon the successful configuration of your Norway service.
`id`	string	(Optional) A custom ID parameter to use. We will send this ID to your redirect URL once the transaction is completed.

Response

The response to the API call will be formatted in JSON (Content-Type: application/json). It will contain the following properties:

Variable	Type	Contents
`requestId`	string	This is a unique request ID
`status`	boolean	The status of the API call. If the call was successful, `true` will be returned. If the call was not successful, `false` will be returned.
`code`	integer	The code will provide you with more information regarding why a transaction was not successful. See Error Codes for more information.
`message`	string	A human-friendly representation of the `code` property.
`data`	object	Contains data returned by the specific API call: `transaction_id` (string) This is the transaction ID for the window. `window_url` (string) This is the URL to which the customer should be redirected.

Example

> GET /no/one-click/new?campaign_name=puregaming&api_key=<api_key>&service_id=<service_id> HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 09 Sep 2021 14:28:44 GMT
< Content-Type: application/json
< Content-Length: 252
< Connection: keep-alive
< Server: nginx
<
{
    "requestId":"b91c5c08-60dd-4607-b900-54310ad1ea22",
    "status":true,
    "code":0,
    "message":"Success",
    "data":{
        "transactionId":"b91c5c08-60dd-4607-b900-54310ad1ea22",
        "windowUrl":"http://betal.strex.no/service?id=b91c5c08-60dd-4607-b900-54310ad1ea22"
    }
}

View Status API

Request

To view the status of your subscription transaction, you should send an HTTP GET to https://client.txtnation.com/no/status/view with the following parameters:

Variable	Type	Contents
`campaign_name`	string	This is your unique account name with us.
`api_key`	string	This is the same as the ekey provided to you for accessing the MessageCloud Gateway API. If you do not have one, please contact MessageCloud Support.
`service_id`	string	This is the service ID provided to you upon the successful configuration of your Norway service.
`transaction_id`	string	The transaction ID returned as part of the Generate One-click Window API response.

Response

The response to the API call will be formatted in JSON (Content-Type: application/json). It will contain the following properties:

Variable	Type	Contents
`requestId`	string	This is a unique request ID
`status`	boolean	The status of the API call. If the call was successful, `true` will be returned. If the call was not successful, `false` will be returned.
`code`	integer	The code will provide you with more information regarding why a transaction was not successful. See Error Codes for more information.
`message`	string	A human-friendly representation of the `code` property.
`data`	object	Contains data returned by the specific API call: `price` (integer) The price of the transaction `shortNumber` (integer) The shortcode on which the billing occurred. `recipient` (integer) The customer's mobile phone number. `transactionId` (string) Confirmation of the transaction ID `statusCode` (string) A string that represents the status of the billing. See the Status Codes section, below, for more information. `detailedStatusCode` (string) Extra details of the status of the transaction, if available. `created` (datetime) The time when the transaction was started. `lastModified` (datetime) The time at which the transaction was last updated.

Example

> GET /no/status/view?campaign_name=puregaming&api_key=<api_key>&service_id=<service_id>&transaction_id=<transaction_id> HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 09 Sep 2021 14:28:44 GMT
< Content-Type: application/json
< Content-Length: 252
< Connection: keep-alive
< Server: nginx
<
{
    "requestId": "975bf918-09bb-46de-bb6b-a5ed5eba8a36",
    "status": true,
    "code": 0,
    "message": "Success",
    "data": {
        "price": 1,
        "shortNumber": "2172",
        "recipient": "4798888888",
        "transactionId": "b91c5c08-60dd-4607-b900-54310ad1ea22",
        "statusCode": "DELIVERED",
        "detailedStatusCode": "Delivered",
        "created": "2021-09-09T08:46:40+00:00",
        "lastModified": "2021-09-09T08:47:23+00:00"
    }
}

Send DOB API

Request

To generate a new Strex window, you should send an HTTP GET to https://client.txtnation.com/no/dob/send with the following parameters:

Variable	Type	Contents
`campaign_name`	string	This is your unique account name with us.
`api_key`	string	This is the same as the ekey provided to you for accessing the MessageCloud Gateway API. If you do not have one, please contact MessageCloud Support.
`service_id`	string	This is the service ID provided to you upon the successful configuration of your Norway service.
`tariff`	integer	This is the tariff of the transaction, in NOK.
`shortcode`	integer	This is the shortcode on which the billing will be done.
`to`	string	This is the MSISDN of the customer, returned during the View Status API call.

Response

The response to the API call will be formatted in JSON (Content-Type: application/json). It will contain the following properties:

Variable	Type	Contents
`requestId`	String	This is a unique request ID
`status`	Boolean	The status of the API call. If the call was successful, `true` will be returned. If the call was not successful, `false` will be returned.
`code`	Integer	The code will provide you with more information regarding why a transaction was not successful. See Error Codes for more information.
`message`	String	A human-friendly representation of the `code` property.
`data`	Object	Contains data returned by the specific API call: `price` (integer) The price of the transaction `shortNumber` (integer) The shortcode on which the billing occurred. `recipient` (integer) The customer's mobile phone number. `transactionId` (string) Confirmation of the transaction ID `statusCode` (string) A string that represents the status of the billing. See the Status Codes section, below, for more information. `detailedStatusCode` (string) Extra details of the status of the transaction, if available. `created` (datetime) The time when the transaction was started. `lastModified` (datetime) The time at which the transaction was last updated.

Example

> GET /no/dob/send?campaign_name=puregaming&api_key=<api_key>&service_id=<service_id>&tariff=<tariff>&shortcode=<shortcode>&to=<to> HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Thu, 09 Sep 2021 14:28:44 GMT
< Content-Type: application/json
< Content-Length: 252
< Connection: keep-alive
< Server: nginx
<
{
    "requestId": "975bf918-09bb-46de-bb6b-a5ed5eba8a36",
    "status": true,
    "code": 0,
    "message": "Success",
    "data": {
        "price": 1,
        "shortNumber": "2172",
        "recipient": "4798888888",
        "transactionId": "b91c5c08-60dd-4607-b900-54310ad1ea22",
        "statusCode": "DELIVERED",
        "detailedStatusCode": "Delivered",
        "created": "2021-09-09T08:46:40+00:00",
        "lastModified": "2021-09-09T08:47:23+00:00"
    }
}

Status Codes

The table below details the possible status codes you could receive after using the View Status API or Send DOB API. They are broadly similar to the delivery report statuses used in Gateway.

Code	Explanation
`DELIVERED`	The transaction was completed successfully and billing has been performed, where requested.
`REJECTED`	The subscriber was barred from completing the transaction.
`VALIDITY_EXPIRED`	The request to charge the customer has expired.
`INVALID_MSISDN`	The customer's MSISDN was not valid or they are not registered with Strex.
`NO_CREDIT`	The customer did not have sufficient credit to complete the transaction.
`FAILED`	The request to charge the customer failed.
`UNKNOWN`	The status of the transaction is unknown.
`ACKNOWLEDGED`	The final status for the message has not yet been received.

Error Codes

The table below details the possible error codes you could receive. Error codes will always be explained in the message property.

Code	Explanation
`1`	The request was missing required parameters or the parameters you sent contained data in an invalid format. See the `message` property for more details.
`2`	Authentication was not successful. Check your `campaign_name` and `api_key` values and try again.
`3`	There was an error when communicating with Strex.
`4`	The `shortcode` or `tariff` is not available.