Testing

You will be able to test your integration using a set of predefined demo credentials.

SSH keys

Before you can start you will need to share a public key with your Project Manager. Refer to Preparing SSH keys guide on how to generate the public and private key pair (only applicable in case of signed redirect).

Testing signed redirect activation flow

This method can be used to test a signed user redirect from partner to Fortumo, whereby the user is safely transferred to Fortumo for completing the activation together with a unique user ID. A successfully triggered request will result in redirect to a Fortumo-hosted success page, whereas requests with missing attributes will result in redirect to an error page indicating the reason of the error. You will also receive a callback to the backend endpoint set in the request.

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.

Offer endpoint: https://b.fortumo.eu/s/f5d6d7-bundling-test-offer-cfa1a/?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. Should be set as "f5d6d7-bundling-test-offer-cfa1a". 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. Should be set as "fortumo-web-demo". 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. Mandatory
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. Mandatory
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
{
    "iss": "f5d6d7-bundling-test-offer-cfa1a",
    "exp": "1988326400",
    "sub": "bundle",
    "aud": "Fortumo",
    "nbf": "1485256642",
    "iat": "1485256645",
    "jti": "00001",
    "offer_code": "fortumo-web-demo",
    "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",
    },
    "merchant_reference": "userid_8572394923"
}

Testing set-top box activation

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 the backend URL provided in the request.

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. Should be set as "f5d6d7-bundling-test-offer-cfa1a". Mandatory
offer_code String Unique offer identifier with a pre-defined set of values as configured on Fortumo's Bundling Platform. Should be set as "fortumo-stb-demo". 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. Mandatory
1
2
3
4
5
6
7
8
9
10
{
    "body_sha256": "daa813eff0066298af3ec0b9b63b4514bd3bd1165ec0391165178abb1368f760",
    "iss": "f5d6d7-bundling-test-offer-cfa1a",
    "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": "f5d6d7-bundling-test-offer-cfa1a",
    "offer_code": "fortumo-stb-demo",
    "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": "fortumo-stb-demo",
    "billing_identity": "e8c7d21a-2096-3fb0-8c25-24bae4af3f34",
    "merchant_reference": "userid_8572394923",
    "service_provider_activation_id": "9b19da40-f110-42c2-8610-65fd08019374"
}

Testing Bundle Status API

This method can be used for checking the status of a previously started bundle by unique bundle ID.

Every request should be secured using a JWT authentication token provided in an Authorization: Bearer header containing a JWT token using the payload as per the below example, include a JWT-Request: true header, and also include a Content-Type: application/json header for indicating the type of request.

Please refer to the Security page for additional information about JWT.

Request URL: https://bw.fortumo.eu/b/f5d6d7-bundling-test-offer-cfa1a/{bundle_id}

1
2
3
GET /b/f5d6d7-bundling-test-offer-cfa1a/95e3e1a2-e09b-4d2d-b35a-6a0845b1170b  HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI2N...OL4LxCc4FA-OtAb_UD9M5M
Content-Type: application/json

The Authorization: Bearer header corresponds to the following payload

Attribute Type Description Required
aud String Audience. Identifies the recipients that the JWT is intended for. Should be set at "Fortumo". Mandatory
exp Long, Unix epoch Expiration time. Identifies the expiration time after 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. We strongly suggest setting this as now minus 2 minutes to avoid server time conflicts. Mandatory
iss String Issuer. Identifies the principal that issued the JWT. Value must equal to Merchant ID as provided by Fortumo. Should be set as "f5d6d7-bundling-test-offer-cfa1a" Mandatory
jti String Should be set at "jwt-id" Mandatory
nbf Long, Unix epoch Not before. Identifies the time before 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

Response parameters

Response body is JSON with the following fields:

Attribute Type Description Required
bundle_state String Bundle activation status. Refer to detailed status codes for additional details. Mandatory
bundle_id String Unique activated bundle id. Mandatory
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier Mandatory
partner_reference String Unique id of activated bundle on partner's side Optional
bundle_starts_at Datetime ISO 8601 formatted bundle validity start. Optional
bundle_ends_at Datetime ISO 8601 formatted bundle validity end. Optional
1
2
3
4
5
6
7
8
{
    "bundle_state":"activated",
    "bundle_id":"9182ee-e139-4629-419909-024356f929c3",
    "bundle_starts_at":"2020-03-13T11:40:50.354Z",
    "bundle_ends_at":"2020-04-13T11:40:50.354Z",
    "product":"vod_monthly_with_trial",
    "partner_reference":"id039sdp-923d-sr93-so98-k99osm30fnad"
}

Testing Bundle Update API

This method can be used for applying updates for an already active bundle in order to move the user to a different package e.g. from free trial to paid, if required by the Partner.

Every request should be secured using JWT authentication token provided in an Authorization: Bearer header containing JWT token using the payload as per the example and also include a JWT-Request: true header for indicating the type of request.

The body_sha256 claim in the JWT header must be equal to the sha256 checksum of the request body.

Please refer to the Security page for additional information about JWT.

Returns either 200 OK or error in case of refused operation. Update result will be sent via an asynchronous callback to the backend URL provided in the request.

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

Request body

Request body is JSON with the following fields:

Attribute Type Description Required
merchant_id String Value must equal to Merchant ID as provided by Fortumo. Should be set as "f5d6d7-bundling-test-offer-cfa1a". Mandatory
bundle_id String Unique activated bundle id. Mandatory
product String An identifier to indicate whether the consumer is on a free, promotional price or full price tier. Should be set to the new tier value Mandatory
operation_reference String A unique operation id. Optional
callback_url String Specifies the backend URL where Fortumo will send a callback after a successful bundle update flow. Overrides default offer configuration. Mandatory
1
2
3
4
5
6
7
8
9
10
{
    "iss": "f5d6d7-bundling-test-offer-cfa1a",
    "exp": 1525437711,
    "iat": 1522845411,
    "nbf": 1522845211,
    "sub": "bundle",
    "aud": "Fortumo",
    "jti": "jwt-id",
    "body_sha256": "0321385d3f67571815efebbb377a6fe9d2b4e205a87f3d5867de60b152560322"
}
1
2
3
4
5
6
7
8
9
10
11
12
POST /bundle/update  HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI2N...OL4LxCc4FA-OtAb_UD9M5M
Content-Type: application/json
JWT-Request: true

{
    "merchant_id": "f5d6d7-bundling-test-offer-cfa1a",
    "bundle_id": "4de65cf6-e1ea-438a-8ac2-49727e700cd4",
    "product": "vod_full_price",
    "operation_reference": "bundling-aed470f7-c9e7-4692-be89-d164b67bb5e6",
    "callback_url": "https://example.com/bundles/callbacks"
}

Testing Bundle Cancellation API

This method can be used for canceling a bundle due to various reasons, e.g. due to user churn or failed subscription renewal.

Every request should be secured using JWT authentication token provided in an Authorization: Bearer header containing JWT token using the payload as per the example and also include a JWT-Request: true header for indicating the type of request.

The body_sha256 claim in the JWT header must be equal to the sha256 checksum of the request body.

Please refer to the Security page for additional information about JWT.

Returns either 200 OK or error in case of refused operation. Cancellation result will be sent via an asynchronous callback to the backend URL provided in the request.

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

Request parameters

Attribute Type Description Required
channel → code String Channel code. Attribute that specifies the channel (carrier) that your consumer is using for bundling. Should be set as "sandbox-ee". Mandatory
merchant_id String Value must equal to partner ID as provided by Fortumo. Should be set as "f5d6d7-bundling-test-offer-cfa1a". Mandatory
reason String Identifies the reason why bundle was terminated. Equals to one of the values described in status and error codes page. Mandatory
bundle_id String Unique activated bundle id. Either bundle_id or msisdn parameter should be present in the request Optional
msisdn String Unique consumer identifier. Either msisdn or bundle_id parameter should be present in the request. NB! this will cancel all bundles for this consumer Optional
callback_url String Partner backend URL to be used for cancellation callbacks. Mandotory
1
2
3
4
5
6
7
8
9
10
{
    "body_sha256": "daa813eff0066298af3ec0b9b63b4514bd3bd1165ec0391165178abb1368f760",
    "iss": "f5d6d7-bundling-test-offer-cfa1a",
    "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
15
16
POST bundle/cancel HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI2N...OL4LxCc4FA-OtAb_UD9M5M
Content-Type: application/json
JWT-Request: true

{
    "channel": {
        "code": "sandbox-ee"
    },
    "merchant_id": "f5d6d7-bundling-test-offer-cfa1a",
    "bundle_id": "9182ee-e139-4629-419909-024356f929c3", 
    "msisdn": "132432093802",
    "reason": "customer_ineligible",
    "callback_url": "https://example.com/bundles/callbacks"
}
Either bundle_id or msisdn is required
Help us improve our Merchants Portal. Was this article helpful?