Subscription API Usage
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 Operator's requirements for subscription services. Alacrity also sends notifications to the Merchant to inform you of updates and charges to a subscription.
All HTTP request parameters should be passed in URL Query String - query_params.
Create
Create a new subscription with an initial charge attempt using the Create API.
Info
If your service does not have a free trial then if during subscription creation the charge attempt fails (say insufficient balance) then the subscription is NOT created. This means that subsequent attempts to charge the user later do not occur. If the service has a free trial then a subscription is created and the user is part of the renewal re-charge process.
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 (or a Token). | 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 | 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. | string | optional |
fraud_token | If you are hosting the landing page you may be required to use our fraud prevention API and include a valid/checked token in this request | string | optional |
Info
A token generated via Checkout or Hosted Button can be used instead of msisdn. Also in this case a pin is not required.
Response Parameters
Name | Description | Type | Usage |
---|---|---|---|
type | An indication of the transaction type. Below is a list of the possible values: | 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: | 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: | string | mandatory |
frequency | The frequency of subscription renewal. Below is a list of the possible values: | 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 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 transaction's identifier. | integer | mandatory |
POST /v2.2/subscription/create?
msisdn=96526xxxxx&
pin=12345&
campaign=campaign:940d351138df895e8dedf51e5d7b90xxxxx0&
merchant=partner:02c76113-0ca7-4xxxaed-xxx-75267bf85e82&
lanauge=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpxxxIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success":
{
"type": "subscription",
"uuid": "c537bf6a-xxxx-xxxx-9eaa-bf6d3faed28c",
"bill_id": "6ab07c272683N",
"operator": "zain-kw",
"merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
"campaign": "campaign:940d351138df895e8dxxxx5d7b90788cdc23d0",
"environment": "test",
"msisdn": "965269xxxx",
"currency": "KWD",
"amount": "0.5",
"mode": "API",
"frequency": "daily",
"next_payment_timestamp": "2015-08-27T10:58:12.026Z",
"transaction":
{
"status": "CHARGED",
"bill_id": "6ab07c272683N",
"timestamp": "2015-08-26T10:58:12.026+00:00",
"transaction_id": "191xxx"
}
}
}
Success
Please note that if the result of the charge attempt is success the next scheduled charge will be triggered by Alacrity automatically. You will be notified by a HTTP notification.
Info
You do not receive a HTTP notification for a create call success or failure. That detail is in the create call response.
Warning
Please note that if the result of the charge attempt is failed for any reason the subscription WILL NOT be created.
You can view your created subscription on Alacrity at https://sla-alacrity.com/partner/subscriptions .
Create Trial
Create a new subscription with free trial period using the Create API.
HTTP Request
POST /v2.2/subscription/create?msisdn={msisdn}&pin={pin}&campaign={campaign}&merchant={merchant}&trial={trial_days}&language={language}&trial_once={true/false}
Request Parameters
Name | Description | Type | Usage |
---|---|---|---|
msisdn | The subscriber MSISDN that you want to create the subscription for (or a Token). | 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 | 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 |
trial_once | A flag indicates whether Alacrity charge the user directly if they got the trial before. | 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. | string | optional |
Info
A token generated via Checkout or Hosted Button can be used instead of msisdn. Also in this case a pin is not required.
POST /v2.2/subscription/create?
msisdn=9652692xxxx&
pin=12345&
campaign=campaign:940d351138df895e8dedf51e5d7b90788cdc23d0&
merchant=partner:02c76113-0ca7-xxxx-xxxx-75267bf85e82&
trial=30&
trial_once=true&
language=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjxxxxuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"uuid": "c537bf6a-xxxx-xxxx-9eaa-bf6d3faed28c",
"msisdn": "9652692xxxx"
}
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"
}
}
Success
Please note that the subscription status will become trial. Once the free trial days have expired, Alacrity will automatically begin charging the subscription. You will be notified by a HTTP notification.
Please note that if you send trial_once with true value, and the user has already taken the trial before, Alacrity will automatically begin charging the subscription, and the subscription will not be in trial status, and the response will be similar to create.
All HTTP request parameters should be passed in URL Query String - query_params.
Info
You do not receive a HTTP notification for a create call success or failure. That detail is in the create call response.
Warning
Please note that your service needs to be approved to offer free trials or you will receive an error.
You can view your created subscription on Alacrity at https://sla-alacrity.com/partner/subscriptions .
Create Inactive
Create a new subscription without an initial charge attempt using the Create API. 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 (or a Token). | 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 | 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. | string | optional |
POST /v2.2/subscription/create?
msisdn=9652692xxxx&
pin=12345&
campaign=campaign:940d351138df895e8dexxxxd7b90788cdc23d0&
merchant=partner:02c76113-0ca7-xxxx-xxxx-75267bf85e82&
charge=false&
language=ar HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpxxxxcGVuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"uuid": "c537bf6a-xxxx-xxxx-9eaa-bf6d3faed28c",
"msisdn": "9652692xxxx"
}
Warning
Please note that this request will create an inactive subscription where the renewal process will not start until the subscription is activated.
Activate
Update an inactive subscription to active with an initial charge attempt using the activate API.
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: | 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 credentials belong to. Below is a list of the possible values: | 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: | string | mandatory |
frequency | The frequency of subscription renewal. Below is a list of the possible values: | 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 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 transaction's identifier. | integer | mandatory |
POST /v2.2/subscription/activate?
uuid=c537bf6a-8603-xxxx-xxxx-bf6d3faed28c HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcxxxxIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success":
{
"type": "subscription",
"uuid": "c537bf6a-8603-xxxx-xxxx-bf6d3faed28c",
"bill_id": "6ab07c272683N",
"operator": "zain-kw",
"merchant": "partner:02c76113-xxxx-4aed-88e2-75267bf85e82",
"campaign": "campaign:940d351xxxdf895e8dedf51e5d7b90788cdc23d0",
"environment": "test",
"msisdn": "9652692xxxx",
"currency": "KWD",
"amount": "0.5",
"mode": "API",
"frequency": "daily",
"next_payment_timestamp": "2015-08-27T10:58:12.026Z",
"transaction":
{
"status": "CHARGED",
"bill_id": "6ab07c272683N",
"timestamp": "2015-08-26T10:58:12.026+00:00",
"transaction_id": "191xxxx"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"error":
{
"type": "subscription",
"operator": "zain-kw",
"merchant": "partner:02c76113-0ca7-xxxx-xxxx-75267bf85e82",
"campaign": "campaign:940d351138dfxxxxedf51e5d7b90788cdc23d0",
"environment": "test",
"msisdn": "9652692xxxx",
"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": "191xxx"
}
}
}
Success
Please note that if the result of the charge attempt is success the subscription status will become active and the next scheduled charge will be triggered by Alacrity automatically.
Warning
Please note that if the result of the charge attempt is failed for any reason the subscription status will become purged.
Resume
Activate a subscription that was removed because it exceeded the retries grace period for failed recurring payments using the resume API.
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 |
POST /v2.2/subscription/resume?
uuid=c537bf6a-8603-xxxx-xxxx-bf6d3faed28c HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGxxxHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"uuid": "c537bf6a-8603-xxxx-xxxx-bf6d3faed28c"
}
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"
}
}
Success
Please note that the subscription status will become active and the next scheduled charge will be triggered by Alacrity automatically.
Warning
Please note that you can not resume a subscription that already exceeded 30 days of retries or 3 retry per day.
Free Period (Coupons)
Activate a free period (free coupon) for an active subscription using the free API.
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 |
Info
period=2
it will skip:
2
days fordaily
subscriptions.
2
weeks (14 days
) forweekly
subscriptions.
2
fortnights (28 days
) forfortnightly
subscriptions.
2
months (60 days
) formonthly
subscriptions.
POST /v2.2/subscription/free?
uuid=c537bf6a-8603-xxxx-xxxx-bf6d3faed28c&
period=2 HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpxxxcGVuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"uuid": "c537bf6a-8603-xxxx-xxxx-bf6d3faed28c"
}
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"
}
}
Success
Please note that the subscription status will become free. Once the free period has expired, Alacrity will automatically begin charging the subscription.
Warning
Please note that your service needs to be approved to offer free periods (free coupons) or you will receive an error.
Status
Get the subscription status using the status API.
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 |
---|---|---|---|
uuid | The universally unique identifier for the subscription. | string | mandatory |
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: | 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 |
next_payment_timestamp | The timestamp for the next scheduled renewal in UTC time standard. | string | optional |
transactions | List of all charge transactions that belong to this subscription. | array | optional |
POST /v2.2/subscription/status?
uuid=c537bf6a-8603-xxxx-xxxx-bf6d3faed28c HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbxxxcGVuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uuid": "7a34ca62-2453-42bc-9b04-e9e3d7206251",
"service": "Shahid Plus",
"msisdn": "965111xxxx",
"frequency": "weekly",
"amount": "30.0",
"currency": "KWD",
"status": "ACTIVE",
"next_payment_timestamp": "2016-06-14 02:59:00 UTC",
"transactions": [
{
"transaction_id": "191xxx",
"status": "CHARGED",
"amount": "30.0",
"billid": "84dc29e8xx8",
"timestamp": "2016-05-31 02:36:36 UTC"
},
{
"transaction_id": "192xx",
"status": "INSUFFICIENT_FUNDS",
"amount": "30.0",
"billid": "3d146bc5xxx",
"timestamp": "2016-06-07 02:58:00 UTC"
},
{
"transaction_id": "192xxx",
"status": "CHARGED",
"amount": "4.285",
"billid": "3d146bcxxx3",
"timestamp": "2016-06-07 02:59:00 UTC"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"error":
{
"category": "Request Validation'",
"cdoe": "2011",
"message": "Subscription not found"
}
}
Latest
Get the latest subscription for specific MSISDN.
HTTP Request
POST /v2.2/subscription/latest?msisdn={msisdn}&campaign={campaign}&merchant={merchant}
Request Parameters
Name | Description | Type | Usage |
---|---|---|---|
msisdn | The subscriber MSISDN that you want to get the latest subscription information for (or a Token). | 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 |
Response Parameters
Name | Description | Type | Usage |
---|---|---|---|
uuid | The universally unique identifier for the subscription. | string | mandatory |
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: | 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 |
next_payment_timestamp | The timestamp for the next scheduled renewal in UTC time standard. | string | optional |
transactions | List of all charge transactions that belong to this subscription. | array | optional |
POST /v2.2/subscription/latest?msisdn=965111xxxx&
campaign=campaign:940d351138df895e8dedf51e5d7xxxcdc23d0&
merchant=partner:02c76113-0ca7-xxxx-88e2-752xxxf85e82
HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbxxxcGVuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uuid": "7a34ca62-2453-42bc-9b04-e9e3d7206251",
"service": "Shahid Plus",
"msisdn": "965111xxxx",
"frequency": "weekly",
"amount": "30.0",
"currency": "KWD",
"status": "ACTIVE",
"next_payment_timestamp": "2024-07-31T13:00:43Z",
"transactions": [
{
"transaction_id": "191xxx",
"status": "CHARGED",
"amount": "30.0",
"billid": "84dc29e8xx8",
"timestamp": "2016-05-31 02:36:36 UTC"
},
{
"transaction_id": "192xx",
"status": "INSUFFICIENT_FUNDS",
"amount": "30.0",
"billid": "3d146bc5xxx",
"timestamp": "2016-06-07 02:58:00 UTC"
},
{
"transaction_id": "192xxx",
"status": "CHARGED",
"amount": "4.285",
"billid": "3d146bcxxx3",
"timestamp": "2016-06-07 02:59:00 UTC"
}
],
}
Delete
Delete all existing subscriptions for a customer for a specified service using the delete API.
This is an asynchronous call which means you will receive a success response even when subscription is not existed.
A HTTP notification will be sent once the subscription status changes 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 (or a Token). | string | mandatory |
campaign | The Alacrity service URI that identifies the service that this transaction belongs to. | string | mandatory |
merchant | The Alacrity merchant URI that identifies which merchant this transaction belongs to. | string | mandatory |
POST /v2.2/subscription/delete?
msisdn=965269xxx&
campaign=campaign:940d351138df895e8dedf51e5d7xxxcdc23d0&
merchant=partner:02c76113-0ca7-xxxx-88e2-752xxxf85e82 HTTP/1.1
Host: api.sla-alacrity.com
Authorization: Basic QWxhZGRpbjxxxGVuIHNlc2FtZQ==
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true
}
Warning
Please note that:
- if you subscribe with Number 09009000 then you have to use the same Number 09009000 to unsubscribe.
- if you subscribe with Token TOKEN:XXXX then you have to use the same Token TOKEN:XXXX to unsubscribe.
- if you subscribe with Acr ACR:XXXX then you have to use the same Acr ACR:XXXX to unsubscribe.
if you subscribe with Number and you tried to unsubscribe with ACR or Token you will get an error message that says Subscription not found
Updated 4 months ago