Zain KSA SDP

There are a few differences between Zain KW SDP and other Operators.

Successfully created subscription request will respond with status SUCCESS instead of CHARGED.
Recurring payment notifications are supported (For failed notification we are unable to know the reason from the SDP).
A new status update notification has been added.
The pin length is 4 digits

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

Typical Flow

User visits a landing page and selects to subscribe to a service
Merchant uses the Checkout Flow
Merchant calls subscription create call as described below
Create call responds with SUCCESS - this means that the subscription has been successfully created so a welcome SMS should be sent using the send SMS API if required and access to content given
If the user has enough balance then renewal charges are processed (after any free trial) by Zain KW
If the user has insufficient balance then a HTTP Notifications is sent with a subscription status change to SUSPENDED (after a free trial); see example notifications below.

Status change HTTP Notifications are used to identified whether a user is still subscribed to a service. The status API call below can be used to confirm a subscription status.

Charging Notification

If a charge attempt fails but the user has some balance and partial charging is enabled then the user retains access until the next charge time from the three times above.

If a charge attempt fails and the user has insufficient balance then a SUSPENDED notification is sent.
When the user tops up and the charge succeeds at one of three times then an ACTIVE notification is sent.

Create

Create a new subscription using the create API.

Request

POST /v2.2/subscription/create?msisdn={msisdn}&pin={pin}&campaign={campaign}&merchant={merchant}&language={language}

Request Parameters


Name	Description	Type	Usage
msisdn	The subscriber MSISDN that you want to create the subscription for.	string	mandatory
pin	The confirmation PIN received by the subscriber via SMS. You can send a PIN to subscribers via the Pin API	string	mandatory
campaign	The Alacrity service URI that identifies the service that this transaction belongs to.	string	mandatory
merchant	The Alacrity merchant URI that identifies which merchant this transaction belongs to.	string	mandatory
trial		integer	optional
language	The language code as defined in ISO639-1. The chosen language will be used in the SMS message. Below is a list of current supported languages. en for English, ar for Arabic	string	optional
fraud_token	If you are hosting the landing page you may be required to use our fraud prevention API and include a valid/checked token in this request	string	optional
civilid	If you are hosting the page; This is only required if your initial create API request with pin parameter fails with the message "CIVIL ID required" You can then request the subscriber for their civilid and send it in lieu of the pin parameter.	string	optional

Response 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
bill_id	NOT AVAILABLE FOR ZAIN KW	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. preproduction: UAT 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
next_payment_timestamp	The timestamp for the next scheduled renewal in UTC time standard.	string	Not available for Zain KW
status	The transaction status. For Zain KW will be SUCCESS for successful subscription provisioning operation.	string	mandatory
message	The error description if any.	string	optional
timestamp	The transaction timestamp in UTC time standard.	string	mandatory
transaction_id	NOT AVAILABLE FOR ZAIN KW	integer	mandatory

POST /v2.2/subscription/create?
msisdn=96626925482&
pin=12345&
campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
merchant=partner:02c76113-0ca7-4aed-88e2-75267bf85e82&
lanauge=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success":
  {
    "type": "subscription",
    "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
    "operator": "zain-kw",
    "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
    "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
    "environment": "test",
    "msisdn": "96626925482",
    "currency": "KWD",
    "amount": "0.5",
    "mode": "API",
    "frequency": "daily",
    "transaction":
    {
      "status": "SUCCESS"
    }
  }
}

Create Trial

Zain KW support pre-configured trial period per service using the create API..

Please contact the integration team to help you set up your service with the trial period.

Status

Get the subscription status using the status API.

Request

POST /v2.2/subscription/status?uuid={uuid}

Request Parameters


Name	Description	Type	Usage
uuid	The universally unique identifier for an existing subscription.	string	mandatory

Response Parameters


Name	Description	Type	Usage
service	The service name that this subscription belong to.	string	mandatory
msisdn	The subscriber MSISDN that this subscription belongs to.	string	mandatory
frequency	The frequency of subscription renewal. Below is a list of the possible values: daily weekly fortnightly monthly	string	mandatory
amount	The decimal subscription amount.	numeric	mandatory
currency	Currency code as defined in ISO4217.	string	mandatory
status	The current Subscription Status.	string	mandatory
transactions	NOT AVAILABLE FOR ZAIN KW	array	optional
next_payment_timestamp	NOT AVAILABLE FOR ZAIN KW	string	optional

POST /v2.2/subscription/status?
uuid=c537bf6a-8603-466c-9eaa-bf6d3faed28c HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
   "service": "Game Plus",
   "msisdn": "966xxxxxxx",
   "frequency": "weekly",
   "amount": "30.0",
   "currency": "KWD",
   "status": "ACTIVE"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
   "service": "Game Plus",
   "msisdn": "9661116648592",
   "frequency": "weekly",
   "amount": "30.0",
   "currency": "KWD",
   "status": "SUSPENDED"
}

Delete

Delete all existing subscriptions for a customer for a specified service using the delete API.

This is asynchronous call which means you will receive success response even when subscription not existed.

We will send an HTTP notification once the subscription status changed from active/trial to deleted.

Request

POST /v2.2/subscription/delete?msisdn={msisdn}&campaign={campaign}&merchant={merchant}

Request Parameters


Name	Description	Type	Usage
msisdn	The subscriber MSISDN that you want to delete the subscription for.	string	mandatory
campaign	The Alacrity service URI that identifies the service that this transaction belongs to.	string	mandatory
merchant	The Alacrity merchant URI that identifies which merchant this transaction belongs to.	string	mandatory

POST /v2.2/subscription/delete?
msisdn=96526925482&
campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
merchant=partner:02c76113-0ca7-4aed-88e2-75267bf85e82 HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

HTTP Notifications

An HTTP notification is an HTTP POST message sent from our server, every time a subscription event happens, where 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.

There are four main types of subscription notifications.

Recurring Payment Notifications

These are sent for Zain KW. On the Alacrity Portal you can access Insights to see charging information for a service on a daily basis.

Status Update Notifications

We will send an HTTP notification when the subscription status changed to one of the following statuses:

ACTIVE when the suspended subscription become active after being charged.
SUSPENDED when the active subscription fails to charge upon subscription renewal.
REMOVED when the subscription recurring charge fails to be collected.
DELETED when customer unsubscribe from the service.
CANCELLED when the user MSISDN changed.
SUCCESS when the subscription is created successfully.
TRIAL when the subscription is in a trial.

View the HTTP notification section for details.

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

{
   "error":{
      "type":"subscription",
      "uuid":"c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e76",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d2",
      "environment":"production",
      "msisdn":"96626925482",
      "currency":"KWD",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "transaction":{
         "status":"SUSPENDED"
      }
   }
}

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

{
   "success":{
      "type":"subscription",
      "uuid":"c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e65",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d3",
      "environment":"production",
      "msisdn":"96626925482",
      "currency":"KWD",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "transaction":{
         "status":"ACTIVE"
      }
   }
}

Charge notification

A charge notification will be sent when a subscription charge occurs. From this charge notification you can estimate future payment occurrences. The status change notifications (below) include the next payment date which will identify gaps in a payment schedule.

This is NOT a subscription creation notification! However, review against the MO SMS notification shown below.

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

{
   "success":{
      "type":"subscription",
      "uuid":"c537bf6a-xx-xx-xx-bf6d3faed28c",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-xx-88e2-xxxxxxx",
      "campaign": "campaign:940d351138df895e8dedfxxxxxx",
      "environment":"production",
      "msisdn":"966xxxxxx",
      "currency":"KWD",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "transaction":{
         "status":"CHARGED",
         "bill_id": "6ab07c272683N",
         "timestamp": "2015-08-26T10:58:12.026+00:00",
         "transaction_id": "191xxx"
      }
   }
}

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

{
   "success":{
      "type":"subscription",
      "uuid":"c537bf6a-xx-xx-xx-bf6d3faed28c",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-xx-88e2-xxxxxxx",
      "campaign": "campaign:940d351138df895e8dedfxxxxxx",
      "environment":"production",
      "msisdn":"966xxxxxx",
      "currency":"KWD",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "transaction":{
         "status":"RETRY_FAILED",
         "bill_id": "6ab07c272683N",
         "timestamp": "2015-08-26T10:58:12.026+00:00",
         "transaction_id": "191xxx"
      }
   }
}

MO SMS Notification

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-kw",
       "merchant": "partner:02c76113-0ca7-4aed-88e2-xxxx",
       "campaign": "campaign:940d351138df895e8dedf51e5d7b9xxx",
       "environment":"production",
       "msisdn":"9659xxxx",
       "currency":"KWD",
       "amount":"1.5",
       "mode":"MOSMS",
       "frequency":"monthly",
       "transaction"=>{
          "status"=>"TRIAL"
        }
    }
}

❗️
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 two hours for one week.