Subscribing to an OCS product

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


This guide shows you how to:

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

Endpoints

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

Transatel APIsURL
Authenticationhttps://api.transatel.com/authentication/api
OCS Cataloghttps://api.transatel.com/ocs/catalog/api
OCS Subscriptionshttps://api.transatel.com/ocs/subscriptions/api
OCS Inventoryhttps://api.transatel.com/ocs/inventory/api
Webhookshttps://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 this 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 that, 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 access_token previously retrieved
  • cos: M2MA_MWC_COS is the name of the COS
  • productId: MWC_RBRP_EUROPE_3GB is the ID of the product

In case of success, the response returned will be as follows:

HTTP/1.1 200 OK
{
"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.

3. Subscribe to product activation events (optional)

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\",
\"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 access_token previously retrieved
  • 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

In case of success, the response returned will be as follows:

HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "257728ad-01ed-447d-b923-062604926f95",
"mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
"status": "active",
"targetUrl": "https://example.com/events",
"events": [
{
"eventType": "OCS/PRODUCT/ACTIVATED",
"description": "A subscription to a product has been activated",
"domain": "OCS",
"category": "products",
"_links": {
"doc": {
"href": "https://api.transatel.com/ocs/events/docs/index.html#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.

4. Subscribe to the product

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

To do that, 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 access_token previously retrieved.
  • 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.

In case of success, the response returned will be as follows:

HTTP/1.1 201 Created
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 bellow:

{
"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 that, 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 access_token previously retrieved
  • msisdn: The mobile phone number of the subscriber
  • statuses: a filter allowing to only get active subscription here in this example

In case of success, the response returned will be as follows:

HTTP/1.1 200 OK
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: