Handling Callbacks

Fortumo's Bundling Platform backend callback API is designed according to the REST principles where different resources are created and updated. This allows easy integration using existing tools and provides established security infrastructure between the parties. This also simplifies the overall design and implementation of the API functionalities.

Callbacks are made to partner's backend URL, when a new bundle is created, activated, updated or cancelled. Please note that multiple callback requests may be performed for the same bundle_id, but only bundle_state = activated indicates a successfully validated and activated bundle, that should trigger delivery of the service. Other statuses can be used for analytical purposes.

Fortumo supports TLS client authentication for callbacks. The certificate is presented during the TLS handshake upon establishing a secure connection between Partner and Fortumo.

Every request that originates from Fortumo will use client certificate with the following CN:

api.fortumo.io

In order to verify the authenticity of the callbacks made by Fortumo you should be checking the following:

  1. Is the callback initiated using a certificate issued by one of the Fortumo approved Certificate Authorities.
  2. Does the Common Name (CN) or DNS Subject alternative name (SAN) of the certificate match api.fortumo.io

Bundle activation callback

Callback sent to return the activation status. Request body is JSON with the following fields:

Request parameters:

Attribute Type Description Required
channel → country String, ISO 3166-1 alpha-2 Country code. Mandatory
channel → code String Channel code. Attribute that specifies the channel (carrier) that your consumer is using for bundling. Mandatory
offer_code String Unique offer identifier as configured on Fortumo's Bundling Platform Mandatory
operation_reference String A unique operation id. Mandatory
bundle_state String Bundle status. Refer to detailed status codes page for additional details. Mandatory
bundle_id String Unique activated bundle id. Mandatory
consumer_identity String Unique string that is generated for a single consumer. Mandatory
partner_reference String Unique activated subscription id in Partner's system. Optional
msisdn String Subscriber's MSISDN. Not included by default due to personal data protection requirements. Optional
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier Optional
merchant_reference String Allows specifying additional information like user identifier, that will be passed over in backend callbacks. Optional
bundle_starts_at Datetime ISO 8601 formatted bundle validity start. Optional
bundle_ends_at Datetime ISO 8601 formatted bundle validity end. Optional
timestamp Datetime ISO 8601 formatted bundle operation timestamp. Optional
metadata Object Additional bundle information like coupon code number or subscriber group. Optional
error → code String Error code in case of failed activation. Refer to table below. Optional
error → message String Detailed error description. Optional
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "channel": {
        "code": "telekom-fr",
        "country": "FR"
    },
    "offer_code": "telekom_vod_trial30",
    "merchant_reference": "userid_8572394923",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "bundle_state": "activated",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3",
    "partner_reference": "1982io-e112-9002-123029-tr4006f919aa",
    "bundle_starts_at": "2016-08-22T09:25:54.394Z",
    "bundle_ends_at": "2016-09-22T09:25:54.394Z",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "msisdn": "441811111111",
    "product": "vod_monthly_with_trial",
    "timestamp": "2016-08-22T09:25:54.394Z",
    "metadata": {
        "coupon_code": "34b2-m34b3-nl6n4"
    },
    "error": {}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "channel": {
        "code": "telekom-fr",
        "country": "FR"
    },
    "offer_code": "telekom_vod_trial30",
    "merchant_reference": "userid_8572394923",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "bundle_state": "failed",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "timestamp": "2016-08-22T09:25:54.394Z",
    "error": {
        "code": "ERR_2003",
        "message": "User entitlement validation failed, bundle was not activated."
    }
}

Bundle update callback

Callback sent upon successful completion of a bundle update, for example from free to paid tier. Request body is JSON with the following fields:

Request parameters:

Attribute Type Description Required
channel → country String, ISO 3166-1 alpha-2 Country code. Mandatory
channel → code String Channel code. Attribute that specifies the channel (carrier) that your consumer is using for bundling. Mandatory
offer_code String Unique offer identifier as configured on Fortumo's Bundling Platform Mandatory
operation_reference String A unique operation id. Mandatory
bundle_state String Bundle status. Refer to detailed status codes page for additional details. Mandatory
bundle_id String Unique activated bundle id. Mandatory
consumer_identity String A unique string that is generated for a single consumer. Mandatory
partner_reference String Unique activated subscription id in Partner's system. Optional
msisdn String Subscriber's MSISDN. Not included by default due to personal data protection requirements. Optional
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier Optional
merchant_reference String Allows specifying additional information like user identifier, that will be passed over in backend callbacks. Optional
bundle_starts_at Datetime ISO 8601 formatted bundle validity start. Optional
bundle_ends_at Datetime ISO 8601 formatted bundle validity end. Optional
timestamp Datetime ISO 8601 formatted bundle operation timestamp. Optional
metadata Object Additional bundle information like coupon code number or subscriber group. Optional
error → code String Error code in case of failed activation. Refer to table below. Optional
error → message String Detailed error description. Optional
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "channel": {
        "code": "telekom-fr",
        "country": "FR"
    },
    "offer_code": "telekom_vod_trial30",
    "merchant_reference": "userid_8572394923",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "bundle_state": "updated",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3",
    "partner_reference": "1982io-e112-9002-123029-tr4006f919aa",
    "bundle_starts_at": "2016-08-22T09:25:54.394Z",
    "bundle_ends_at": "2016-09-22T09:25:54.394Z",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "msisdn": "441811111111",
    "product": "vod_full_price",
    "timestamp": "2016-08-22T09:25:54.394Z",
    "error": {}
}

Bundle cancellation callback

Callback sent in case bundle has been cancelled, for example, due to user's opt-out or bad debt. Request body is JSON with the following fields:

Request parameters:

Attribute Type Description Required
channel → country String, ISO 3166-1 alpha-2 Country code. Mandatory
channel → code String Channel code. Attribute that specifies the channel (carrier) that your consumer is using for bundling. Mandatory
offer_code String Unique offer identifier as configured on Fortumo's Bundling Platform Mandatory
operation_reference String A unique operation id. Mandatory
bundle_state String Bundle status. Refer to detailed status codes page for additional details. Mandatory
bundle_id String Unique activated bundle id. Mandatory
consumer_identity String A unique string that is generated for a single consumer. Mandatory
termination_reason String Identifies the reason why bundle was terminated. Equals to one of the values described in cancellation codes page. Mandatory
merchant_reference String Allows specifying additional information like user identifier, that will be passed over in backend callbacks. Optional
partner_reference String Unique activated subscription id in Partner's system. Optional
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier Optional
bundle_starts_at Datetime ISO 8601 formatted bundle validity start. Optional
bundle_ends_at Datetime ISO 8601 formatted bundle validity end. Optional
timestamp Datetime ISO 8601 formatted bundle operation timestamp. Optional
metadata Object Additional bundle information like coupon code number or subscriber group. Optional
error → code String Error code in case of failed activation. Refer to table below. Optional
error → message String Detailed error description. Optional
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "channel": {
        "code": "telekom-fr",
        "country": "FR"
    },
    "offer_code": "telekom_vod_trial30",
    "merchant_reference": "userid_8572394923",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "product": "vod_monthly_with_trial",
    "bundle_state": "cancelled",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3",
    "partner_reference": "1982io-e112-9002-123029-tr4006f919aa",
    "bundle_starts_at": "2016-08-22T09:25:54.394Z",
    "bundle_ends_at": "2016-09-22T09:25:54.394Z",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "termination_reason": "customer_ineligible",
    "timestamp": "2016-08-22T09:25:54.394Z",
    "error": {}
}
1
2
3
4
5
6
7
8
{
    "bundle_id":"9182ee-e139-4629-419909-024356f929c3",
    "error":
    {
        "code":"ERR_2001",
        "message":"Termination failed"
    }
}

Retries

In case of any other HTTP status code besides the 200s, Fortumo will retry the callbacks with progressive backoff time, depending on the connection. Typically, there is a total of 10 attempts with the following intervals: 3 sec, 10 sec, 1 minute, 10 minutes, 100 minutes, 8 hours, 24 hours, 48 hours and 96 hours.

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