PIN authorisation

In order to complete PIN authorisation flow, Consumer is sent a PIN code that they will need to enter into your payment interface. After the PIN has been entered, Fortumo validates whether the PIN was correct or not. In case the PIN entered was correct, Consumer's authorisation session gets verified and you will receive a callback with a verified charging token that can be used for charging.

From integration perspective, PIN authorisation flow involves following steps:

  1. You as a merchant make a POST request towards authorisation endpoint with channel_code and consumer MSISDN 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 is made to your server providing you a charging token that can be used for identifying the authorisation session and its status
  4. Consumer is sent a PIN via SMS that they will need to enter into a payment authorisation interface provided by you
  5. You will make a PUT request to update the specific authorisation object with a PIN Consumer has entered to the payment authorisation interface
  6. Fortumo validates if the PIN provided is correct
  7. Separate callback with a final authorisation status is made to your backend

In case PIN verification does not succeed, you may ask the Consumer to try enter the PIN again. Total of 3 PIN verification attempts can be made per one authorisation session.

Possible authorisation states

Authorisation state Description
new New authorisation object has been created, PIN has not yet been sent to Consumer
pending PIN has been sent to user, authorisation object is waiting for an update with PIN code included
confirmed Authorisation object has been updated with a PIN, PIN verification has not yet been started
verified PIN verification has been successful, you can proceed with charging the Consumer using the charging_token issued
failed PIN verification 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

As this request is to start PIN authorisation session then the code object is present, but empty as the user hasn't been sent the PIN yet.

You can either have operation_reference for each request you make in order to know about which request the callback is in response to or have one operation_reference per one user authorisation session (both POST request to start and PUT request to verify the pin auth have the same operation_reference in that case).

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

{
    "flow": {
        "pin": {
            "channel_code": "sandbox-ee",
            "msisdn": "3725123456",
            "code": "" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_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

{
    "flow": {
        "pin": {
            "channel_code": "sandbox-ee",
            "msisdn": "3725123456",
            "code": "" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_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
22
23
POST /authorisations HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

{
    "flow": {
        "pin": {
            "channel_code": "sandbox-ee",
            "msisdn": "3725123456",
            "code": "" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "callback": "https://your-callback-url-here.com",
    "item_description": "Premium subscription",
    "payment_type": "subscription", 
    "price": {
      "amount": 4.99,
      "currency": "EUR"
    }
}
Fortumo Callback

After a successful request a callback is made to your server providing you a charging token that can be used for identifying the authorisation session and its status.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "charging_token": "08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b",
    "authorisation_state": "new",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "error": {},
    "timestamp": "2016-08-22T09:25:54.297Z"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "charging_token": "08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b",
    "authorisation_state": "pending",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "error": {},
    "timestamp": "2016-08-22T09:25:54.394Z"
}

Request to Fortumo API - updating an authorisation session

After you make the POST request to start PIN authorisation the consumer will be sent a PIN to their phone. As a next step you are expected to capture the PIN from the consumer and verify it by making a PUT request and update the authorisation object identified by the charing token.

In sandbox mode the PIN will always be 1234, any other PIN will yield in a failed verification. PIN can be verified up to 3 times, after that a new authorisation flow needs to be initialised.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
PUT /authorisations/08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....CgVKRghGWI6-QjMv8JpJi1GarWaQ06CG9d0c1PDFek

{
    "flow": {
        "pin": {
            "channel_code": "sandbox-ee",
            "msisdn": "3725123456",
            "code": "1234" 
        }
    },
    "country": "EE",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "callback": "https://your-callback-url-here.com"
}
Fortumo Callback

After successful request is sent Fortumo will validate if PIN is correct and send a callback with a final authorisation status.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "charging_token": "08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b",
    "authorisation_state": "confirmed",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "error": {},
    "timestamp": "2016-08-22T10:57:34.341Z"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "charging_token": "08356bca-e665-4446-b1c6-d2ba0258ab51:d767c48b",
    "authorisation_state": "verified",
    "merchant": "377b7cdc1716225e7766a7a46e0bbb73",
    "operation_reference": "pin_authorisation_1",
    "consumer_identity": "9af92f6e-b83e-3b11-9148-ca60fdeb9115",
    "channel": {
        "code": "sandbox-ee",
        "country": "EE"
    },
    "error": {},
    "timestamp": "2016-08-22T10:57:34.463Z"
}
Help us improve our Merchants Portal. Was this article helpful?