Subscription callbacks

In case you are using Unified SDK for providing subscription services, it is recommended to make use of subscription specific callbacks when delivering service to consumers. Based on parameters provided when initializing the subscription, every subscription callback provides information about consumer's eligibility for your service.

Subscription actions
Action Description
activation New subscription has been started
rebill Subscription has been renewed
free_cycle Subscription free period has been renewed
cancellation Subscription has been cancelled
suspension Subscription has been suspended by Fortumo
Subscription statuses
Status Description
new New subscription has started
active Subscription is active
suspended Subscription is suspended by Fortumo
failed Subscription failed
cancelled Subscription is cancelled
Subscription errors
Code Error message Description
ERR_900 Generic error, operation failed Invalid input. May be a typo or malicious usage.
ERR_901 Subscription not found  
ERR_902 Subscription already exists  
ERR_903 Subscription invalid state transition  
ERR_904 Subscription already cancelled Happens if you attempt to cancel already stopped subscription.
ERR_905 Subscription free trial has ended  
ERR_906 Authorisation has been failed, retries are allowed Authorisation failed on the operator side. May be resolved on the retries.
ERR_907 Authorisation has been failed, retries are not allowed Authorisation failed on the operator side. Can not be resolved on retry attempts.
ERR_908 Subscription in wrong status  
ERR_909 Discount already exist  
Callback examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "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",
    "billing_status":"charged",
    "service_starts_at":"2018-05-02T11:19:42.711Z",
    "service_ends_at":"2018-05-03T11:19:42.711Z",
    "consumer_identity":"a30881d7-5d1d-38ca-84f3-39905f1d2848",
    "error":{},
    "metadata":{
        "token":"acfd13d1-40b6-4b57-aa5d-a1000bd52187",
        "uuid":"998b146a-6ca2-4df3-81ba-99b676962fbf"
    },
    "timestamp":"2018-05-02T11:19:42.711Z",
    "price":{
        "amount":6.99,
        "currency":"EUR"
    },
    "action":"activation",
    "unsubscribe_url":"https://fortumo.eu/u/hGVxPEv4aYHY",
    "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "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",
    "billing_status":"charged",
    "service_starts_at":"2018-05-02T11:19:42.711Z",
    "service_ends_at":"2018-05-04T11:19:42.711Z",
    "consumer_identity":"a30881d7-5d1d-38ca-84f3-39905f1d2848",
    "error":{},
    "metadata":{
        "token":"acfd13d1-40b6-4b57-aa5d-a1000bd52187",
        "uuid":"998b146a-6ca2-4df3-81ba-99b676962fbf"
    },
    "timestamp":"2018-05-03T11:18:50.272Z",
    "price":{
        "amount":6.99,
        "currency":"EUR"
    },
    "action":"rebill",
    "unsubscribe_url":"https://fortumo.eu/u/nslF0QAzqDTh",
    "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
    "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": "cancelled",
    "billing_status": "enqueued",
    "service_starts_at": "2018-05-18T13:26:50.045Z",
    "service_ends_at": "2018-05-19T13:26:50.045Z",
    "consumer_identity": "aaf3af50-09d6-3919-acc6-f02428c835e4",
    "error": {},
    "metadata": {
       "token": "1d6de68c-9aa1-47ab-b07a-32db8150a41c",
       "uuid": "8c301bb3-1ef2-436e-b588-ada0dc2c181f"
    },
    "timestamp": "2018-05-18T13:27:48.143Z",
    "price": {
        "amount": 6.99,
        "currency": "EUR"
    },
    "promotion_price": {
        "amount": 0,
        "currency": "EUR"
    },
    "action": "cancellation",
    "unsubscribe_url": "https://fortumo.eu/u/7f8Ec1u3xc1T",
    "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
Subscription lifecycle example
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "charged",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-08T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-07T20:58:32.994Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "activation",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-08T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-08T20:57:44.702Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-08T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-08T20:58:51.815Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-08T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-08T22:57:46.068Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-08T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-09T04:57:50.052Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "charged",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-15T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-09T20:57:46.764Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "charged",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-15T20:57:44.805Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-22T20:57:42.348Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-22T20:58:51.739Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-22T22:57:46.356Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "active",
  "billing_status": "pending",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-23T04:57:45.341Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "rebill",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
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
{
  "subscription_uuid": "37b59a51-4ab6-4658-836c-1f0c1ea775ef",
  "charging_token": "57995f3e-66c8-4999-b5dc-fd1b2f304e19:2f89bc4e",
  "merchant": "as208e52daace2ed5e4936956e8b0b85",
  "operation_reference": "3x8NdHYJw9yBN5gnUGSmywEBUvl5v5mH",
  "subscription_status": "suspended",
  "billing_status": "failed",
  "service_starts_at": "2018-08-07T20:58:32.994Z",
  "service_ends_at": "2018-08-22T20:58:32.994Z",
  "consumer_identity": "9d00b9dd-fcf8-3ec8-8013-1053344cb14a",
  "error": {
    
  },
  "metadata": {
    "token": "f1356a6f-9277-44ac-9e32-db9fb0e374eb",
    "uuid": "3b72b820-50ae-4d78-9708-ca93333f5481"
  },
  "timestamp": "2018-08-23T20:57:49.568Z",
  "price": {
    "amount": 3.99,
    "currency": "MYR"
  },
  "promotion_price": {
    "amount": 0,
    "currency": "MYR"
  },
  "action": "suspension",
  "unsubscribe_url": "https:\/\/fortumo.eu\/u\/IB82mkCwV5Go",
  "payment_transaction_id":"c02f221b-9ccf-4127-bc4t-5df7d4e0161e"
}
Operation_reference parameter in subscription callbacks

In case of a subscription the "operation_reference" parameter you define in the initial JWT request will be the unique identifier of the whole subscription cycle. This will be presented as "operation_reference" in authorisation and subscription callbacks. In payment callbacks it is presented as "subscription_merchant_operation_reference". This is so because payment callback holds its own "operation_reference" that defines a unique value of one charging withing the subscription cycle.

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