NAV
Alacrity API Documentation
HTTP C# Java PHP

Introduction

API Endpoint: http://api.sla-alacrity.com

Alacrity is a Digital Services Platform that provides a range of Digital Services like Direct Operator Billing to Mobile Operators and Merchants.

The following are the Alacrity API standards:

HTTP Tab will show you HTTP request/response samples using generic message format of RFC 822

We also have some specific language libraries to make integration easier. You can switch the programming language of the examples with the tabs in the top right.

If you have any questions please contact us via email: Integration@SLA-LTD.COM

Getting Started

SLA’s Integration Team will introduce you to the Alacrity Platform and give you instructions to register for access to the Alacrity Portal. The Alacrity Portal can be access via www.sla-alacrity.com

Registration

Accounts will be created for merchants which will allow them to create and manage multiple merchants and/or services.

Service Management

merchant_new

Create Service

Once your merchant has been successfuly created you can begin creating services for that merchant.

Service URI example: campaign:2c16ac357652ee7d93d2cfce3f959dfccfa758ca

API Access

Alacrity uses Basic Authentication to allow access to the API. Your API Credentials (username / password) can be generated from the Alacrity Portal. - Go to API Access tab ➤ Add API Login

Environments

The API has three accessible environements. You can create API credentials for each as follows:

Sandbox

Requests made within the sandbox are not connected to any mobile operator’s billing system and therefore incur no costs.

UAT

Requests made within UAT are connected to the mobile operator’s billing system. Staging environments specification vary from operator to operator.

Live

Requests made within the live environment will have access to the mobile operator’s end users.

IP Whitelisting

CIDR IP addresses Examples:
120.55.23.13/32 (for a single network address)
120.55.23.13/25 (for a 128 network addresses)

In addition to Basic Authentication, your server IP addresses must be whitelisted. This can be done via the portal.

Mobile Operators

Bellow is a list of live mobile operators with our Direct Operator Billing service:

Name Country Currency Code SMS Language Max Charge Limit Spend Limit
Zain KW Kuwait KWD zain-kw English, Arabic 30 Monthly postpaid: 30
Monthly prepaid: 300
Zain BH Bahrain BHD zain-bh English, Arabic 30 Monthly postpaid: 30
Zain JO Jordan JOD zain-jo English, Arabic 30 Monthly: 30
Zain IQ Iraq IQD zain-iq Arabic 88000 Monthly: 88000
Zain SD Sudan SDG zain-sd English, Arabic 30
Zain KSA Saudi Arabia SAR zain-sa English 30 Monthly: 30
Vodafone Ireland Ireland EUR vf-ie English 30 Daily: 30
Telenor Digi Malaysia MYR telenor-digi English 100 Monthly: 300
Telenor Myanmar Myanmar MMK telenor-mm English, Burmese 10000
Jawwal Palestine ILS jawwal-pl English 30 Monthly: 30
Etisalat UAE United Arab Emirates AED etisalat-ae English, Arabic 333

Authentication

For example, the string fred:fred encodes to ZnJlZDpmcmVk in base64, in this case your HTTP Header will be:
Authorization: Basic ZnJlZDpmcmVk

You should use HTTP Basic Authentication to verify your identity via the API.

To use Basic Authentication with the Alacrity API, simply perform the following steps:

Authorization: Basic <YOUR_ENCODED_STRING>

Sandbox API

The sandbox environment is available to you immediately so you can begin testing straight away. This environment does not require agreements to be set up.

The environment is determined by the credentials that you use to authenticate. So if you are using Sandbox credentials your requests will automatically go to the Sandbox.

Dummy PIN

The PIN API request will always generate the same PIN value which is 000000 as no actual SMS is sent for transactions in the Sandbox.

Once you receive a successful response from PIN API, you can use the PIN 000000 with the subscription API.

Provision

Sample Request

POST /v2.2/sandbox/provision?
msisdn=965987654321&
merchant=partner:00ow34-al6g67-12o6hh-00ff66&
amount=30&
currency=KWD HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Sample Response

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

{
  "success": true
}

Provision an MSISDN in the Sandbox with some credit. An MSISDN is only provisioned for a maximum of 4 hours. After that it will need re-provisioned.

HTTP Request

POST /v2.2/sandbox/provision?msisdn={msisdn}&merchant={merchant}&amount={amount}&currency={currency}

Request Parameters

Name Description Type Usage
msisdn The subscribers MSISDN that you want to provision. string mandatory
merchant The Alacrity merchant uri that identifies which merchant this transaction belongs to. string mandatory
amount The amount that you want to provision. numeric mandatory
currency The currency associated with the MSISDN. string mandatory

Balance

Sample Request

POST /v2.2/sandbox/balances?
merchant=partner:00ow34-al6g67-12o6hh-00ff66 HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Sample Response

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

{
  "965987654321": 30.000,
  "965912345678": 1.500
}

Receive the list of provisioned MSISDNs with their balances.

HTTP Request

POST /v2.2/sandbox/balances?merchant={merchant}&msisdn={msisdn}

Request Parameters

Name Description Type Usage
merchant The Alacrity merchant uri that identifies which merchant this transaction belongs to. string mandatory
msisdn The subscribers MSISDN that you want to check the balance for. string optional

Sandbox testing

SLA require two documents from the merchant to complete the Sandbox testing phase of an integration:

  1. SLA require evidence from the merchant that they have tested in the Sandbox environment. This evidence should be in the form of a document summarising their test cases with reference to the transactions completed with SLA. See the document DOB Final Test Report – Merchants

  2. SLA require a user flow document describing the Merchant’s service – typically this is a document with screenshots and a description of how the end user would access and use the service. This will be used for testing the service and may be provided to the Operator

Billing API

Charge

Sample Request

POST /v2.2/charge?
msisdn=96526925482&
campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
merchant=partner:02c76113-0ca7-4aed-88e2-75267bf85e82&
amount=0.5&
currency=KWD&
correlator=we78fehjke8erwhjkre78&
description=Game+from+Acme+Games&
language=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Sample Response (success)

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

{
  "success":
  {
    "type": "charge",
    "operator": "zain-kw",
    "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
    "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
    "environment": "test",
    "msisdn": "96526925482",
    "currency": "KWD",
    "amount": "0.5",
    "transaction":
    {
      "status": "CHARGED",
      "timestamp": "2015-08-26T10:58:12.026+08:00",
      "transaction_id": "1910173"
    }
  }
}

Sample Response (failed)

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

{
  "error":
  {
    "type": "charge",
    "operator": "zain-kw",
    "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
    "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
    "environment": "test",
    "msisdn": "96526925482",
    "currency": "KWD",
    "amount": "0.5",
    "transaction":
    {
      "status": "ACCOUNT_NOT_FOUND",
      "timestamp": "2015-08-26T10:59:10.000+08:00",
      "transaction_id": "1910174"
    }
  }
}

Immediate charge against the subscriber. Used for direct one-off charge based services.

HTTP Request

POST /v2.2/charge?msisdn={msisdn}&campaign={campaign}&merchant={merchant}amount={amount}&currency={currency}&correlator={correlator}&description={description}&language={language}

Request Parameters

Name Description Type Usage
msisdn The subscribers MSISDN that you want to charge. 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
amount The decimal amount that you want to charge. numeric mandatory
currency Currency code as defined in [ISO4217]. string mandatory
correlator A unique string for this transaction. The correlator guards against accidental duplicate transactions. string mandatory
description The human readable description for this charge that will appear on the customers bill. string mandatory
pin The confirmation PIN received by the subscriber via SMS. You can send a pin to subscribers via the PIN API. (Conditional depending on operator) string conditional
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

    PIN Parameter

    PIN is a required request parameter for the below mentioned mobile operators

    Mobile Operator
    Telenor Digi

    Response Parameters

    Name Description Type Usage
    type An indication of the transaction type. Below is a list of possible values:
  • charge: Immediate charge transaction.
  • refund: Immediate refund transaction.
  • subscription: Subscription’s initial charge transaction.
  • 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 credentials belong to. Below is a list of possible values:
  • test: sandbox credentials.
  • preproduction: UAT credentials.
  • production: live credentials.
  • string mandatory
    msisdn The subscribers MSISDN that has been charged. string mandatory
    currency Currency code as defined in [ISO4217]. string mandatory
    amount The decimal amount that has been charged. numeric mandatory
    status The transaction status. A list of possible values can be 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 transactions identifier. integer mandatory

    Refund

    Sample Request

    POST /v2.2/refund?
    msisdn=96526925482&
    campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
    merchant=partner:02c76113-0ca7-4aed-88e2-75267bf85e82&
    amount=-0.5&
    currency=KWD&
    correlator=we78fehjke8erwhjkre78&
    transaction=1910173&
    language=ar HTTP/1.1
    Host: api.sla-alacrity.com
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Accept: application/json
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success":
      {
        "type": "refund",
        "operator": "zain-kw",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "-0.5",
        "transaction":
        {
          "status": "REFUNDED",
          "timestamp": "2015-08-26T10:58:12.026+08:00",
          "transaction_id": "2090173"
        }
      }
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "type": "refund",
        "operator": "zain-kw",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "-0.5",
        "transaction":
        {
          "status": "ACCOUNT_NOT_FOUND",
          "timestamp": "2015-08-26T10:59:10.000+08:00",
          "transaction_id": "1910174"
        }
      }
    }
    

    Immediate refund against previous charge transaction.

    HTTP Request

    POST /v2.2/refund?msisdn={msisdn}&campaign={campaign}&merchant={merchant}amount={amount}&currency={currency}&correlator={correlator}&transaction={transaction_id}&language={language}

    Request Parameters

    Name Description Type Usage
    msisdn The subscribers MSISDN that you want to refund. 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
    amount The decimal amount that you want to refund. This must be a negative amount eg. -0.010 numeric mandatory
    currency Currency code as defined in [ISO4217]. string mandatory
    correlator A unique string for this transaction. The correlator guards against accidental duplicate transactions. string mandatory
    transaction The transaction ID for the original transaction that you are refunding. The transaction_id is returned by Alacrity in the response to a successful charge transaction. integer mandatory
    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

    Response Parameters

    Name Description Type Usage
    type An indication of the transaction type. Below is a list of possible values:
  • charge: Immediate charge transaction.
  • refund: Immediate refund transaction.
  • subscription: Subscription’s initial charge transaction.
  • 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 possible values:
  • test: sandbox credentials.
  • preproduction: uat credentials.
  • production: live credentials.
  • string mandatory
    msisdn The subscribers MSISDN that has been refunded. string mandatory
    currency Currency code as defined in [ISO4217]. string mandatory
    amount The decimal amount that has been refunded. numeric mandatory
    status The transaction status. A list of 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 transactions identifier. integer mandatory

    PIN API

    The PIN API will generate a unique PIN and send it via SMS to the specified MSISDN. The PIN must then be included in the Subscription creation request and some operator One Off Charge API calls. The PIN is used to verify that the customer has opted in to a service.

    Send

    Sample Request

    POST /v2.2/pin?
    msisdn=965987654321&
    campaign=campaign:56yhws-87e376-yuio43-45yhh7&
    merchant=partner:00ow34-al6g67-12o6hh-00ff66&
    template=subscription&
    language=en HTTP/1.1
    Host: api.sla-alacrity.com
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Accept: application/json
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "PIN API",
        "cdoe": "3001",
        "message": "PIN sending failed"
      }
    }
    

    Generate a unique PIN and send via SMS to the specified MSISDN.

    HTTP Request

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

    Request Parameters

    Name Description Type Usage
    msisdn The subscribers MSISDN that you want to send the PIN to. 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
    template The template to be used which will determine the content of the SMS message. Below is a list of the valid options:
  • charge (default)
  • subscription
  • string 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

    SMS API

    The SMS API will send an SMS message to the specified MSISDN.

    Send

    Sample Request

    POST /v2.2/sms?
    msisdn=965987654321&
    campaign=campaign:56yhws-87e376-yuio43-45yhh7&
    merchant=partner:00ow34-al6g67-12o6hh-00ff66&
    correlator=we78fehjke8erwhjkre78&
    text=welcome HTTP/1.1
    Host: api.sla-alacrity.com
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Accept: application/json
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "SMS API",
        "cdoe": "8001",
        "message": "SMS sending failed"
      }
    }
    

    Send an SMS message to a specified MSISDN.

    HTTP Request

    POST /v2.2/sms?msisdn={msisdn}&campaign={campaign}&merchant={merchant}&correlator={correlator}&text={text}

    Request Parameters

    Name Description Type Usage
    msisdn The subscriber MSISDN that you want to send the SMS to. 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
    correlator A unique string for this transaction. The correlator guards against accidental duplicate transactions. string mandatory
    text A text message which will be sent to the subscriber. string mandatory

    Subscription API

    The Alacrity Subscription API’s allow merchants to easily manage subscription services for customers. Alacrity takes care of opting the customer in and confirming their subscription, notifying them of the subscription details, recurring billing and retries.

    All of this is done in accordance with the Mobile Operators requirements for subscription services. Alacrity also sends notifications to the Merchant to inform you of updates and charges to a subscription.

    Create

    Sample Request

    POST /v2.2/subscription/create?
    msisdn=96526925482&
    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
    

    Sample Response (success)

    HTTP/1.1 200 OK
    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-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "next_payment_timestamp": "2015-08-27T10:58:12.026Z",
        "transaction":
        {
          "status": "CHARGED",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "type": "subscription",
        "operator": "zain-kw",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "transaction":
        {
          "status": "ACCOUNT_NOT_FOUND",
          "message": "Account could not be found",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    
    /**
     *
     * C# coming soon
     *
    */
    
    /**
     *
     * Java coming soon
     *
    */
    
    /**
     *
     * PHP coming soon
     *
    */
    

    Create a new subscription with an initial charge attempt.

    HTTP 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
    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

    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 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.
  • 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
  • MOSMS: Mobile Originated SMS action notification
  • PORTAL: Self Service Portal action notification
  • SYSTEM: System logic 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 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

    Create Trial

    Sample Request

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

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true,
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "msisdn": "96526925482"
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "Free Trial",
        "cdoe": "5001",
        "message": "{service_name} service doesn't support Free trial subscriptions"
      }
    }
    

    Create a new subscription with free trial period.

    HTTP Request

    POST /v2.2/subscription/create?msisdn={msisdn}&pin={pin}&campaign={campaign}&merchant={merchant}&trial={trial_days}&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 subscriber via 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 The length of the free trial period in days. Maximum value is 30. 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

    Create Inactive

    Sample Request

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

    Sample Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true,
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "msisdn": "96526925482"
    }
    

    Create a new subscription without an initial charge attempt. The subscription status will be Inactive.

    HTTP Request

    POST /v2.2/subscription/create?msisdn={msisdn}&pin={pin}&campaign={campaign}&merchant={merchant}&charge=false&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
    charge A flag indicates whether an initial charge attempt will be triggered or not. boolean 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

    Activate

    Sample Request

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

    Sample Response (success)

    HTTP/1.1 200 OK
    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-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "next_payment_timestamp": "2015-08-27T10:58:12.026Z",
        "transaction":
        {
          "status": "CHARGED",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "type": "subscription",
        "operator": "zain-kw",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "96526925482",
        "currency": "KWD",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "transaction":
        {
          "status": "ACCOUNT_NOT_FOUND",
          "message": "Account could not be found",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    

    Update an inactive subscription to active with an initial charge attempt.

    HTTP Request

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

    Request Parameters

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

    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 The unique identifier representing all renewal’s 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.
  • 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
  • MOSMS: Mobile Originated SMS action notification
  • PORTAL: Self Service Portal action notification
  • SYSTEM: System logic 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 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

    Resume

    Sample Request

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

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true,
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c"
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "Request Validation",
        "cdoe": "2020",
        "message": "Grace period should not exceed 30 days and number of retries should not exceed 3 times per day"
      }
    }
    

    Activate a subscription that was removed because it exceeded the retries grace period for failed recurring payments.

    HTTP Request

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

    Request Parameters

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

    Response Parameters

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

    Free Period (Coupons)

    eg. period=2 it will skip:
    2 days for daily subscriptions.
    2 weeks (14 days) for weekly subscriptions.
    2 fortnights (28 days) for fortnightly subscriptions.
    2 months (60 days) for monthly subscriptions.

    Sample Request

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

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true,
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c"
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "Free Period'",
        "cdoe": "7001",
        "message": "{service_name} service doesn't support Free periods for subscriptions"
      }
    }
    

    Activate a free period (free coupon) for an active subscription.

    HTTP Request

    POST /v2.2/subscription/free?uuid={uuid}&period={period}

    Request Parameters

    Name Description Type Usage
    uuid The universally unique identifier for an existing active subscription. string mandatory
    period The number of renewals to skip in the active subscription. integer mandatory

    Response Parameters

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

    Status

    Sample Request

    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
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
       "service": "Shahid Plus",
       "msisdn": "9651116648592",
       "frequency": "weekly",
       "amount": "30.0",
       "currency": "KWD",
       "status": "ACTIVE",
       "transactions": [
          {
             "transaction_id": "1910173",
             "status": "CHARGED",
             "amount": "30.0",
             "billid": "84dc29e80138",
             "timestamp": "2016-05-31 02:36:36 UTC"
          },
          {
             "transaction_id": "1920165",
             "status": "INSUFFICIENT_FUNDS",
             "amount": "30.0",
             "billid": "3d146bc57c23",
             "timestamp": "2016-06-07 02:58:00 UTC"
          },
          {
            "transaction_id": "1920169",
             "status": "CHARGED",
             "amount": "4.285",
             "billid": "3d146bc57c23",
             "timestamp": "2016-06-07 02:59:00 UTC"
          }
       ],
       "next_payment_timestamp": "2016-06-14 02:59:00 UTC"
    }
    

    Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "category": "Request Validation'",
        "cdoe": "2011",
        "message": "Subscription not found"
      }
    }
    

    Get the subscription status.

    HTTP 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. Refer to Subscription Status table. string mandatory
    transactions List of all charge transactions that belong to this subscription. array optional
    next_payment_timestamp The timestamp for the next scheduled renewal in UTC time standard. string optional

    Delete

    Sample Request

    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
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true
    }
    

    Delete all existing subscriptions for a customer for a specified service.

    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.

    HTTP 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

    Subscription via SMS

    Customers can subscribe/unsubscribe to your services by sending an SMS to the Operator’s Short Code.

    Operators Short Codes

    Code Operator
    1090 Etisalat UAE
    37022 Jawwal Palestine
    94010 Zain Kuwait
    97970 Zain Jordan
    94005 Zain Bahrain
    4064 Zain Iraq

    Subscribe

    The possible SMS formats for subscription are:

    SUB <KEYWORD>

    START <KEYWORD>

    Unsubscribe

    The possible SMS formats for unsubscribe are:

    UNSUB <KEYWORD>

    STOP <KEYWORD>

    Subscription Renewal

    This section provides information about the actions which are taken when recurring payments are handled by the Alacrity Subscriptions module.

    The Subscription module performs a number of tasks as part of renewal, including generating a transaction to record payment, notifying both the merchant via http notifications and the customer via SMS and processing the payment.

    Recurring Payments

    A key feature of subscriptions is a reccuring payment - a payment due at a regular interval over time.

    Proration Recurring Payments

    Sample partial charge HTTP notification

    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-kw",
          "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96596619582",
          "currency":"KWD",
          "amount":"1.5",
          "mode":"PARTIAL",
          "frequency":"monthly",
          "duration":7,
          "transaction":{
             "status":"CHARGED",
             "timestamp":"2016-07-08 04:40:15 +0000",
             "transaction_id":"6563403"
          }
       }
    }
    

    Alacrity will automatically prorate a partial period fees if a subscription recurring payment fails due to customer having an insufficient credits.

    The below table shows the partial charges that Alacrity will try for different subscriptions frequencies.

    Frequency Partial Period Partial Amount
    Daily NA NA
    Weekly 1 Day Full Amount / 7
    Fortnightly 1 Day Full Amount / 14
    Monthly 1 Week Full Amount / 4

    Once the duration of the partial period has expired Alacrity will once again attempt the full subscription amount for the regular frequency.

    Step-Down Recurring Payments

    Sample step-down charge HTTP notification

    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-kw",
          "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96596619582",
          "currency":"KWD",
          "amount":"0.05",
          "mode":"STEP_DOWN",
          "frequency":"monthly",
          "duration":7,
          "transaction":{
             "status":"CHARGED",
             "timestamp":"2016-07-08 04:40:15 +0000",
             "transaction_id":"6563403"
          }
       }
    }
    

    In case of having a customer with no enough credits, Alacrity allows you to configure a list of step-down amounts (max 5) in order to breakdown your recurring charges to a certain partial amounts.

    An example of a step-down charging:

    Service Policy Value
    Frequency Daily
    Full Price $1
    Step-down amounts $0.5 $0.15 $0.05
    Step-down grace period retry every 8 hours for 3 days

    In case of a customer having only $0.23 of credits, Alacrity will try to charge the step-down amounts:

    Try to charge $0.5 Fail

    Try to charge $0.15 Success

    Try to charge $0.15 Fail

    Try to charge $0.05 Success

    Try to charge $0.05 Fail

    Total amount deducted = $0.2

    Total balance = $0.8

    After 8 hours we will try to charge the balance $0.8 and if it fails then we will loop back again on the step-down amounts until we obtain the full amount $1.

    Counting a 3 days from the last successful partial charge and if the balance not obtained during that time, we will automatically unsubscribe the customer.

    Failed Payment Handling

    Sample HTTP notification for subscription that exceed the retries grace period

    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-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96526925482",
          "currency":"KWD",
          "amount":"0.3",
          "mode":"SYSTEM",
          "frequency":"weekly",
          "transaction":{
             "status":"REMOVED"
          }
       }
    }
    

    When a recurring payment fails:

    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 two main types of subscription notifications:

    1. Recurring Payment Notifications

    Sample Renewal Notification Body (success)

    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",
             "timestamp":"2016-07-08T05:06:47.010+00:00",
             "transaction_id":"656000"
          }
       }
    }
    

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

    Notification Parameters

    Sample Renewal Notification Body (failed)

    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",
             "message":"Not Enough Balance",
             "timestamp":"2016-07-08T05:06:47.010+00:00",
             "transaction_id":"656000"
          }
       }
    }
    
    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 The unique identifier representing all renewal’s 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.
  • 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
  • MOSMS: Mobile Originated SMS action notification
  • PORTAL: Self Service Portal action notification
  • SYSTEM: System logic 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

    2. Status Update Notifications

    Sample Status Update Notification Body

    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-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96526925482",
          "currency":"KWD",
          "amount":"0.3",
          "mode":"MOSMS",
          "frequency":"weekly",
          "transaction":{
             "status":"DELETED"
          }
       }
    }
    

    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.
  • 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
  • MOSMS Mobile Originated SMS action notification
  • PORTAL Self Service Portal action notification
  • SYSTEM System logic 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

    3. Availability Check Notifications

    Sample Availability Check Notification Body

    POST / HTTP/1.1
    Host: <MERCHANT_NOTIFICATION_URL>
    Content-Type: application/json
    
    {
        "message": "Test availability",
        "timestamp": "2016-07-08T05:06:47.010+00:00"
    }
    

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

    Subscription Statuses

    Status Description
    CREATED Subscription with failed initial charge attempt.
    INACTIVE Subscription created using create inactive call.
    TRIAL Subscription created using create trial call.
    ACTIVE Subscription’s recurring payment process is active.
    FREE Subscription free period is active.
    PROCESSING Subscription renewal is in progress.
    REMOVED Subscription exceeded the retries grace period.
    DELETED Subscription deleted via delete API call, delete MO-SMS, customer care portal or self service portal (my.sla-digital.com).
    CANCELLED Subscription canceled by the system because of customer type changed.
    PURGED Subscription activate call failed.
    SUSPENDED Subscription suspended manually per operator/merchant request.

    Zain KSA Subscription

    Summary

    Create

    Sample Request

    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
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success":
      {
        "type": "subscription",
        "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
        "operator": "zain-ksa",
        "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 a new subscription

    HTTP 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 NOT AVAILABLE FOR ZAIN KSA. 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

    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 KSA 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
  • MOSMS: Mobile Originated SMS action notification
  • PORTAL: Self Service Portal action notification
  • SYSTEM: System logic 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 NOT AVAILABLE FOR ZAIN KSA string optional
    status The transaction status. For Zain KSA will be SUCCESS for successful subscription provisioning operation. string mandatory
    message The error description if any. string optional
    timestamp NOT AVAILABLE FOR ZAIN KSA string mandatory
    transaction_id NOT AVAILABLE FOR ZAIN KSA integer mandatory

    Create Trial

    Zain KSA support pre-configured trial period per service.

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

    Status

    Sample Request

    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
    

    Sample Response (last bill charged successfully)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
       "service": "Shahid Plus",
       "msisdn": "9661116648592",
       "frequency": "weekly",
       "amount": "30.0",
       "currency": "SAR",
       "status": "ACTIVE"
    }
    

    Sample Response (last bill failed to charge)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
       "service": "Shahid Plus",
       "msisdn": "9661116648592",
       "frequency": "weekly",
       "amount": "30.0",
       "currency": "SAR",
       "status": "SUSPENDED"
    }
    

    Get the subscription status.

    HTTP 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. Refer to Subscription Status table. string mandatory
    transactions NOT AVAILABLE FOR ZAIN KSA array optional
    next_payment_timestamp NOT AVAILABLE FOR ZAIN KSA string optional

    Delete

    Sample Request

    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
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success": true
    }
    

    Delete all existing subscriptions for a customer for a specified service.

    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.

    HTTP 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

    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 two main types of subscription notifications:

    1. Recurring Payment Notifications

    NOT AVAILABLE FOR ZAIN KSA.

    We will NOT send notification on each charge attempt for zain ksa customers.

    2. Status Update Notifications

    Sample 1

    POST / HTTP/1.1
    Host: <MERCHANT_NOTIFICATION_URL>
    Content-Type: application/json
    
    {
       "success":{
          "type":"subscription",
          "uuid":"c537bf6a-8603-466c-9eaa-bf6d3faed28c",
          "operator":"zain-ksa",
          "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96626925482",
          "currency":"SAR",
          "amount":"0.3",
          "mode":"API",
          "frequency":"weekly",
          "transaction":{
             "status":"SUSPENDED"
          }
       }
    }
    

    Sample 2

    POST / HTTP/1.1
    Host: <MERCHANT_NOTIFICATION_URL>
    Content-Type: application/json
    
    {
       "success":{
          "type":"subscription",
          "uuid":"c537bf6a-8603-466c-9eaa-bf6d3faed28c",
          "operator":"zain-ksa",
          "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
          "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
          "environment":"production",
          "msisdn":"96626925482",
          "currency":"SAR",
          "amount":"0.3",
          "mode":"PORTAL",
          "frequency":"weekly",
          "transaction":{
             "status":"ACTIVE"
          }
       }
    }
    

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

    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.
  • 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
  • MOSMS Mobile Originated SMS action notification
  • PORTAL Self Service Portal action notification
  • SYSTEM System logic 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 NOT AVAILABLE FOR ZAIN KSA string optional
    status The subscription status. string mandatory

    Axiata Integration

    Summary

    Subscription

    Redirect the customer to https://checkout.sla-alacrity.com/purchase/axiata

    Include the following parameters in the query string:

    Name Description Type Usage
    merchant The merchant URI that identifies your merchant and can be obtained via the Alacrity portal. string mandatory
    service The unique URI for your service which can be obtained via the Alacrity portal. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after checkout. string mandatory
    transaction_id A unique ID generated by you that identifies this transaction. string mandatory

    If any of the above parameters are missing you will be returned to your redirect url as below, except for redirect_url.

    Example Request

    https://checkout.sla-alacrity.com/purchase/axiata?merchant={merchant_uri}&service={service_uri}&transaction_id={transaction_id}&redirect_url={url}

    One Off Charge

    Redirect the customer to https://checkout.sla-alacrity.com/purchase/axiata

    Include the following parameters in the query string:

    Name Description Type Usage
    merchant The merchant URI that identifies your merchant and can be obtained via the Alacrity portal. string mandatory
    service The unique URI for your service which can be obtained via the Alacrity portal. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after checkout. string mandatory
    transaction_id A unique ID generated by you that identifies this transaction. string mandatory
    price The decimal amount that you want to charge numeric mandatory

    If any of the above parameters are missing you will be returned to your redirect url as below, except for redirect_url.

    Example Request

    https://checkout.sla-alacrity.com/purchase/axiata?merchant={merchant_uri}&service={service_uri}&transaction_id={transaction_id}&price={price}&redirect_url={url}

    Success

    If the process is successfully finished you will receive the following via http redirect callback:

    http://your-redirect-url?status=success&transaction_id={transaction_id}&uuid={uuid}

    Errors

    Other errors will be returned to your redirect url and will have the following format:

    http://your-redirect-url/?status=error&message=reason%20for%20the%20error&type=error%20type

    Possible Error Messages

    Unknown Service (invalid_service)

    Unknown Merchant (invalid_merchant)

    Invalid price (invalid_price)

    Invalid Transaction ID (invalid_transaction_id)

    Service is not belong to this merchant (service_not_belong_to_merchant)

    Response from One-Off Charge/Subscription

    One-Off Charge Response Parameters

    One-Off Charge Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success":
      {
        "type": "charge",
        "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
        "operator": "axiata-lk",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "94770000000",
        "currency": "LKR",
        "amount": "0.5",
        "transaction":
        {
          "status": "CHARGED",
          "timestamp": "2015-08-26T10:58:12.026+08:00",
          "transaction_id": "1910173"
        }
      }
    }
    

    One-Off Charge Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "type": "charge",
        "operator": "axiata-lk",
        "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "94770000000",
        "currency": "LKR",
        "amount": "0.5",
        "transaction":
        {
          "status": "ACCOUNT_NOT_FOUND",
          "timestamp": "2015-08-26T10:59:10.000+08:00",
          "transaction_id": "1910174"
        }
      }
    }
    
    Name Description Type Usage
    type An indication of the transaction type. Below is a list of 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 charge. string optional
    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 possible values:
  • test: sandbox credentials.
  • preproduction: uat credentials.
  • production: live credentials.
  • string mandatory
    msisdn The subscribers MSISDN that has been refunded. string mandatory
    currency Currency code as defined in [ISO4217]. string mandatory
    amount The decimal amount that has been refunded. numeric mandatory
    status The transaction status. A list of 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 transactions identifier. integer mandatory

    Subscription Response Parameters

    Subscription Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "success":
      {
        "type": "subscription",
        "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
        "bill_id": "6ab07c272683N",
        "operator": "axiata-lk",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "94770000000",
        "currency": "LKR",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "next_payment_timestamp": "2015-08-27T10:58:12.026Z",
        "transaction":
        {
          "status": "CHARGED",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    

    Subscription Sample Response (failed)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "error":
      {
        "type": "subscription",
        "operator": "axiata-lk",
        "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
        "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
        "environment": "test",
        "msisdn": "94770000000",
        "currency": "LKR",
        "amount": "0.5",
        "mode": "API",
        "frequency": "daily",
        "transaction":
        {
          "status": "ACCOUNT_NOT_FOUND",
          "message": "Account could not be found",
          "timestamp": "2015-08-26T10:58:12.026+00:00",
          "transaction_id": "1910173"
        }
      }
    }
    
    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 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.
  • 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
  • MOSMS: Mobile Originated SMS action notification
  • PORTAL: Self Service Portal action notification
  • SYSTEM: System logic 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 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

    Subscription Status

    You may refer to Subscription status

    Subscription Delete

    You may refer to Subscription delete

    HTTP Notifications

    You may refer to HTTP notification

    Header Enrichment

    Alacrity provides an API for you to retrieve the customers MSISDN via header enrichment (if it is available).

    This is a two step process:

    1. Redirect the user to Alacrity where we will attempt to obtain the MSISDN.
    2. Retrieve the MSISDN via the API.

    Request

    Redirect the customer to:

    http://msisdn.sla-alacrity.com/redirect?redirect_url={redirect_url}&uri={uri}&transaction_id={transaction_id}

    Parameters

    Name Description Type Usage
    redirect_url Your URL that we redirect the end customer back to after msisdn detection. string mandatory
    uri The Alacrity merchant uri that identifies which merchant this transaction belongs to. string mandatory
    transaction_id A unique transaction id generated by you. integer mandatory

    If any of the above parameters are missing you will receive a 400 Bad Request

    Errors

    Other errors will be returned to your redirect url and will have the following format:

    http://your-url.com/?status=error&message=reason%20for%20the%20error&transaction_id={transaction_id}

    Possible Error Messages

    Unknown merchant

    Request not from operator gateway IP

    MSISDN not detected

    We will always return the transaction_id so that you can identify the transaction

    Success

    If the MSISDN is successfully detected and saved you will receive the following via redirect:

    http://your-url?status=success&transaction_id={transaction_id}

    MSISDN Retrieval

    Sample Request

    GET /authenticate/msisdn?
    transaction_id=19235&
    uri=partner:1b0a715f-27c5-46c2-9e97-00748dca334f HTTP/1.1
    Host: msisdn.sla-alacrity.com
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Accept: application/json
    

    Sample Response (success)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
       "msisdn_protection":{
          "msisdn": "353867676767"
       }
    }
    

    Sample Response (error)

    HTTP/1.1 410 Gone
    

    Retrieve MSISDN for specific transaction

    HTTP Request

    GET /authenticate/msisdn?transaction_id={ID}&uri={URI}

    Request Parameters

    Name Description Type Usage
    transaction_id A unique identifier to the current transaction. This value will be used to retrieve the MSISDN. string mandatory
    uri The Alacrity merchant uri that identifies which merchant this transaction belongs to. string mandatory

    Transaction Status

    List of transaction status

    Status Description Usage
    CHARGED Transaction charged successfully charge
    REFUNDED Transaction refunded successfully refund
    WAITING Transaction waiting customer action (v3.0) charge
    INSUFFICIENT_FUNDS Subscriber has insufficient funds charge
    INSUFFICIENT_BALANCE Subscriber balance is below minimum requirements charge
    LIMIT_EXCEEDED Transaction exceeded operator limit charge
    INVALID_ACCOUNT Subscriber has invalid account charge, refund
    INACTIVE_ACCOUNT Subscriber has inactive account charge, refund
    ACCOUNT_NOT_FOUND Subscriber account not found charge, refund
    ACCOUNT_SUSPENDED Subscriber account suspended charge, refund
    CORPORATE_ACCOUNT Subscriber has invalid account charge, refund
    CUSTOMER_CHANGED Subscriber has invalid account subscription
    INVALID_PIN Invalid PIN provided subscription
    EXPIRED_ACR Invalid ACR provided subscription
    NOT_SUPPORTED Operation not supported refund
    ERROR Transaction error charge, refund
    SYSTEM_ERROR System error charge, refund

    Errors

    Sample Error Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
       "error":{
          "category": "Authorization",
          "code": "1001",
          "message": "Basic Auth required. Invalid credentials"
       }
    }
    

    Error messages are returned in HTTP response. The body of the response contains the details of the error in JSON format.

    The following attributes are returned as part of the error content

    Attribute Description
    category A string which groups errors based on the error handling routine that is required.
    code A more specific code allowing you to handle the specific errors.
    message A descriptive information about the error. This is for developer(/merchant) consumption and should not be used for showing errors to your customers.

    The following are the list of codes grouped based on category.

    Category Code Message Possible Cause
    Authorization 1001 Basic Auth required. Invalid credentials Wrong or missing authorization token in HTTP header
    Authorization 1002 Your IP address {ip} is not in the whitelist {whitelist}. You can add it via the Management Portal Wrong or missing IP Allow list in API access page in portal
    Authorization 1003 Rate limit exceeded, You have exceeded the number of requests per {period}
    Request Validation 2000 Invalid parameter {parameter} value {value}
    Request Validation 2001 Missing required parameters {params} Missing mandatory parameters in HTTP request
    Request Validation 2002 Unknown Merchant with URI {uri} Wrong merchant parameter value
    Request Validation 2003 Unknown Operator for MSISDN {msisdn} Wrong country dial code in MSISDN parameter value
    Request Validation 2004 Campaign with uri {campaign_uri} is not valid Wrong campaign parameter value or campaign not approved
    Request Validation 2005 {operator} does not accept charges in {currency} Unsupported currency
    Request Validation 2006 {operator} has a max charge amount of {max} {currency} Amount parameter value exceed the purchase limit
    Request Validation 2007 Correlator repeated. Possible duplicate transaction Correlator parameter value has been used before
    Request Validation 2008 Invalid PIN Wrong PIN parameter value
    Request Validation 2009 Invalid Notification URL Wrong notification url value in service settings
    Request Validation 2010 Invalid frequency requested. Valid values are: {frequencies} Wrong frequency value in service settings
    Request Validation 2011 Subscription not found Wrong uuid value or no subscription available
    Request Validation 2012 Subscription {campaign} already exists with {operator} for this customer Create duplicates subscription
    Request Validation 2013 No valid agreement with {operator} for {environment} environment Service agreement not approved
    Request Validation 2014 {operator} does not support partial refund. Refunded amount ({refund_amount}) did not match original amount ({original_amount}) Refund amount not equal to charge amount
    Request Validation 2015 Charge amount must be greater than zero Charge amount less than zero
    Request Validation 2016 Invalid (charge) parameter value. should be true for subscriptions offers free trials Create trial subscription with charge parameter value is false
    Request Validation 2017 Period value is invalid Free coupons API request with not allowed period value
    Request Validation 2018 Subscription not in inactive mode Subscription status value is not inactive
    Request Validation 2019 Subscription not active Subscription status value is not active
    Request Validation 2021 Subscription not in paused mode Subscription status value is not removed
    Request Validation 2022 Invalid SMS message SMS MT not delivered
    Request Validation 2023 {language} is not supported for {operator} Wrong language or the it is not supported for this operator
    Request Validation 2024 {msisdn} is not a valid MSISDN or ACR Wrong MSISDN or ACR parameter value
    Request Validation 2025 Account not found The customer is not exist in our system
    Request Validation 2026 {operator} has a min charge amount of {min} {currency} Amount parameter value exceed the purchase limit
    Request Validation 2027 Refund amount must be less than zero Refund amount greater or equal to zero
    Request Validation 2028 Offer not provisioned
    Request Validation 2029 Customer may not eligible. Please call isEligible before dataProvision.
    Request Validation 2030 Customer {msisdn} is blocked from using campaign with uri {campaign_uri}“
    Request Validation 2031 Trial value must be over zero
    Request Validation 2032 Subscription creation exceeded the limit
    PIN API 3001 PIN sending failed SMS MT not delivered
    Invalid PIN 4001 PIN has been used already Proved PIN value reused
    Invalid PIN 4002 PIN has expired Provided PIN value TTL expired
    Invalid PIN 4003 PIN not found Wrong pin parameter value
    Free Trial 5001 {service_name} service doesn’t support Free trial for subscriptions Trial subscriptions not activated on service settings
    Free Trial 5002 Free trial period cannot exceed 30 days Trial parameter value greater than 30
    Free Period 5501 {service_name} service doesn’t support Free periods for subscriptions Free coupons for subscription not activated in service settings
    Free Period 5502 Free period cannot exceed {max_free_days} days
    Service Incomplete 6001 Your service is missing notification_url Notification url value is empty in service settings
    Service Incomplete 6002 Your service is missing amount Subscription amount is empty in service settings
    Service Incomplete 6003 Your service retries grace period is invalid. Grace period should not exceed 30 days and number of retries should not exceed 3 times per day Wrong grace period value in service settings
    Service Incomplete 6004 Your are not allowed to use this service
    Token Error 7001 Token {token} could not be found”
    Token Error 7001 Token {token} has been already used"
    Token Error 7002 No MSISDN for token {token}“
    Token Error 7003 Amount {amount} doesn’t match the original amount provisioned with Token {token}”
    Token Error 7004 Token {token} doesn’t belong to campaign with uri {campaign_uri}“
    SMS API 8001 SMS sending failed SMS MT not delivered

    SDKs

    Alacrity SDKs are set of programming language libraries to assist developers in integrating with Alacrity HTTP API.

    CSharp

    coming soon

    Java

    coming soon

    PHP

    coming soon

    Two Click

    The Two Click flow allows you to charge or subscribe a customer without a PIN or SMS. We host a confirmation page where the customer just needs to click Confirm and we obtain their MSISDN via Header Enrichment.

    Overview

    twoclick twoclick

    Redirect

    Redirect the customer to http://msisdn.sla-alacrity.com/redirect

    Include the following parameters in the query string:

    Name Description Type Usage
    transaction_id A unique ID generated by you that identifies this transaction. string mandatory
    uri The Alacrity merchant uri that identifies which merchant this transaction belongs to. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after attempting header enrichment. string mandatory

    Example Request

    http://msisdn.sla-alacrity.com/redirect?redirect_url={redirect_url}&uri={uri}&transaction_id={transaction_id}

    Success Response

    http://your-callback-url.com/callback?status=success&transaction_id=19826Hghs546gg009364

    Error Response

    http://your-callback-url.com/callback?status=error&messge=Request not from operator gateway IP&transaction_id=19826Hghs546gg009364

    Redirect to confirmation page

    Redirect the customer to http://msisdn.sla-alacrity.com/twoclick/confirm

    Include the following parameters in the query string:

    Name Description Type Usage
    transaction_id Please use the same transaction ID as used in previous call. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after attempting header enrichment. string mandatory
    uri Your Merchant URI that uniquely identifies your Merchant within Alacrity. string mandatory
    service Your Service URI that uniquely identifies your Service within Alacrity. string mandatory

    Example Request

    http://msisdn.sla-alacrity.com/twoclick/confirm?transaction_id=19826Hghs546gg009364&redirect_url=http://your-callback-url.com/callback&service=campaign://dgsha-23432-fdsfds-99432&uri=partner://dasdsa-342324-dgssg-87876

    Receive Token

    The customer will be presented with the confirmation page and have the option of click Confirm or Cancel. The customer will then be redirected back to your redirect url and the url will contain the result.

    Example:

    Success:

    http://your-redirect-url/?status=success&token=TOKEN:4324gh-fwe7we-dsf-342hh

    Error:

    http://your-redirect-url/?status=error&message=cancelled

    Possible values for message are:

    cancelled
    internal_error
    service_merchant_incorrect
    invalid_service
    merchant_not_found
    invalid_transaction_id
    operator_unsupported
    not_found&param=service (missing required parameters)

    Use Token with API

    Use the token returned to your redirect url to call the Alacrity API’s. Usually you would need to provide msisdn AND pin when calling the Alacrity API’s. If you have a token obtained from the Two Click flow above you can send this value in the msisdn field and omit the pin.

    Example:

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

    Checkout

    Alacrity Checkout provides a complete customer purchase experience. Redirect your customers to our Checkout page and we will authenticate them, confirm their purchase and return a unique token to you which you can use with our Subscription and Charge API’s.

    Authentication

    Authentication is done via HTTP Basic Auth. In the examples below username and password are included as part of the requested URL. Credentials can be created via the Alacrity portal.

    https://username:password@checkout.sla-alacrity.com/purchase

    Authentication Params

    Name Description Type Usage
    username The Alacrity API access credential username that belong to the merchant. string mandatory
    password The Alacrity API access credential password that belong to the merchant. string mandatory

    Subscription

    Redirect the customer to https://checkout.sla-alacrity.com/purchase

    Include the following parameters in the query string:

    Name Description Type Usage
    merchant The merchant URI that identifies your merchant and can be obtained via the Alacrity portal. string mandatory
    service The unique URI for your service which can be obtained via the Alacrity portal. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after checkout. string mandatory
    locale The language code as defined in [ISO639-1]. The chosen language will be used to display the UI string optional

    If any of the above parameters are missing you will be returned to your redirect url as below, except for redirect_url.

    Example Request

    https://{username}:{password}@checkout.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}

    One Off Charge

    Redirect the customer to https://checkout.sla-alacrity.com/purchase

    Include the following parameters in the query string:

    Name Description Type Usage
    merchant The merchant URI that identifies your merchant and can be obtained via the Alacrity portal. string mandatory
    service The unique URI for your service which can be obtained via the Alacrity portal. string mandatory
    redirect_url Your URL that we will automatically redirect the customer back to after checkout. string mandatory
    locale The language code as defined in [ISO639-1]. The chosen language will be used to display the UI string optional
    price The decimal amount that you want to charge numeric mandatory

    If any of the above parameters are missing you will be returned to your redirect url as below, except for redirect_url.

    Example Request

    https://{username}:{password}@checkout.sla-alacrity.com/purchase?merchant={merchant_uri}&service={service_uri}&redirect_url={url}&price={price}

    Success

    If the process is successfully finished you will receive the following via http redirect callback:

    http://your-redirect-url?status=success&token={token}

    Errors

    Other errors will be returned to your redirect url and will have the following format:

    http://your-redirect-url/?status=error&message=reason%20for%20the%20error&type=error%20type

    Possible Error Messages

    Unknown Service (invalid_service)

    Unknown Merchant (invalid_merchant)

    Invalid price (invalid_price)

    Service is not belong to this merchant (service_not_belong_to_merchant)

    Use Token with API

    Use the token returned to your callback redirect url to call the Alacrity API’s. Usually you would need to provide msisdn AND pin when calling the Alacrity API’s. If you have a token obtained from Checkout you can send this value in the msisdn field and omit the pin.

    Example Request

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

    API Changelog

    API v2.2.1

    2016-05-31

    API v2.2.0

    2015-12-01

    2016-04-20

    API v1.0.0

    FAQ

    Should I send MSISDNs with or without country code on API requests?

    You should always ensure that API requests include the country code in your msisdns. An error shall be raised if you send the wrong country code for the service you wish to use.

    Is there any Dummy MSISDN to use for Sandbox environment?

    No. In the Sandbox environment you have to provision any MSISDN you wish to use via the provision API call. Provisioning only lasts for 4 hours.

    How do I know that my service has been approved?

    You will receive an email notification about service approval.

    Can I execute transactions on unapproved services created on the Alacrity portal?

    You can execute transactions for unapproved services in the Sandbox environment. However, you cannot execute transactions on UAT or live environments until a service is approved.

    In the sandbox environment, since the PIN code defaults to 000000, do I need to call the PIN API?

    The PIN API must be called otherwise you will receive an error.

    Do I get a notification when I call the create subscription API?

    No but you will get a subscription creation notification if a service is created by another mechanism such as an SMS subscribtion message.

    I am testing in the Sandbox Environment but I have not received any notifications. What could be wrong?

    In the Sandbox Environment for typical test scenarios you may only receive notifications on the renewal of a subscription. However, you can contact the SLA Integration team at Integration@SLA-LTD.COM to test subscription deletion scenarios.

    Do I need to support Subscription via SMS?

    Most operators expect support for subscription and unsubscribe via SMS messages sent to a special short code. Alacrity supports this functionality. If you have a service that does not wish to use this functionality then you should discuss with the SLA Integration team at Integration@SLA-LTD.COM

    Can my service support unsubscribe via SMS and not subscribe?

    No you need to support both because a customer may try to use the SMS subscribe option.

    How do I know when my service is integrated correctly?

    You should test your service in the Sandbox environment using scenarios such as service subscription, renewal and deletion. You can then consult with the SLA Integration team at Integration@SLA-LTD.COM who can review your transactions. You should also provide a test report and a Service User Guide.

    I require MSISDNs to be whitelisted to use my service before it goes live. How should I whitelist MSISDNs for testing?

    Please contact the SLA Integration team at Integration@SLA-LTD.COM

    Can I use an IP range to identify the operator a customer is using?

    Although this can be done it is not recommended as operators do not guarentee that they will not change their IP range in the future.

    What is the Alacrity server IPs that send the HTTP notifications?

    54.194.110.57 and 54.194.89.16. You may need to whitelist these addresses on your servers to receive Alacrity notifications.

    When defining my notification url, are there any Port restrictions?

    There are no special requirements for Notification URL however we recommend that you use one of the following ports: 80, 443, 8310, 19321, 123, 20540 and 8080