HTTP Notifications

An HTTP notification is an HTTP POST message sent from our server every time a subscription event happens. The body of the message will be in JSON format and sent to a URL that you specified in your service settings (notification URL).

Those notifications will help Merchants to keep track of all asynchronous data of their customer's subscriptions. Most commonly you will receive notifications:

if a customer subscribes or unsubscribes via MOS SMS
if a subscription is deleted as a result of a customer care request
on each Subscription renewal attempt (except Zain KSA)

The mode identifies the reason for the notification.

📘
Info
Notifications are not sent when a merchant makes an API calls such as create subscription.

There are three main types of subscription notifications:

Recurring Payments

For every charge attempt which happens during renewal, Alacrity will send an HTTP notification (regardless of the transaction status).

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json

{
   "success":{
      "type":"subscription",
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "bill_id":"6ab07c272683N",
      "operator":"zain-jo",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
      "environment":"production",
      "msisdn":"96226925482",
      "currency":"JOD",
      "amount":"0.1",
      "mode":"RENEWAL",
      "frequency":"daily",
      "next_payment_timestamp":"2016-07-08T13:06:46.992Z",
      "transaction":{
         "status":"CHARGED",
     		 "bill_id":"6ab07c272683N",
         "timestamp":"2016-07-08T05:06:47.010+00:00",
         "transaction_id":"656000"
      }
   }
}

Notification Parameters

Name	Description	Type	Usage
type	An indication of the transaction type. Below is a list of the possible values: charge: Immediate charge transaction associated with One Off charges. refund: Immediate refund transaction. subscription: Subscription's initial charge transaction.	string	mandatory
uuid	The universally unique identifier for the subscription.	string	mandatory
bill_id	The unique identifier representing all renewal attempts for one bill period.	string	mandatory
operator	The mobile operator code.	string	mandatory
merchant	The Alacrity merchant URI that identifies which merchant this transaction belongs to.	string	mandatory
campaign	The Alacrity service URI that identifies the service that this transaction belongs to.	string	mandatory
environment	The environment that your API credential belong to. Below is a list of the possible values: test: sandbox credentials. production: live credentials.	string	mandatory
msisdn	The subscriber MSISDN that the subscription has been created for.	string	mandatory
currency	Currency code as defined in ISO4217.	string	mandatory
amount	The decimal amount that has been charged.	numeric	mandatory
mode	An indication of the transaction mode. Below is a list of the possible values: API Synchronous API response RENEWAL Renewal notification PARTIAL Partial renewal notification STEP_DOWN Step Down renewal notification MOSMS Mobile Originated SMS action notification PORTAL Self Service Portal action notification SYSTEM System logic action notification CUSTOMER_CARE_PORTAL Self Customer Care action notification CUSTOMER_CARE_PORTAL_LINK Self Customer Care Direct unsub link action notification CONFIRMSMS Confirmation SMS received notification CC_API Operator Customer Care API unsub action notification OPCO_API Operator Notification API unsub action notification	string	mandatory
frequency	The frequency of subscription renewal. Below is a list of the possible values: daily weekly fortnightly monthly	string	mandatory
duration	An indication of the number of days that the partial charge is for.	integer	optional
next_payment_timestamp	The timestamp for the next scheduled renewal in UTC time standard.	string	optional
status	The transaction status. A list of the possible values found here	string	mandatory
message	The error description if any.	string	optional
timestamp	The transaction timestamp in UTC time standard.	string	mandatory
transaction_id	The API generated and unique transaction's identifier.	integer	mandatory

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json

{
   "error":{
      "type":"subscription",
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "bill_id":"6ab07c272683N",
      "operator":"zain-jo",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
      "environment":"production",
      "msisdn":"96226925482",
      "currency":"JOD",
      "amount":"0.1",
      "mode":"RENEWAL",
      "frequency":"daily",
      "next_payment_timestamp":"2016-07-08T13:06:46.992Z",
      "transaction":{
         "status":"INSUFFICIENT_FUNDS",
      	 "bill_id":"6ab07c272683N",
         "message":"Not Enough Balance",
         "timestamp":"2016-07-08T05:06:47.010+00:00",
         "transaction_id":"656000"
      }
   }
}

Status Updates

For every asynchronous update to subscription status, Alacrity will send an HTTP notification about it.

Notification Parameters

Name	Description	Type	Usage
type	An indication of the transaction type. Below is a list of the possible values: charge: Immediate charge transaction. refund: Immediate refund transaction. subscription: Subscription's initial charge transaction.	string	mandatory
uuid	The universally unique identifier for the subscription.	string	mandatory
operator	The mobile operator code.	string	mandatory
merchant	The Alacrity merchant URI that identifies which merchant this transaction belongs to.	string	mandatory
campaign	The Alacrity service URI that identifies the service that this transaction belongs to.	string	mandatory
environment	The environment that your API credential belong to. Below is a list of the possible values: test: sandbox credentials. production: live credentials.	string	mandatory
msisdn	The subscriber MSISDN that the subscription has been created for.	string	mandatory
currency	Currency code as defined in ISO4217.	string	mandatory
amount	The decimal amount that has been charged.	numeric	mandatory
mode	An indication of the transaction mode. Below is a list of the possible values: API Synchronous API response RENEWAL Renewal notification PARTIAL Partial renewal notification STEP_DOWN Step Down renewal notification MOSMS Mobile Originated SMS action notification PORTAL Self Service Portal action notification SYSTEM System logic action notification CUSTOMER_CARE_PORTAL Self Customer Care action notification CUSTOMER_CARE_PORTAL_LINK Self Customer Care Direct unsub link action notification CONFIRMSMS Confirmation SMS received notification CC_API Operator Customer Care API unsub action notification OPCO_API Operator Notification API unsub action notification	string	mandatory
frequency	The frequency of subscription renewal. Below is a list of the possible values: daily weekly fortnightly monthly	string	mandatory
next_payment_timestamp	The timestamp for the next scheduled renewal in UTC time standard.	string	optional
status	The subscription status. A list of the possible values found here	string	mandatory

The below notification is sent when a user subscribes with MO SMS and the service has a free trial.

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json
{
  "success":{
    "type":"subscription",
    "uuid":"92b31909-66e9-xxx-xxxx-29ba9adc3d9b",
    "operator":"zain-jo",
    "merchant":"partner:9dca9b95-75b4-xxxx-xxxx-112479400f36",
    "campaign":"campaign:3cd9a87cd4bf680b355xxxx8f51aa8f0",
    "environment":"production",
    "msisdn":"962xxxxxxx",
    "currency":"JOD",
    "amount":"0.65",
    "mode":"MOSMS",
    "frequency":"weekly",
    "next_payment_timestamp":"2020-05-25T07:43:50.220Z",
    "transaction":{
      "status":"TRIAL"
    }
  }
}

The below notification is sent when a user subscribes with MO SMS and the service has no free trial so a charge occurs.

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json
{
  "success":{
    "type":"subscription",
    "uuid":"09f8d01a-e182-46f1-xxxx-xxxxxxxx",
    "bill_id":"159661a92055",
    "operator":"zain-jo",
    "merchant":"partner:9dca9b95-75b4-40f4-xxxx-xxxxxxx",
    "campaign":"campaign:3cd9a87cd4bf680b355bxxxxxxx",
    "environment":"production",
    "msisdn":"9627xxxxxxx",
    "currency":"JOD",
    "amount":"0.65",
    "mode":"MOSMS",
    "frequency":"weekly",
    "next_payment_timestamp":"2020-05-18T01:16:21.250Z",
    "transaction":{
      "status":"CHARGED",
      "bill_id":"xxxxxxx",
      "timestamp":"2020-05-11 01:16:20 UTC",
      "transaction_id":"xxxxxx"
    }
  }
}

Deleted identifies that subscription was deleted by the Customer Care portal or MO SMS as shown below. The example below is for Telenor which return msisdns in the form "telenor-TLN-MM:M1hLXXXXXXXXXXXXXXXXXXXXXXXXX". Other operators provide the msisdn.

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json
{
    "success" : {
        "type" : "subscription",
        "uuid" : "4262bcb2-5bda-XXXXXXXXXXXXXXXXXXXXXXXXX7",
        "operator" : "telenor-mm",
        "merchant" : "partner:XXXXXXXXXXXXXXXXXXXXXXXXX",
        "campaign" : "campaign:XXXXXXXXXXXXXXXXXXXXXXXXX",
        "environment" : "production",
        "msisdn" : "telenor-TLN-MM:M1hLXXXXXXXXXXXXXXXXXXXXXXXXX",
        "currency" : "MMK",
        "amount" : "450.0",
        "mode" : "CUSTOMER_CARE_PORTAL_LINK",
        "frequency" : "weekly",
        "transaction" : {
            "status" : "DELETED"
        }
    }
}

Removed identifies when a Subscription is deleted, for example, when the retry period has completed.

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json
{
    "success" : {
        "type" : "subscription",
        "uuid" : "cab3ce8a-7b41-4e39-a503-5XXXXXXXXX",
        "operator" : "telenor-mm",
        "merchant" : "partner:XXXXXXXXXXXXXXXXXXXXXXXXX",
        "campaign" : "campaign:XXXXXXXXXXXXXXXXXXXXXXXXX",
        "environment" : "production",
        "msisdn" : "telenor-TLN-MM:XXXXXXXXXXXXXXXXXXXXXXXXX",
        "currency" : "MMK",
        "amount" : "450.0",
        "mode" : "SYSTEM",
        "frequency" : "weekly",
        "transaction" : {
            "status" : "REMOVED"
        }
    }
}

SUSPENDED is used with Zain KSA

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json
{
  "error": {
    "type": "subscription",
    "uuid": "7863cd35-0712-xxx-aae2-xxxxxxxx",
    "operator": "zain-sa",
    "merchant": "partner:4ca6dd08-xxx-44d9-aff8-xxxxxx",
    "campaign": "campaign:88b9e17951262bca591f4c745axxxxxxxxx",
    "environment": "production",
    "msisdn": "966xxxxxxxxx",
    "currency": "SAR",
    "amount": "5.0",
    "mode": "API",
    "frequency": "weekly",
    "transaction": {
      "status": "SUSPENDED"
    }
  }
}

🚧
Warning
Please note that all HTTP notifications should respond with a 200 or 201 HTTP response code regardless of response body, otherwise Alacrity will keep trying to send the notification every four hours for one day.

Availability Checks

Alacrity system will send this notification from time to time (weekly) to check the availability of the notification URL.

POST / HTTP/1.1
Host: <MERCHANT_NOTIFICATION_URL>
Content-Type: application/json

{
    "message": "Test availability",
    "timestamp": "2016-07-08T05:06:47.010+00:00"
}

HTTP Notifications

📘
Info

Recurring Payments

Status Updates

🚧
Warning

Availability Checks

📘Info

Recurring Payments

Status Updates

🚧Warning

Availability Checks

📘
Info

🚧
Warning