Header Enrichment authorisation

In certain markets Consumer identification can be carried out by fetching Consumer specific information such as MSISDN from HTTP request headers. Authorisation with help of Header Enrichment allows you to build an even more seamless payment flow whereby user authorisation can be carried out with one click only. Note that as Header Enrichment is not available for all payment channels, it is recommended that you always implement a PIN authorisation flow as a fallback in case Header Enrichment authorisation fails.

From integration perspective, Header Enrichment authorisation involves following steps:

  1. You as a merchant make a POST request towards authorisation endpoint with channel_code and consumer_ip specified to create a new authorisation object
  2. Fortumo responds to the request with an HTTP status indicating whether the request was received by Fortumo servers successfully or not
  3. Separate callback with authorisation_state new is made to your server providing you a charging token that can be used for identifying the authorisation session and its status
  4. In case Header Enrichment is available for specified payment channel, separate callback with authorisation_state pending is made to your server including details with the Header Enrichment URL
  5. Header Enrichment URL received in callback must be called from Consumer's device with any specified parameters attached
  6. Fortumo validates if Consumer requesting the previously provided URL can be identified based on request headers
  7. Separate callback with a final authorisation status is made to your backend

For being able to finish an authorisation session successfully via Header Enrichment, Consumer must be using carrier data connection. In case Consumer is on WIFI connection, authorisation will fail.

Possible authorisation states

Authorisation state Description
new New authorisation object has been created
pending Header Enrichment capability has been checked and URL to be requested from Consumer's device returned to you in a callback
verified Header Enrichment URL has been called from Consumer's device and Consumer has been successfully authorised, you can proceed with chrging the Consumer using the charging_token issued
failed Consumer identification failed, in order to proceed with charging the Consumer new authorisation session must be carried through

Request to Fortumo Authorisation API - initiating an authorisation session

For starting a Header Enrichment authorisation session you will need to make a request towards Fortumo API with Consumer channel_code and/or consumer_ip specified in the callback so that Fortumo could check whether Header Enrichment authorisation flow for the specified channel is available.

The most fool-proof method for determining your consumer's carrier is asking that directly from the consumer itself. If you would like to avoid asking the consumer to confirm their carrier manually, we strongly recommend using a combination of different IP based methods for resolving the consumer carrier instead of only one. Consumer carrier could be detected by validating the combination of consumer's

  • IP address hostname
  • carrier IP ranges provided by Fortumo (via Capabilities API)
  • IP address whois lookup
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
POST /authorisations HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

{
    "flow": {
        "he": {
            "channel_code": "sandbox-ee",
            "consumer_ip": "127.0.0.1" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "callback": "https://your-callback-url-here.com"
}

On certain connections authorisation requests also need to include item description, price and payment type information. In such situations, please refer to examples below. Whether the additional information in requests is required or not will be shared with you by Fortumo team during the integration process.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /authorisations HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

{
    "flow": {
        "he": {
            "channel_code": "sandbox-ee",
            "consumer_ip": "127.0.0.1" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "callback": "https://your-callback-url-here.com",
    "item_description": "Premium item",
    "payment_type": "oneoff", 
    "price": {
      "amount": 4.99,
      "currency": "EUR"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST /authorisations HTTP/1.1
Content-Type: application/json

{
    "flow": {
        "he": {
            "channel_code": "sandbox-ee",
            "consumer_ip": "127.0.0.1" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "callback": "https://your-callback-url-here.com",
    "item_description": "Premium subscription",
    "payment_type": "subscription", 
    "price": {
      "amount": 4.99,
      "currency": "EUR"
    }
}
Fortumo callback

Callback with authorisation_state new is made to your server providing you a charging token that can be used for identifying the authorisation session.

1
2
3
4
5
6
7
8
9
{
    "charging_token": "7164712a-4a15-4c16-8f5c-affaf680c7ff:300bc7cb",
    "authorisation_state": "new",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "channel": {},
    "error": {},
    "timestamp": "2016-08-22T12:12:15.970Z"
}

After Fortumo has determined that Header Enrichment authorisation flow is available for the specific channel, we will return you a URL that must be called from Consumer's device.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "flow": {
        "he": {
            "url": "http://sandbox-ee-311695a1-he.fortumo.io/he/v1/detect/96d54d30-4a8f-0134-4882-064c70866873",
            "request_type": "GET"
        }
    },
    "charging_token": "7164712a-4a15-4c16-8f5c-affaf680c7ff:300bc7cb",
    "authorisation_state": "pending",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "channel": {},
    "error": {},
    "timestamp": "2016-08-22T12:12:16.304Z"
}

Since background AJAX javascript call to HE endpoint may not go through due to CORS restrictions we recommended to call the URL by having a small image on your payment page with the Header Enrichment URL as its source:

1
<img alt="." height="1" width="1" class="hidden" src="http://sandbox-ee-311695a1-he.fortumo.io/he/v1/detect/96d54d30-4a8f-0134-4882-064c70866873">

Note that if for any reason calling that URL fails, authorisation remains in pending state.

Request to Header Enrichment URL

Consumer calls the Header Enrichment URL from its device.

When testing in sandbox mode, upon calling the Header Enrichment URL X-Msisdn header must be hardcoded to the request. Hardcoding the X-Msisdn header in production requests results in authorisation failure.

1
2
3
GET /he/v1/detect/96d54d30-4a8f-0134-4882-064c70866873 HTTP/1.1
Host: sandbox-ee-311695a1-he.fortumo.io
X-Msisdn: 3725123456
Fortumo callback

Fortumo validates if Consumer requesting the previously provided URL can be identified based on request headers. If so a callback with relevant status is sent to your backend.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "flow": {
        "he": {
            "url": "http://sandbox-ee-311695a1-he.fortumo.io/he/v1/detect/96d54d30-4a8f-0134-4882-064c70866873",
            "request_type": "GET"
        }
    },
    "charging_token": "7164712a-4a15-4c16-8f5c-affaf680c7ff:300bc7cb",
    "authorisation_state": "verified",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "he_authorisation_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "error": {},
    "timestamp": "2016-08-22T12:21:05.949Z"
}
Help us improve our Merchants Portal. Was this article helpful?