Warning

Experimental functionality of the operator’s Personal account inside the TV application. The visual interface and API can be changed.

Billing API

Description

Serves for the implementation of the operator’s personal account inside the client applications, and it allows the following:

Read the current terms of service

Change the password to access the Account

Switch tariff plan

Subscribe to a tariff plan

Cancel the plan

Now Billing API support is only available in mobile applications.

Changing the subscriptions may be limited. Below you may find the information how actions on tariff plans are limited.

Billing API describes the interface of interaction with billing operator. This means that the implementation of all actions should be handled by billing through the existing integration via provider-api.

Activation of Billing API

To enable the Billing API you need to:

Add billing: true to the /opt/tvip-tms/gateway/gateway-tvip-tms-tvip-tms-tvip-api/application-prod.yml file;

...
 features:
   billing: true
...

In the TMS Web interface, in the Provider settings, enable the Resolve Billing option, add a Url and token to access billing;
Restart the service systemctl restart gateway-tvip-tms-tvip-api.

Header variables available when requesting from TMS to operator billing

X-TMS-ACCOUNT-ID - The ID of the account in the TMS whose request is being processed.

X-TMS-PROVIDER-ID - The ID of the provider (an integer) whose request is being processed.

Accept-Language - Locale of the client application.

X-AUTH-TOKEN - Signature defined in the TMS provider settings. It is formed as follows:

private function createSign(Request $request):string{
  $token = $request->getPathInfo();
  $token = $token.$_ENV['TMS_TOKEN'];
  if($request->headers->has('Content-Length') && $request->headers->get('Content-Length')>0){
     $token = $request->headers->get('Content-Length');
  }
  return md5($token);

General rules

Fields containing the date and time are transmitted in the format “Y-m-dTH:i:sO”, for example: 2023-05-03T10:55:11+0000
Responses to billing requests should contain correct HTTP codes, for example, 200 for successful requests, 500 for errors on the service side.
All requests are transmitted to TMS, and it will proxy them as is, just adding headers X-TMS-ACCOUNT-ID, X-TMS-PROVIDER-ID, X-AUTH-TOKEN.
All business logic and operations on the billing and TMS side is entrusted to the billing, the API provides subscriber control interface only.

Processed URLs that should be implemented by operator billing

GET /api/cabinet - user account

POST /api/switch - change tariff plan

POST /api/subscribe - subscribe to a new subscription plan

POST /api/unsubscribe - unsubscribe

GET /api/tariff/{id} - detailed description of the tariff

POST /api/cabinet/password - Account password change

GET /api/cabinet

{
  "contacts":"string"
  "account":{
    "id": 1,
    "fullname":"John Doe",
    "balance": "10 $",
    "enabled": true,
    "account_credentials": "132379-2014-01-01"
  },
  "services":[
    {
      "type": "iptv",
      "title": "Interactive TV",
      "description" "TV with timeshift and catch-up"
      "groups":[
          {
            "title": "Basic subscription",
            "type": "SINGLE",
            "offers":[
              {
                "from": "2023-06-01T00:00:00+0300",
                "tariff":{
                  "id" 2,
                  "name": "Standard channels",
                  "cost": "2 $",
                  "period": "monthly",
                  "description": "",
                  "channel_count": 150
                }
              }
            ],
            "subscription":{
              "id": 19589,
              "from": "2022-11-03T00:00:00+0300",
              "to": null,
              "cancel_date": null,
              "tariff":{
                "id": 1,
                "name": "Basic channels",
                "cost": "1 $",
                "period": "monthly",
                "description": "",
                "channel_count": 100
              }
            },
            "archiveSubscriptions":[],
            "futureSubscriptions":[],
          },
          {
            "title": "Premium packages",
            "type": "MULTI",
            "offers":[],
            "subscriptions":[]
          }
      ]
    }
  ]
}

The object cabinet contains the following fields:

cabinet.contacts:

The line, for example, there could be a support email address or phone number.

cabinet.account:

The account object contains information about the subscriber: name of the contract holder, contract details, current balance, the flag enabled indicates whether the subscriber’s services are enabled.

cabinet.services:

The array of services that can be managed through Personal Area in the application is currently supported only by type iptv.

service.groups:

The service contains groups (groups), which in turn can have type:

SINGLE - for plans that can replace each other and cannot be active simultaneously, e.g., ‘Basic Tariff’ and ‘Advanced Tariff’.
MULTI - for plans that may be active simultaneously, usually they include movie or sports channels.

group.offers:

Common for both types of groups, the field contains offers for subscribing or switching (for SINGLE type) to tariff plans:

from - the date from which it is proposed to subscribe (change subscription)

tariff - the tariff to which the subscription is offered

group.subscription:

Specific field for SINGLE group type, can be null or shows the current subscription:

id - subscription identifier, it is used as an argument in unsubscribe and unsubscribe methods

from - start date of the subscription

to - end date of subscription, null - no end date defined

cancel_date - the date from which it is possible to end the subscription (unsubscribe), if set to null - it’s impossible to cancel a subscription through the LC.

tariff - description of the subscription plan

group.subscriptions:

Specific field for MULTI group type, array subscriptions, has the same structure as for SINGLE group

group.archiveSubscriptions:

Array of past subscriptions, specific to SINGLE groups

group.futureSubscriptions:

Array of scheduled subscription changes, allows you to cancel a scheduled subscription

tariff:

Tariff object, describes the properties of the tariff plan:

id - tariff ID, used in subscription methods

name - the name of the tariff plan.

cost - the cost of the tariff plan, it is a simple string, it is allowed to use the accepted notation for the region of service provision, for example, “20 EUR” or “$ 20”.

period - the billing period of the service, use the wording understandable to the subscriber, for example “per day”, “per year”.

description - a description of the tariff plan, describe the features or describe the benefits.

channel_count - an integer field, specify the number of channels in the tariff plan.

POST /api/switch

Server request model

{
  "subscription_id": 19589,
  "tariff_id": 2,
  "from": "2023-06-01T00:00:00+0300"
}

Change subscription method, used only for SINGLE groups, the application generates a request based on the selected offer:

subscription_id - identifier of the subscription to be changed

tariff_id - identifier of the tariff in the selected subscriber offer

from - the date of change of the tariff plan in the subscription, specified in the selected by the subscriber offer

Server response model

{
  "status": 200,
  "message": null,
  "subscription": {
      "id": 19589,
      "from": "2023-06-01T00:00:00+0300",
      "to": null,
      "cancel_date": null,
      "tariff":{
        "id" 2,
        "name": "Standard channels",
        "cost": "2 $",
        "period": "monthly",
        "description": "",
        "channel_count": 150
      }
  }
}

Response fields

status - response code 200 should be set in case of correct execution of the request, in other cases you should specify 500.

message - message to the subscriber, not used at the moment.

subscription - model of the generated subscription (group.subscription)

Note

At the moment only HTTP code is processed. HTTP response code should be 200 if the request is executed without errors. The HTTP response code should be 500 if the request is not executed.

POST /api/unsubscribe

Server request model

{
  "subscription_id": 100,
  "to": "2023-07-01T00:00:00+0300"
}

Unsubscribe is possible only if the field subscription.cancel_date is defined, in which case the client will have a button that will generate a request:

subscription_id - Subscription ID

to - end date of subscription

Server response model

{
  "status": 200,
  "message": null,
  "subscription": {
      "id": 100,
      "from": "2023-06-01T00:00:00+0300",
      "to": "2023-07-01T00:00:00+0300",
      "cancel_date": null,
      "tariff":{
        "id" 2,
        "name": "Standard channels",
        "cost": "2 $",
        "period": "monthly",
        "description": "",
        "channel_count": 150
      }
  }
}

Response fields:

status - response code 200 should be set in case of correct execution of the request, in other cases you should specify 500.

message - message to the subscriber, not used at the moment.

subscription - the modified subscription model (group.subscription)

Note

At the moment only HTTP code is processed. HTTP response code should be 200 if the request is executed without errors. The HTTP response code should be 500 if the request is not executed.

GET /api/tariff/{id}

Request for details of the tariff plan with the identifier {id}

Server response model

{
    "tariff": {
        "id": 10,
        "name": "Amedia Premium",
        "cost": "99 $",
        "period": "monthly",
        "description": "",
        "channel_count": 1
    },
    "channels": [
        {
            "name": "Amedia Premium HD",
            "logo_url": "https://example.com/logo.png",
            "description": "",
            "number": 322,
            "categories": [
                2,
                3
            ]
        }
    ],
    "categories": {
        "1": "News",
        "2": "Movies",
        "3": "HD Channels",
    }
}

Response fields:

tariff - the tariff model described above. channels - an array of channels included in the tariff plan. categories - a directory of categories.

POST /api/cabinet/password

Method of changing the password from the Subscriber’s account in TMS

Server request model

{
  "old_password": "0512f08120c4fef707bd5e2259c537d0"
  "password": "5f4dcc3b5aa765d61d8327deb882cf99"
}

Field Description:

old_password - the current password entered by the user.

password - the new password entered by the user.

Your backend, based on the data transmitted, should change the password or refuse to change the password

Server response model

{
  "status": 200,
  "message": null,
}

Field Description:

status - 200 in case of password change, 500 in other cases.

message - message to the subscriber, not used at the moment.

Note

At the moment only HTTP code is processed. HTTP response code should be 200 if the request is executed without errors. The HTTP response code should be 500 if the request is not executed.

Billing API

Description

Activation of Billing API

Header variables available when requesting from TMS to operator billing

General rules

Processed URLs that should be implemented by operator billing

GET /api/cabinet

POST /api/switch

POST /api/subscribe

POST /api/unsubscribe

GET /api/tariff/{id}

POST /api/cabinet/password