Telenor (all)

Telenor do not share MSISDNS but use ACRs (Authentication Context Class Reference) instead. As a result some Alacrity API calls expect ACRs or return ACRs.

An ACR is 48 characters. The first 30 characters of the ACR uniquely identify the customer. The remaining characters can vary. However, the full initial ACR returned in a subscription create call should be used in subsequent API calls.

An example ACR is "Telenor-TLN-MM:XXX9oirtpv0wrGsDXXXTHjTS5vKRXXXX".

For details of request and response parameters please consult the API Reference.

For Telenor Digi merchants must provide a support email or telephone number. This should be displayed in the welcome SMS and in your landing page.

Supported Flows

Telenor supports Checkout. The Checkout Flow allows a Merchant to charge or subscribe a customer with the Telenor/SLA hosted confirmation pages prompting the user for their MSISDN and/or PIN and final confirmation depending upon whether HE is available.

One Off Charge with Checkout

The checkout re-direct to SLA should look like:

http://checkout.sla-alacrity.com/purchase?merchant=partner:4e3f654ed86dbb113bb472be07630b3cb6ad0859& service=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0& correlator=123XYZ& price=450.0& redirect_url=http://test.com/api/callback/123?transaction_id=XXXXXXXX

The Correlator is a required field.

If successful, then control will re-direct back to you on your redirect_url:

http://test.com/api/callback/123?transaction_id=XXXXXXXX& status=success& token=TOKEN:22bcb1a2-6b16-4644-9425-c1XXXXXXXXXX

The charge API call can then be made using the Token provided:

POST
/v2.2/charge?msisdn=TOKEN:22bcb1a2-6b16-4644-9425-c1XXXXXXXXXX&campaign=
campaign:2e94ef85486fXXXXXXXXXXXXX&merchant=
partner:4e3f654ed86dbb113bb472XXXXXXXXXXXXXX&amount=450.0&currency=
MMK&language=en

The response from the charge call contains the ACR instead of a MSISDN:

{
   "success":{
      "type":"subscription",
      "uuid":"9de34c90-XX-XXX-XXXX-a30681fea696",
      "bill_id":"23a3f5XXXXX",
      "operator":"telenor-mm",
      "merchant":"partner:6a5a026c005fac63ffcXXXXXXXXb",
      "campaign":"campaign:2b00ed67ebb41df9fc9XXXXX7",
      "environment":"production",
      "msisdn":"telenor-TLN-MM:OGzwVFOpaQlpqkD0KXXXXXXXXXXXX",
      "currency":"MMK",
      "amount":"450.0",
      "mode":"API",
      "frequency":"weekly",
      "next_payment_timestamp":"2020-09-11 07:09:58 UTC",
      "transaction":{
         "status":"CHARGED",
         "bill_id":"23a3f5XXXXXXXX",
         "timestamp":"2020-09-04 07:09:58 UTC",
         "transaction_id":"83553333333"
      }
   }

Subscription creation with Checkout

The checkout re-direct to SLA should look like:

http://checkout.sla-alacrity.com/purchase?merchant=partner:4e3f654ed86dbb113bb472be07630b3cb6ad0859& service=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0& correlator=123XYZ& redirect_url=http://test.com/api/callback/123?transaction_id=XXXXXXXX

The Correlator is a required field.

If successful, then control will re-direct back to you on your redirect_url:

http://test.com/api/callback/123?transaction_id=XXXXXXXX& status=success& token=TOKEN:22bcb1a2-6b16-4644-9425-c1XXXXXXXXXX

The subscription create call will use the Token provided by Checkout:

POST
/v2.2/subscription/create?msisdn=
TOKEN:22bcb1a2-6b16-4644-9425-c1XXXXXXXXXX&
campaign=campaign:2e94ef85486fXXXXXXXXXXXXX&
merchant=partner:4e3f654ed86dbb113bb472XXXXXXXXXXXXXX&
template=subscription&language=en

The response from the subscription create call contains the ACR instead of a
MSISDN:

{
   "success":{
      "type":"subscription",
      "uuid":"9de34c90-XX-XXX-XXXX-a30681fea696",
      "bill_id":"23a3f5XXXXX",
      "operator":"telenor-mm",
      "merchant":"partner:6a5a026c005fac63ffcXXXXXXXXb",
      "campaign":"campaign:2b00ed67ebb41df9fc9XXXXX7",
      "environment":"production",
      "msisdn":"telenor-TLN-MM:OGzwVFOpaQlpqkD0KXXXXXXXXXXXX",
      "currency":"MMK",
      "amount":"450.0",
      "mode":"API",
      "frequency":"weekly",
      "next_payment_timestamp":"2020-09-11 07:09:58 UTC",
      "transaction":{
         "status":"CHARGED",
         "bill_id":"23a3f5XXXXXXXX",
         "timestamp":"2020-09-04 07:09:58 UTC",
         "transaction_id":"83553333333"
      }
   }

📘

Info

The above ACR should be used to manage the subscription going
forward and not a MSISDN.
An ACR is 48 characters. The first 30 characters of the ACR uniquely identify
the customer. The remaining characters can vary. However, the full initial ACR
returned in this subscription create call should be used in subsequent API
calls.

Telenor does not allow free trials

📘

Info

If you attempt to charge the same msisdn more than once for a weekly subscription, then you will get a CHARGE_EXCEEDS_LIMIT result code

"error": {
    "type": "subscription",
    "uuid": "3c55bd7b-8624-xxxx-xxxx-a39x8914220a",
    "bill_id": "xxxxx",
    "operator": "telenor-digi",
    "merchant": "partner:xxxxx",
    "campaign": "campaign:xxxxx",
    "environment": "production",
    "msisdn": "telenor-DIG-MY:xxxxxxxxxx",
    "currency": "MYR",
    "amount": "4.2",
    "mode": "API",
    "frequency": "weekly",
    "transaction": {
        "status": "LIMIT_EXCEEDED",
        "message": "Periodic charge threshold exceeded",
        "bill_id": "xxxxx",
        "timestamp": "2020-06-09 14:20:32 UTC",
        "transaction_id": "748xxxxxx"
      }
    }
}

Notifications

In notifications the ACR provided will contain the original 30 characters and a different 18-character ending.

Notifications shall reference an ACR but not a MSISDN regardless. details on notifications can be found in the HTTP section. Below is an example for a renewal notification:

"success" : {
   "type" : "subscription",
   "uuid" : "99b3bbed-b735-491f-a3c5-16f2XXXXXXXX",
   "bill_id" : "1d44caaf7XXXXXXXX",
   "operator" : "telenor-mm",
   "merchant" : "partner:4e3f654ed86dbb113bb472XXXXXXXXXXXXX",
   "campaign" : "campaign:2e94ef85486fXXXXXXXXXXXXX ",
   "environment" : "production",
   "msisdn" : "telenor-TLN-MM:XXXPbCyj3lJNj4mBCIBR2iaYYYYYYYY",
   "currency" : "MMK",
   "amount" : "450.0",
   "mode" : "RENEWAL",
   "frequency" : "weekly",
   "next_payment_timestamp" : "2018-06-05T10:25:01.987Z",
   "transaction" : {
      "status" : "CHARGED",
      "bill_id" : "1d44caaXXXXXX",
      "timestamp" : "2018-05-29 10:25:01 UTC",
      "transaction_id" : "13600XXXXXX"
    }
 }

Below is an example for a deletion notification:

"success" : {
   "type" : "subscription",
   "uuid" : "b7d052f4-c696-42f1-a940-b528eeXXXXXX",
   "operator" : "telenor-mm",
   "merchant" : "partner:4e3f654ed8XXXXXXXXXXXXXXXXXXXXXXXXXX",
   "campaign" : "campaign:2e94ef854XXXXXXXXXXXXXXXXXXXXXXXXXX",
   "environment" : "production",
   "msisdn" : "telenor-TLN-MM:XXXPbCyj3lJNj4mBCIBR2iaYYYYYYYY",
   "currency" : "MMK",
   "amount" : "450.0",
   "mode" : "SYSTEM",
   "frequency" : "weekly",
      "transaction" : {
         "status" : "REMOVED"
      }
   }
}

Unsubscribe and MSISDN Retrieval API Calls

Other API calls such as delete should use the original ACR provided in the response to the subscription create:

POST /v2.2/subscription/delete? msisdn=telenor-TLN-MM:XXXPbCyj3lJNj4mBCIBR2iayWYVpKTz& campaign=campaign:2e94ef85486fXXXXXXXXXXXXX& merchant=partner:4e3f654ed86dbb113bb472XXXXXXXXXXXXXX

For Header Enrichment the ACR can be retrieved for a transaction using MSISDN Retrieval.

ACR Management

One issue with ACR management is that if a user connects to a service when HE (Header Enrichment) is not available then the original ACR is not available as the user will connect via PIN Flow. Some services use cookies or a login mechanism to re-identify the customer in such circumstances. These scenarios should be considered in the definition of your service.

If for customer support reasons you need to access an ACR from a MSISDN then please contact SLA Support via email: [email protected].