Recurring payments

In case you are running a subscription business model, Fortumo Unified SDK provides you simple solution to process recurring charges. During integration you will have the flexibility of specifying all necessary details for processing the subscription, such as what is the price of your service at a given period of time.

In order to help you with user acquisition, Fortumo Unified SDK also provides you an option to offer your users free trials or a promotional price for a specified time period.

Starting subscriptions

Starting a subscription does not differ significantly from initializing a one-time payment. For every subscription you will need to generate a custom JSON Web Token that includes all necessary details for starting the subscription. Below you will find examples of different subscription setups, including simple subscription integration, subscriptions with free trials and also subscriptions with a promotional price.

Messaging

In live, after every payment/subscription an SMS message is sent to the end-user notifying him whether the payment was successful. There are different types of sms messages(reminders, failed payments, subscription started etc.) that can be sent ant it varies depending on operator or ewallet requirements. For ewallets, messages are managed within the wallet.

Simple subscription flow

With simple subscription integration you will specify one standard price that users need to pay for your service every period. With such integration, consumers start paying the full price for your service from the very first day they subscribe.

Simple subscription

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "iss": "d3ad608d0a1729727a3eb6bc0892b427", 
    "exp": "1988326400", 
    "sub": "hdcb", 
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "00001",
    "country_code": "EE",
    "channel_code": "sandbox-ee",
    "urls": {
        "subscription_callback": "https://example.com/subscriptions",
        "redirect": "https://example.com/payment-complete",
        "unsubscription_redirect": "https://example.com/unsubscribe-complete"
    },
    "item_description": "Premium Joy Subscription",
    "operation_reference": "session001",
    "subscription": {
        "price": {
            "amount": 4.99,
            "currency": "EUR"
        },
        "duration": 30,
        "unit": "days"
    }
}

Subscription with free trial

With free trial you will specify the period that users will get for free and the full price after that. With such integration, consumers start paying the full price after the free trial has ended. Consumers will be able to get the amount of free trials that you defined.

Subscription with free trial

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    "iss": "d3ad608d0a1729727a3eb6bc0892b427", 
    "exp": "1988326400", 
    "sub": "hdcb", 
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "00001",
    "country_code": "EE",
    "channel_code": "sandbox-ee",
    "urls": {
        "subscription_callback": "https://example.com/subscriptions",
        "redirect": "https://example.com/payment-complete/",
        "unsubscription_redirect": "https://example.com/unsubscribe-complete"
    },
    "item_description": "Premium Joy Subscription",
    "operation_reference": "session001",
    "subscription": {
        "price": {
            "amount": 4.99,
            "currency": "EUR"
        },
        "duration": 30,
        "unit": "days",
        "promotion": {
            "price": {
                "amount": 0.00,
                "currency": "EUR"
            },
            "free_trial_limit": 2,
            "duration": 30,
            "unit": "days",
            "cycles": 3
        }
    }
}

Subscription with promotion

With promoption you will specify the promotion period in which users will get the service at a discount. With such integration, consumers start paying the discount amount at the start and will continue paying full price after the promotion period has ended.

Subscription with promotion

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "iss": "d3ad608d0a1729727a3eb6bc0892b427", 
    "exp": "1988326400", 
    "sub": "hdcb", 
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "00001",
    "country_code": "EE",
    "channel_code": "sandbox-ee",
    "urls": {
        "subscription_callback": "https://example.com/subscriptions",
        "redirect": "https://example.com/payment-complete/",
        "unsubscription_redirect": "https://example.com/unsubscribe-complete"
    },
    "item_description": "Premium Joy Subscription",
    "operation_reference": "session001",
    "subscription": {
        "price": {
            "amount": 4.99,
            "currency": "EUR"
        },
        "duration": 30,
        "unit": "days",
        "promotion": {
            "price": {
                "amount": 0.99,
                "currency": "EUR"
            },
            "duration": 30,
            "unit": "days",
            "cycles": 1
        }
    }
}

Grace period

By default, Fortumo applies a 48 hour grace period for every subscription. Grace period is a period of time after an unsuccessful rebill event when subscription is not automatically suspended, but instead rebill retry attempts are processed. In case of carrier billing, it is often the case that subscribers run out of money on their prepaid phone cards. Grace period gives such subscribers an option to top up their card instead of automatically losing access to service. During the grace period, subscription remains in active state. In case all rebill retries during grace period fail, subscription will become suspended. Ultimately such feature helps you reduce churn as subscribers do not need to manually visit your service again to re-subscribe - instead, their original subscription continues.

You can override the default grace period of 48 hours by defining "grace_period" attribute inside "subscription" parameter in your JWT payload. Grace period attribute can be set as hours, but can’t have value higher than default 48 hours.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
    "subscription": {
        "price": {
            "amount": 4.99,
            "currency": "EUR"
        },
        "duration": 30,
        "unit": "days",
        "promotion": {
            "price": {
                "amount": 0.99,
                "currency": "EUR"
            },
            "duration": 30,
            "unit": "days",
            "cycles": 1
        },
        "grace_period": {
            "duration": 0,
            "unit": "hours"
        }
    }

Subscription callbacks

For every subscription activity that takes place, your server will be sent a callback. Based on that callback you will decide whether user should have access to your service or not. Every subscription has a unique subscription_id based on which you can track all events related to one subscription.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "subscription_uuid": "c261b02f-51e4-43b4-bce5-a23191405b18", 
    "charging_token": "a73bd482-fcce-407e-adf7-d12063036eb1:f7a85225", 
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "your_internal_subscription_id",
    "subscription_status": "active",
    "action": "activation",
    "billing_status": "charged",
    "service_starts_at": "2017-05-30T10:47:39.836Z",
    "service_ends_at": "2017-06-05T10:47:39.836Z",
    "unsubscribe_url": "https://fortumo.eu/u/nslF0QAzqDTh",
    "consumer_identity": "a30881d7-5d1d-38ca-84f3-39905f1d2848",
    "error": {},
    "metadata": {
        "token": "acfd13d1-40b6-4b57-aa5d-a1000bd52187",
        "uuid": "998b146a-6ca2-4df3-81ba-99b676962fbf"
    },
    "timestamp": "2017-06-01T09:47:45.127Z",
    "price": {
        "amount": 6.99,
        "currency": "EUR"
    },
    "promotion_price": {
        "amount": 0,
        "currency": "EUR"
    }
}

Providing service to consumers

In subscription callbacks you will have information about subscription related actions, billing statuses and subscription statuses. As a general rule, you should provide service to consumers based on service_starts_at and service_ends_at dates.

Possible subscription related actions you may receive in callbacks are:

  • activation - consumer starts a new subscription
  • rebill - consumer is charged for subscription renewal
  • cancellation - consumer has cancelled the subscription
  • suspension - subscription has been suspended due to failure to charge consumer for a renewal

Possible billing statuses are:

  • new
  • pending
  • enqueued
  • charged
  • failed

Possible subscription statuses:

  • active - subscription is active, user should be granted service, rebill will be processed at service_ends_at date
  • suspended - subscription has been cancelled by merchant, carrier or Fortumo, no future rebills will be processed
  • failed - subscription activation has failed, no rebills will be processed
  • cancelled - consumer has voluntarily cancelled subscription, no future rebills will be processed

Stopping subscriptions

There are multiple ways how Unified SDK subscriptions can be terminated. Listed below are different methods how to unsubscribe in Unified SDK.

User follows the unsubscribe URL from payment confirmation SMS

Every time a user has successfully subscribed Fortumo will send them a confirmation message which includes the service they subscribed to, price and a link to unsubscribe. This link can be clicked and users are guided to Fortumo hosted unsubscribe flow here they can see the details of their subscription and unsubscribe.

Implementing unsubscribe URL to your app or webpage

Upon successful subscription you will always receive a callback consisting an unsubscribe url. You can implement this URL to your webpage as a button or a link for an option to unsubscribe.

When the user has successfully unsubscribed we are sending you a notification with the subscription status and service end date when you should stop providing service for that user.

Stopping subscription via API call

You can also cancel the subscription on your end via API call. Please see the API documentation here.

Help us improve our Merchants Portal. Was this article helpful?