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:
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.
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 |
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" } } |
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" } |
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" } |
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" } |