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 recurring payment - a payment due at a regular interval over time.

📘

Info

Please note that recurring payments are charged without any involvement from the Merchant.

Proration Recurring Payments

(Also called Partial Charging)

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

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

FrequencyPartial PeriodPartial Amount
DailyNANA
Weekly1 DayFull Amount / 7
Fortnightly1 DayFull Amount / 14
Monthly1 WeekFull Amount / 4

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

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

{
   "success":{
      "type":"subscription",
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "bill_id":"6ab07c272683N",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
      "environment":"production",
      "msisdn":"96596619582",
      "currency":"KWD",
      "amount":"1.5",
      "mode":"PARTIAL",
      "frequency":"monthly",
      "duration":7,
      "transaction":{
         "status":"CHARGED",
         "bill_id":"6ab07c272683N",
         "timestamp":"2016-07-08 04:40:15 +0000",
         "transaction_id":"6563403"
      }
   }
}

📘

Info

Please note that your service needs to be approved to enable partial charging otherwise the insufficient funds recurring payments will be handled as failed payments.

Step-Down Recurring Payments

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

An example of a step-down charging:

Service PolicyValue
FrequencyDaily
Full Price$1
Step-down amounts$0.5 $0.15 $0.05
Step-down grace periodretry 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 3 days from the last successful partial charge and if the balance is not obtained during that time, we will automatically unsubscribe the customer.

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

{
   "success":{
      "type":"subscription",
      "uuid": "c537bf6a-8603-466c-9eaa-bf6d3faed28c",
      "bill_id":"6ab07c272683N",
      "operator":"zain-kw",
      "merchant": "partner:02c76113-0ca7-4aed-88e2-75267bf85e82",
      "campaign": "campaign:940d351138df895e8dedf51e5d7b90788cdc23d0",
      "environment":"production",
      "msisdn":"96596619582",
      "currency":"KWD",
      "amount":"0.05",
      "mode":"STEP_DOWN",
      "frequency":"monthly",
      "duration":7,
      "transaction":{
         "status":"CHARGED",
         "bill_id":"6ab07c272683N",
         "timestamp":"2016-07-08 04:40:15 +0000",
         "transaction_id":"6563403"
      }
   }
}

📘

Info

Please note that your service needs to be approved to enable step-down charging otherwise the insufficient funds recurring payments will be handled as failed payments.

Failed Payment Handling

When a recurring payment fails:

  • Alacrity will automatically retry to charge the customer according to a retries grace period that you can define in your service.
  • The default retries grace period is to retry charging the customer 3 times per day for 30 days. Some Operators have different rules. Consult the Alacrity Integration Team if you require this detail.
  • When the retries grace period is exceeded, the subscription will be removed and the Merchant will be notified via http notification.
  • Merchants are allowed to resume a removed subscription unless it has exceeded a total of 30 days of retries.
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"
      }
   }
}