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

NameDescriptionTypeUsage
typeAn 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.
  • stringmandatory
    uuidThe universally unique identifier for the subscription.stringmandatory
    bill_idThe unique identifier representing all renewal attempts for one bill period.stringmandatory
    operatorThe mobile operator code.stringmandatory
    merchantThe Alacrity merchant URI that identifies which merchant this transaction belongs to.stringmandatory
    campaignThe Alacrity service URI that identifies the service that this transaction belongs to.stringmandatory
    environmentThe environment that your API credential belong to. Below is a list of the possible values:
  • test: sandbox credentials.
  • production: live credentials.
  • stringmandatory
    msisdnThe subscriber MSISDN that the subscription has been created for.stringmandatory
    currencyCurrency code as defined in ISO4217.stringmandatory
    amountThe decimal amount that has been charged.numericmandatory
    modeAn 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

  • stringmandatory
    frequencyThe frequency of subscription renewal. Below is a list of the possible values:
  • daily
  • weekly
  • fortnightly
  • monthly
  • stringmandatory
    durationAn indication of the number of days that the partial charge is for.integeroptional
    next_payment_timestampThe timestamp for the next scheduled renewal in UTC time standard.stringoptional
    statusThe transaction status. A list of the possible values found herestringmandatory
    messageThe error description if any.stringoptional
    timestampThe transaction timestamp in UTC time standard.stringmandatory
    transaction_idThe API generated and unique transaction's identifier.integermandatory
    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

    NameDescriptionTypeUsage
    typeAn 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.
  • stringmandatory
    uuidThe universally unique identifier for the subscription.stringmandatory
    operatorThe mobile operator code.stringmandatory
    merchantThe Alacrity merchant URI that identifies which merchant this transaction belongs to.stringmandatory
    campaignThe Alacrity service URI that identifies the service that this transaction belongs to.stringmandatory
    environmentThe environment that your API credential belong to. Below is a list of the possible values:
  • test: sandbox credentials.
  • production: live credentials.
  • stringmandatory
    msisdnThe subscriber MSISDN that the subscription has been created for.stringmandatory
    currencyCurrency code as defined in ISO4217.stringmandatory
    amountThe decimal amount that has been charged.numericmandatory
    modeAn 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

  • stringmandatory
    frequencyThe frequency of subscription renewal. Below is a list of the possible values:
  • daily
  • weekly
  • fortnightly
  • monthly
  • stringmandatory
    next_payment_timestampThe timestamp for the next scheduled renewal in UTC time standard.stringoptional
    statusThe subscription status. A list of the possible values found herestringmandatory

    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"
    }