Zain KSA SDP

There are a few differences between Zain KSA and other Operators.

• Charging of customers is managed by Zain KSA so billing related attributes are not returned in API responses.
• Successful create subscription request will respond with status SUCCESS instead of CHARGED.
• Recurring payment notifications are not supported.
• A new status update notification has been added.
• Partial charging lowest domination is one day so daily service will not have partial or fallback charging.
• The pin length is 6 digits

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

Typical Flow

1. User visits a landing page and selects to subscribe to a service
2. Merchant uses the Checkout Flow
3. Merchant calls subscription create call as described below
4. 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
5. If the user has enough balance then renewal charges are processed (after any free trial) by Zain KSA - no notifications are sent
6. 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 times

Charging occur at one of 00:00, 16:00, 20:00(UTC+3) and no notification is sent if the charge succeeds.

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 and no notification is sent.

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.

When a free trial ends then the next charge attempt will be at 00:00 on the next day.

📘

Info

15 digits MSISDNs should be ignored as they are data SIMs that will not be processed. Acceptable MSISDNs are 12 digits.

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

Response Parameters

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-sa",
    "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
    "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
    "environment": "test",
    "msisdn": "96626925482",
    "currency": "SAR",
    "amount": "0.5",
    "mode": "API",
    "frequency": "daily",
    "transaction":
    {
      "status": "SUCCESS"
    }
  }
}

Create Trial

Zain KSA 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

Response Parameters

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": "SAR",
   "status": "ACTIVE"
}

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

{
   "service": "Game Plus",
   "msisdn": "9661116648592",
   "frequency": "weekly",
   "amount": "30.0",
   "currency": "SAR",
   "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

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 not sent for Zain KSA. 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 changes to one of the following statues:

• ACTIVE when a suspended subscription is successfully charged.
• SUSPENDED when an active subscription fails to charge upon subscription renewal.
• REMOVED when the maximum number of retries are exhausted.
• DELETED when customer unsubscribe from the service.
• CANCELLED when the users msisdn has changed.
• SUCCESS when the users msisdn is created via an SMS.

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-sa",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e76",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d2",
      "environment":"production",
      "msisdn":"96626925482",
      "currency":"SAR",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "next_payment_timestamp":"2016-07-08T13:06:46.992Z",
      "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-sa",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e65",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d3",
      "environment":"production",
      "msisdn":"96626925482",
      "currency":"SAR",
      "amount":"0.3",
      "mode":"API",
      "frequency":"weekly",
      "next_payment_timestamp":"2016-07-08T13:06:46.992Z",
      "transaction":{
         "status":"ACTIVE"
      }
   }
}

Charge notification

A charge notification will be sent when a subscription status change occurs. Typically one is sent for the first charge on a service. 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.

If the first charge attempt results in insufficient balance then a charge notification is not sent as you will receive a status notification which has next payment timestamp.

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-sa",
      "merchant": "partner:02c76113-0ca7-xx-88e2-xxxxxxx",
      "campaign": "campaign:940d351138df895e8dedfxxxxxx",
      "environment":"production",
      "msisdn":"966xxxxxx",
      "currency":"SAR",
      "amount":"0.3",
      "mode":"PORTAL",
      "frequency":"weekly",
      "next_payment_timestamp":"2016-07-08T13:06:46.992Z",
      "transaction":{
         "status":"CHARGED"
      }
   }
}

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":"SAR",
       "amount":"1.5",
       "mode":"MOSMS",
       "frequency":"monthly",
       "next_payment_timestamp": "2019-01-30T04:46:38.904Z",
       "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.

One Off PIN API

The PIN API call for Zain KSA is slightly different from the standard PIN API call as the charge amount must be included.

Before requesting that a PIN is generated for a customer you should prompt the customer to enter their MSISDN. The PIN API will generate a unique PIN and send it via SMS to the specified MSISDN. The pin length is 5 digits apart from 000000 in the sandbox environment

HTTP Request

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

Request Parameters

POST /v2.2/pin?
msisdn=965987654321&
campaign=campaign:56yhws-87e376-yuio43-45yhh7&
merchant=partner:00ow34-al6g67-12o6hh-00ff66&
template=subscription&
language=en&
amoutn=5 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/1.1 200 OK
Content-Type: application/json

{
  "error":
  {
    "category": "PIN API",
    "cdoe": "3001",
    "message": "PIN sending failed"
  }
}

📘

Info

The generated PIN will be invalid after 120 seconds.
Please note when using Sandbox credentials, a dummy PIN (000000) will be generated.

❗️

Warning

Please note that if the result of sending the PIN message fails for any reason the PIN message will NOT be sent.

One Off Charge

The charge API call can be made as normal.