Subscribing to an OCS product

Discover how you can use OCS APIs to subscribe to an OCS product

This guide shows you how to:

authenticate yourself and retrieve an access token
search for a product in your catalog and check your subscriber eligibility
create a webhook and subscribe to product activation events
subscribe to this product on your subscriber
receive the product activation event
check this subscriber inventory

Endpoints

Below are all APIs url that you will need for this guide:

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
OCS Catalog	https://api.transatel.com/ocs/catalog/api
OCS Subscriptions	https://api.transatel.com/ocs/subscriptions/api
OCS Inventory	https://api.transatel.com/ocs/inventory/api
Webhooks	https://api.transatel.com/webhooks/api

All Transatel APIs are available through our unique API gateway https://api.transatel.com

1. API Authentication

First thing first, let's get your access token by following the getting started guide!

2. Check product eligibility (optional)

Now that you are authenticated, and you have an access token, let's use it to check the eligibility of your subscriber to subscribe to a product from your catalog (MWC_RBRP_EUROPE_3GB in this example).
To do so, we will use the OCS Catalog API.

The below example shows how to check your eligibility to a given product:

curl --location --request GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA'\
'https://api.transatel.com/ocs/catalog/api/cos/M2MA_MWC_COS/products/MWC_RBRP_EUROPE_3GB'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
cos: M2MA_MWC_COS is the name of the COS
productId: MWC_RBRP_EUROPE_3GB is the ID of the product

If successful, the response returned will be as follows:

HTTP/1.1 200 OK
X-TSL-Request-Id: c251d1de-aca5-4cdb-9154-d136f87b8cbe
{
  "cos": "M2MA_MWC_COS",
  "currentLocale": "en-US",
  "products": [
    {
      "display": {
        "priority": 0
      },
      "canSubscribe": {
        "allowed": true
      },
      "hasSubProducts": false,
      "inventoryActive": false,
      "availability": {
        "available": true,
        "startDate": "2021-04-19T13:30:00Z"
      },
      "productDefinition": {
        "productId": "MWC_RBRP_EUROPE_3GB",
        "productCategory": "Recurring",
        "validityPeriod": {
          "validityDurationUnit": "months",
          "validityDuration": 1
        },
        "countryList": [
          "DNK", "CHE", "IRL", "REU", "NLD", "SVK", "SVN", "LTU", "HRV", "PRT", "MLT", "GBR", "CYP", "AUT", "HUN", "SWE", "ISL", "ESP", "EST", "BEL", "LIE", "FIN", "IMN", "BGR", "POL", "LUX", "CZE", "NOR", "FRA", "DEU", "LVA", "AND", "ITA", "GGY", "GRC", "ROU", "JEY"
        ],
        "allowances": {
          "data": [
            {
              "resourceName": "DATA_BUNDLE_CONTINENT",
              "resourceUnit": "KB",
              "resourceValue": 3145728,
              "resourceDurationUnit": "months",
              "resourceDuration": 1
            }
          ]
        },
        "links": [
          {
            "rel": "product",
            "href": "/api/cos/M2MA_MWC_COS/products/MWC_RBRP_EUROPE_3GB"
          }
        ]
      }
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/api/cos/M2MA_MWC_COS/products"
    }
  ]
}

A successful response returns a HTTP/1.1 200 OK with the details of the product in your catalog.
To verify your subscriber eligibility to the product, you can check the canSubscribe object and its allowed flag.

According to your business need, you may need to receive events when products are activated on one of your subscribers. If so, you will need to create a webhook and subscribe to product activation event: OCS/PRODUCT/ACTIVATED.
Please check the webhooks integration guide to learn more about it.

To do a that, we will use the Webhooks API.

The below example shows how to create a webhook and subscribe to product activation events:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{
      \"mvnoRef\": \"M2MA_WW_TSL_MWC_INTERNAL\",
      \"status\": \"active\",
      \"targetUrl\": \"https://example.com/events\",
      \"email\": \"support@company.com\",
      \"events\": [
        \"OCS/PRODUCT/ACTIVATED\"
      ]
    }" \
    'https://api.transatel.com/webhooks/api/webhooks'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
mvnoRef: Customer account identifier provided by Transatel at setup
targetUrl: The HTTPS url to which events will be posted
events: An array with the events you want to subscribe to, here the product activation event

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: 0fdbd7d7-6243-4364-bef0-5c3b012364cf
Content-Type: application/json
{
  "id": "257728ad-01ed-447d-b923-062604926f95",
  "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
  "status": "active",
  "targetUrl": "https://example.com/events",
  "email": "support@company.com",
  "events": [
    {
      "eventType": "OCS/PRODUCT/ACTIVATED",
      "description": "A subscription to a product has been activated",
      "domain": "OCS",
      "category": "products",
      "_links": {
        "doc": {
          "href": "https://developers.transatel.com/api/ocs/events/#tag/Products/paths/OCS~1PRODUCT~1ACTIVATED/post"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.transatel.com/webhooks/api/webhooks/257728ad-01ed-447d-b923-062604926f95"
    }
  }
}

A successful response returns a HTTP/1.1 201 Created with the details of the webhook.

Now that we are ready to proceed, let's subscribe to MWC_RBRP_EUROPE_3GB product on one of your subscriber!

To do so, we will use the OCS Subscriptions API.
Several payment providers are supported, and the one to use will depend on the Transatel Business Offer you are using. This information will be communicated during your account creation process.

The below example shows how to subscribe to the MWC_RBRP_EUROPE_3GB product with the customer payment provider:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{ 
      \"bind\": {
        \"msisdn\": \"882470400271060\"
      },
      \"product\": {
        \"productId\": \"MWC_RBRP_EUROPE_3GB\"
      },
      \"payment\": {
        \"provider\": \"customer\"
      },
      \"source\": \"api\",
      \"orderType\": \"subscribe\",
      \"mvnoRef\": \"M2MA_WW_TSL_MWC_INTERNAL\"
    }" \
    'https://api.transatel.com/ocs/subscriptions/api/orders/products'

Highlighted above are the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token.
msisdn: The mobile phone number of the subscriber.
productId: The identifier of the product to subscribe. (The list of products available for your subscriber will be communicated upon setup of your Transatel account.)
provider: The payment providers matching your Transatel Business offer.
orderType: The type of order you want to place, here subscribe for a subscription.
mvnoRef: Your Transatel account identifier.

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: 80953b63-ba25-40f0-b136-1932b4103c31
Content-Type: application/json
{
  "id": "9c3aa73e2eaee4b8",
  "status": "done",
  "submissionDate": "2021-04-19T13:30:00Z",
  "bind": {
    "msisdn": "882470400271060"
  },
  "product": {
    "productId": "MWC_RBRP_EUROPE_3GB"
  },
  "payment": {
    "provider": "customer"
  },
  "source": "api",
  "subscriptionId": "d138fd27-97e9-4e45-ac51-8c4ad7563f85",
  "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your order was successfully processed and the identifier of the susbcription will be returned as subscriptionId.

5. Receive product activation events (optional)

If you subscribed to product activation events in step 3, then you will receive a OCS/PRODUCT/ACTIVATED event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "OCS/PRODUCT/ACTIVATED",
    "eventDate": "2021-04-19T13:30:00Z"
  },
  "body": {
    "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
    "cos": "M2MA_MWC_COS",
    "msisdn": "882470400271060",
    "iccid": "8988247000013920591",
    "productSubscription": {
      "subscriptionId": "d138fd27-97e9-4e45-ac51-8c4ad7563f85",
      "subscriptionDate": "2021-04-19T13:30:00Z",
      "activationDate": "2021-04-19T13:30:00Z",
      "productDefinition": {
        "productId": "MWC_RBRP_EUROPE_3GB",
        "productCategory": "Recurring",
        "validityPeriod": {
          "validityDurationUnit": "months",
          "validityDuration": 1
        }
      },
      "recurrence": {
        "isRecurring": true,
        "isLastRenewal": false,
        "occurrenceCount": 1,
        "nextRenewalDate": "2021-05-19T13:30:00Z"
      }
    }
  }
}

You will be able to identify this product activation event thanks to the eventType and subscriptionId fields.

To learn more about the definition of this event, please check the event specification

6. Retrieve your subscriber inventory (optional)

Now that we subscribed to this product, let's check the subscriber's inventory and verify that the subscription for this product has been correctly added.

To do so, we will use the OCS Inventory API.

The below example shows how to retrieve the active subscriptions of a subscriber:

curl --location --request GET \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    'https://api.transatel.com/ocs/inventory/api/subscriptions/products?msisdn=882470400271060&statuses=active'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber
statuses: a filter allowing to only get active subscription here in this example

If successful, the response returned will be as follows:

HTTP/1.1 200 OK
X-TSL-Request-Id: cfeb76a2-3eba-42c3-9d06-f252edff8bef
Content-Type: application/json
{
  "productSubscriptions": [
    {
      "subscriptionId": "d138fd27-97e9-4e45-ac51-8c4ad7563f85",
      "status": "active",
      "subscriptionDate": "2021-04-19T13:30:00Z",
      "activationDate": "2021-04-19T13:30:00Z",
      "bind": {
        "msisdn": "882470400271060"
      },
      "paymentMethod": {
        "provider": "customer"
      },
      "hasSubProducts": true,
      "productDefinition": {
        "productId": "MWC_RBRP_EUROPE_3GB",
        "productCategory": "Recurring",
        "validityPeriod": {
          "validityDurationUnit": "months",
          "validityDuration": 1
        },
        "allowances": {
          "data": [
            {
              "resourceName": "DATA_BUNDLE_CONTINENT",
              "resourceUnit": "KB",
              "resourceValue": 3145728,
              "resourceDurationUnit": "months",
              "resourceDuration": 1
            }
          ]
        }
      },
      "balances": {
        "data": [
          {
            "resourceName": "DATA_BUNDLE_CONTINENT",
            "resourceUnit": "KB",
            "resourceValue": 3145728,
            "resourceStartDate": "2021-04-19T13:30:00Z",
            "resourceEndDate": "2021-05-19T13:30:00Z"
          }
        ]
      },
      "recurrence": {
        "isRecurring": true,
        "isLastRenewal": false,
        "occurrenceCount": 1,
        "nextRenewalDate": "2021-05-19T13:30:00Z"
      }
    }
  ]
}

A successful response returns a HTTP/1.1 200 OK, with the details of the active subscriptions.

What to do next?

Learn more about our OCS APIs by checking their overview & API references:

Subscribing to an OCS product

Endpoints

1. API Authentication

2. Check product eligibility (optional)

3. Subscribe to product activation events (optional)

4. Subscribe to the product

5. Receive product activation events (optional)

6. Retrieve your subscriber inventory (optional)

What to do next?