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.

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:

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"
      }
   }
}

Split Billing

Currently only available in Movitel Mozambique.

If a customer does not have enough credit due to insufficient funds:

• Alacrity will attempt to charge a new amount which is equal to half of the initial price.
• Alacrity will continue to retry the halved amounts during a shorter retry period. For Movitel Mozambique this retry period is 6 times a day for 30 days; which is once every 4 hours.
• Alacrity will keep retrying at the halved amounts until two half amounts have been obtained during the same billing period. For example: For daily subscriptions - Two halved amounts within the same 24 hour period. For weekly subscriptions - Two halved amounts within the same weekly period, For Monthly - Two halved amounts within the same monthly period.
• Once a full amount has been obtained within the same period for a full renewal, Alacrity will revert back to renewing at the original price.

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.5",
      "mode":"SPLIT_BILLING",
      "frequency":"daily",
      "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 split billing charging otherwise the insufficient funds recurring payments will be handled as failed payments.