Activating a Bundle

There are two common scenarios to start a bundle activation journey:

1. Public offer URL

In this scenario, an offer can be accessed via a unique public URL. This URL can be distributed via mobile operator or partner promotional channels like email newsletters, account profile pages or SMS marketing broadcast. Any user that lands to public offer URL will be able to access the offer and activate the bundle assuming all authentication and validation criteria are met.

Example of public offer URL: https://b.fortumo.eu/o/telekom_vod_trial30

NB: If an offer is only meant to be accessible via a signed user redirect, then public offer URL will be disabled.

2. Signed redirect to offer endpoint

In this scenario, a signed user redirect from partner to Fortumo will be used for securely transferring the user to Fortumo for completing the activation together with a unique user ID. Signed redirect should be used if offer access should be restricted to specific users or partner needs to pass additional reference parameters through bundle activation process.

Redirect requests are signed using JSON Web Tokens (JWT). JWT is an open RFC 7519 standard for transmitting information between two parties. Using JWTs helps us to validate that all payment requests are initiated by the partner and none of the parameters have been tampered with by third parties. We strongly encourage to use one of the available JWT libraries for request signing. We also suggest adding a few minutes buffer to the time-related claims to account for possible server time differences. Please refer to the Security page for additional information about JWT.

NB: Some of the optional parameters including offer_name and offer_description can be used for overriding default offer configuration.

Offer endpoint: https://b.fortumo.eu/s/{merchant_id}/?token={JWT token}

JWT header

Attribute Type Description Required
alg String Algorithm. Specified the algorithm that is used for signing the token. Fortumo supports RS256 algorithm. Mandatory
typ String Type. Used to declare the media type of the complete JWT. Defaults to "JWT". Mandatory

JWT payload

Attribute Type Description Required
iss String Issuer. Identifies the principal that issued the JWT. Value must equal to Merchant ID as provided by Fortumo. Mandatory
exp Long, Unix epoch Expiration time. Identifies the expiration time after which the JWT must not be accepted for processing. Mandatory
sub String Subject. Identifies the principal that is the subject of the JWT. Should be set as "bundle". Mandatory
aud String Audience. Identifies the recipients that the JWT is intended for. Should be set at "Fortumo". Mandatory
nbf Long, Unix epoch Not before. Identifies the time before which the JWT must not be accepted for processing. Mandatory
iat Long, Unix epoch Issued at. Identifies the time at which the JWT was issued. Mandatory
jti String JWT ID. Provides a unique identifier for the JWT. Mandatory
offer_code String Unique offer identifier with a pre-defined set of values as configured on Fortumo's Bundling Platform. Mandatory
offer_name String Offer name that will be included in offer activation flow. Overrides default offer configuration. Optional
offer_description String Short offer description that will be included in offer activation flow. Overrides default offer configuration. Optional
msisdn String Subscriber's MSISDN, unique hash, ACR, subscriber ID, landline number or any other unique identifier. Optional
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier. Optional
urls → bundle_callback String Partner backend URL to be used for offer activation callbacks. Overrides default offer configuration. Optional
urls → redirect String Specifies the URL of the page for user activation after successful or failed bundling activation flow. Overrides default offer configuration. Optional
merchant_reference String Allows specifying additional information like user identifier, session or transaction ID, that will be passed over in backend callbacks. Optional
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "iss": "d3ad608d0a1729727a3eb6bc0892b426",
    "exp": "1988326400",
    "sub": "bundle",
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "00001",
    "offer_code": "telekom_vod_trial30",
    "offer_name": "1 Month Trial",
    "offer_description": "Free access to video service for Telekom subscribers",
    "msisdn": "33158111111",
    "product": "vod_monthly_with_trial",
    "urls": {
        "bundle_callback": "https://example.com/bundles_activate",
        "redirect": "https://example.com/bundling_complete"
    },
    "merchant_reference": "userid_8572394923"
}

Signed redirect to partner

Signed user redirect from Fortumo to partner is used to deliver the user to offer activation page after completing bundle activation process. Redirect will be done to pre-configured URL and can be overridden using urls -> redirect parameter. Please use a HTTPS-secured URL to avoid browser security restrictions.

1
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC4gnCJaVkFsbuARdlDJAWRq9NUKr1Ls0626TpCGhhGAGiUbm6BNtomU8JI+hs2WutHMgSJ85uS0GVI0qbniBbOoEV+yGIl+kvttmeZ8GrT+w0mIgKFouTWp8Bw1tdOZbEoSbIgkfN4hthddIWeLxQEPyjAsFQFgKHR5FJyVcmnUTCmD9+8Z/fipfxLhPbfs1zQfdnD1PjIp4IO94dvkUkCv8HbF9kLsJ4koMgayNQIIs2FZJ8gT3qLw7AdejBCtCGLsEkuZVZnMr/ysxbLe5QQHeUHJVH4yxqkeDK+GQf33bx93iiaHWXT0z+juMH1I+EIdCgNGhCRt3ZDo8uCHYh1bDcMwJrPMYT9qGiv68bTD+dqp90mqrYWof3LUGoF71lU9rKVC4JpA/NZGSi9UuHlvnKp0qGU3zUaYZZEBXK+qxFJmnKkS9nsR7Bc9KBxTc/CwusAnhl0Nob6eZaJ9RwiV9SsY04rRhQCQ8EUd1t+3PtOl9SbY5T0XHzdumghMD2dHvujJJNIflHzGR+KMafsU5fWHE7qjOgDB1ROCfZgqT4ba6zg8VS5+Ll8C3ovUVn0l02tskesRf5PJAu94MmEiyRiTwYWjtsNzSFC6CpcxmztRY/bWVvDZ3Y9lBEw9o3KFWHzfLtGLcS17n0fr5K5OuWutQRzGzrSSwk9V2OGPw== development@fortumo.com

NB: Please note that this method is not applicable for flows that end on the service provider's side.

JWT header

Attribute Type Description Required
alg String Algorithm. Specified the algorithm that is used for signing the token. Fortumo supports RS256 algorithm. Mandatory
typ String Type. Used to declare the media type of the complete JWT. Defaults to "JWT". Mandatory

JWT payload

Attribute Type Description Required
iss String Will be set to "Fortumo". Mandatory
exp Long, Unix epoch Expiration time. Identifies the expiration time after which the JWT must not be accepted for processing. Mandatory
sub String Subject. Identifies the principal that is the subject of the JWT. Will be set as "bundle". Mandatory
aud String Audience. Identifies the recipients that the JWT is intended for. Mandatory
nbf Long, Unix epoch Not before. Identifies the time before which the JWT must not be accepted for processing. Mandatory
iat Long, Unix epoch Issued at. Identifies the time at which the JWT was issued. Mandatory
jti String JWT ID. Provides a unique identifier for the JWT. Mandatory
country_code 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 Unique operation id. Mandatory
bundle_state String Bundle activation status. Refer to status codes page for details. Mandatory
bundle_id String Unique activated bundle id. Mandatory
consumer_identity String A unique string that is generated for a single consumer. Mandatory
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
error_code String Error code in case of failed activation. Refer to error codes page for details. 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
{
    "iss": "377b7cdc1716225e7766a7a46e0ccc73",
    "exp": "1988326400",
    "sub": "bundle",
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "bundling-55d52709-b50b-4798-9f83-2f0b2f0f218f",
    "channel_code": "telekom-fr",
    "country": "FR",
    "offer_code": "telekom_vod_trial30",
    "offer_name": "1 Month Trial",
    "offer_description": "Free access to video service for Telekom subscribers",
    "merchant_reference": "userid_8572394923",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "bundle_state": "activated",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3",
    "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"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "iss": "Fortumo",
    "exp": 1539065947,
    "sub": "bundle",
    "aud": "Fortumo",
    "nbf": 1539065647,
    "iat": 1539065647,
    "jti": "bundling-dfe280cb-6c77-4c5e-82fb-eb9c641e0f22",
    "offer_code": "telekom_vod_trial30",
    "operation_reference": "bundling-dfe280cb-6c77-4c5e-82fb-eb9c641e0f22",
    "bundle_state": "failed",
    "bundle_id": "4de65cf6-e1ea-438a-8ac2-49727e700cd4",
    "country_code": "FR",
    "channel_code": "telekom-fr",
    "merchant_reference": "userid_8572394923",
    "consumer_identity": "e8c7d21a-2096-3fb0-8c25-24bae4af3f34",
    "error_code": "ERR_2002",
    "error_message": "User authentication failed, bundle was not activated."
}

Bundle Activation API

This method can be used to trigger an activation ID to be returned in case of activations from a set-top box.

Every request should be secured using JWT authentication token provided in an Authorization: Bearer header containing JWT token using the below payload. Please refer to the Security page for additional information about JWT.

Returns either 200 OK or error in case of refused operation. The request result will be sent via an asynchronous callback to a previously configured backend URL.

Request URL: https://bundle-api.fortumo.io/bundle/activate

Request parameters

Attribute Type Description Required
merchant_id String Value must equal to merchant_id as provided by Fortumo. Mandatory
offer_code String Unique offer identifier as configured on Fortumo Bundling Platform. Mandatory
billing_identity String Subscribers MSISDN, unique hash, ACR, subscriber ID, landline number or any other unique identifier. Mandatory
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
callback_url String Partner backend URL to be used for callbacks. Overrides default offer configuration. Optional
1
2
3
4
5
6
7
8
9
10
{
    "body_sha256": "daa813eff0066298af3ec0b9b63b4514bd3bd1165ec0391165178abb1368f760",
    "iss": "d3ad608d0a1729727a3eb6bc0892b426",
    "exp": 1525437711,
    "iat": 1522845411,
    "nbf": 1522845211,
    "sub": "bundle",
    "aud": "Fortumo",
    "jti": "jwt-id"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /bundle/activate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI2N...OL4LxCc4FA-OtAb_UD9M5M
Content-Type: application/json

Request body:

{
    "merchant_id": "sASd9829hdaoda0dasuasdas0d9u2djads",
    "offer_code": "telekom_vod_trial30",
    "billing_identity": "e8c7d21a-2096-3fb0-8c25-24bae4af3f34",
    "product": "vod_monthly_with_trial",
    "merchant_reference": "userid_8572394923",
    "callback_url": "https://example.com/bundles/callbacks"
}

Service Provider Activation Callback

Callback sent to return the service provider activation ID. Request body is JSON with the following fields:

Attribute Type Description Required
offer_code String Unique offer identifier as configured on Fortumo Bundling Platform. Mandatory
bundle_id String Unique activated bundle id. Mandatory
billing_identidy String Subscribers MSISDN, unique hash, ACR, subscriber ID, landline number or any other unique identifier. Mandatory
service_provider_activation_id String Service providers's activation ID. Mandatory
merchant_reference String Allows specifying additional information like user identifier, that will be passed over in backend callbacks. Optional
1
2
3
4
5
6
{
    "offer_code": "telekom_vod_trial30",
    "billing_identity": "e8c7d21a-2096-3fb0-8c25-24bae4af3f34",
    "merchant_reference": "userid_8572394923",
    "service_provider_activation_id": "9b19da40-f110-42c2-8610-65fd08019374"
}
Help us improve our Merchants Portal. Was this article helpful?