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

  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 if required and access to content given
  5. If the user has enough balance then renewal charges are processed (after any free trial) by Zain KW
  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 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

NameDescriptionTypeUsage
msisdnThe subscriber MSISDN that you want to create the subscription for.stringmandatory
pinThe confirmation PIN received by the subscriber via SMS. You can send a PIN to subscribers via the Pin APIstringmandatory
campaignThe Alacrity service URI that identifies the service that this transaction belongs to.stringmandatory
merchantThe Alacrity merchant URI that identifies which merchant this transaction belongs to.stringmandatory
trialintegeroptional
languageThe 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
  • stringoptional
    fraud_tokenIf you are hosting the landing page you may be required to use our fraud prevention API and include a valid/checked token in this requeststringoptional

    Response 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
    bill_idNOT AVAILABLE FOR ZAIN KWstringmandatory
    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.
  • preproduction: UAT 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
  • next_payment_timestampThe timestamp for the next scheduled renewal in UTC time standard.stringNot available for Zain KW
    statusThe transaction status. For Zain KW will be SUCCESS for successful subscription provisioning operation.stringmandatory
    messageThe error description if any.stringoptional
    timestampThe transaction timestamp in UTC time standard.stringmandatory
    transaction_idNOT AVAILABLE FOR ZAIN KWintegermandatory
    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

    NameDescriptionTypeUsage
    uuidThe universally unique identifier for an existing subscription.stringmandatory

    Response Parameters

    NameDescriptionTypeUsage
    serviceThe service name that this subscription belong to.stringmandatory
    msisdnThe subscriber MSISDN that this subscription belongs to.stringmandatory
    frequencyThe frequency of subscription renewal. Below is a list of the possible values:
  • daily
  • weekly
  • fortnightly
  • monthly
  • stringmandatory
    amountThe decimal subscription amount.numericmandatory
    currencyCurrency code as defined in ISO4217.stringmandatory
    statusThe current Subscription Status.stringmandatory
    transactionsNOT AVAILABLE FOR ZAIN KWarrayoptional
    next_payment_timestampNOT AVAILABLE FOR ZAIN KWstringoptional
    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

    NameDescriptionTypeUsage
    msisdnThe subscriber MSISDN that you want to delete the subscription for.stringmandatory
    campaignThe Alacrity service URI that identifies the service that this transaction belongs to.stringmandatory
    merchantThe Alacrity merchant URI that identifies which merchant this transaction belongs to.stringmandatory
    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.