Authorisations

When initiating a purchase for a Consumer, first their authorisation has to be obtained. A charging token (received through Local API) identifies the authorisation session. There are different authorisation flows to choose from depending on the payment method and the capabilities of the channel and Consumer's device.

For carrier billing, Fortumo offers two types of authorisation flows:

  • Header Enrichment authorisation
  • PIN authorisation

As Header Enrichment authorisation works only on devices that are using mobile data network and not on WIFI, it is recommended that in addition to Header Enrichment authorisation flow you always implement PIN authorisation as a fallback as this is the flow that is supported on all available carriers and devices.

Every authorisation session is started with a POST request that creates a new authorisation object. In response to the POST request you will receive an HTTP status code indicating whether the request was successful or not. In case of a 200 response, a separate callback is made to the callback URL specified in the initial POST request. From that separate callback you will receive the value of a unique charging_token that will be used when updating the authorisation object and later for charging.

Read more about different authorisation flows from documentation of PIN authorisation and Header Enrichment authorisation.

Authorisation request parameters

Parameter Type Required Description
country String, ISO 3166-1 alpha-2 Mandatory Country code. Attribute that specifies the country of your consumer's carrier. Example: EE
flow Object Mandatory Contains attributes PIN, HE and MO for specifying authorisation flow type.
merchant String Mandatory Your Fortumo account's merchant ID. Example: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory Operation reference. Attribute that allows you to specify a custom reference to every payment session initiated. It will be returned to you with Fortumo notifications so that you can map all payments internally. Operation_reference has to be unique for each payment session. Example: payment0001
callback String Mandatory Callback URL to be used for receiving payment callbacks. Example: https://www.example.com/payment
price Object Optional Contains attributes amount and currency for specifying the price you want to charge for the service.
payment_type Boolean Optional Indicates whether the payment is one-time or requrring. Example: oneoff/subscription

Authorisation callback parameters

charging_token String Mandatory A valid and verified customer identifying token, provided by Authorisations API and issued by Fortumo. Example: 8923b690-2d70-4d51-8caa-d4ab2871f188:8fe403b3
authorisation_state String Mandatory The current state of the authorisation flow. Example: new/pending/confirmed/verified/failed/invalidated
merchant String Mandatory Your Fortumo account's merchant ID. Example: 93d9523134eee0f22716e49093af881a
operation_reference String Mandatory Operation reference. Attribute that allows you to specify a custom reference to every payment session initiated. It will be returned to you with Fortumo notifications so that you can map all payments internally. Operation_reference has to be unique for each payment session. Example: payment0001
consumer_identity String Optional A unique string that is generated for a single consumer. Example: 2b924672-f1a3-3d60-8173-e8a0a0b41e99
channel String Optional Contains attributes code and country. Example: 5555555555
error Object Optional In case errors happen an errorcode and description is listed. Example: 602
timestamp Datetime Mandatory Timestamp of the sent callback. Example: 2016-08-22T09:25:54.394Z
billing_identity String Optional Consumer's phone number. Sent with a callback to your server during MO flow. Example: 5555555555
flow object parameters
Flow      
pin Object Mandatory Used for triggering PIN authorisation flow. Includes attributes defining the channel_code, msisdn and code.
he Object Mandatory Used for triggering HE authorisation flow. Includes attributes defining the channel_code and consumer_ip.
mo Object Mandatory Used for triggering MO authorisation flow. Includes attributes defining the shortcode and content
PIN      
channel_code String Mandatory Channel code. Attribute that specifies the channel (carrier that your consumer is using for completing a payment. Example: sandbox-ee
msisdn String Mandatory Phone number. Can be in standard format or hash(sometimes operators encode the phone number for security and privacy measures). Example: 37256455115 or #a2001sdf1993fc7
code String Mandatory Pin code required by consumer for successful authorisation. Example:12345
HE      
channel_code String Optional Channel code. Attribute that specifies the channel (carrier that your consumer is using for completing a payment. Example: sandbox-ee
consumer_ip String Mandatory Consumer's IP address. Example: 127.0.0.1
url String Optional(sent with callback) If Fortumo determines that HE flow is available for specific channel we will return an URL that is called from Consumer's device. Example:ttp://sandbox-ee-311695a1-he.fortumo.io/he/v1/detect/96d54d30-4a8f-0134-4882-064c70866873
request_type String Optional(sent with callback) The method of HTTP request. Example: GET
MO      
shortcode Integer Mandatory Channel code. Attribute that specifies the channel (carrier that your consumer is using for completing a payment. Example: sandbox-ee
content String Mandatory The content of an SMS message. Example:HELLO abc
price object parameters
Price      
amount Double Mandatory Price amount. Attribute that specifies how much you are going to charge the consumer for your service. Example: 4.99
currency String, ISO 4217 Mandatory Currency code. Attribute that specifies the currency in which you are about to charge the consumer. Example: EUR
channel object parameters
Channel      
code string Mandatory Specifies the identification code of the carrier. Example: sandbox-ee
country String, ISO 3166-1 alpha-2 Mandatory Country code. Attribute that specifies the country of your consumer's carrier. Example: EE

Possible authorisation errors

Code Error message Description
ERR_400 Bad request  
ERR_401 Authentication failure  
ERR_403 Forbidden  
ERR_404 Not found  
ERR_409 Duplicate request  
ERR_500 Server error  
ERR_503 Server busy and service unavailable. Please retry the request  
ERR_600 Authentication failed  
ERR_601 Authentication message delivery failed Message not delivered by the operator.
ERR_602 Consumer authorisation failed - no headers detected  
ERR_603 Authentication failed, retries are allowed Temporary problem on the operator side. May be resolved on the retires.
ERR_610 Wrong or unsupported user End-user is not supported. For instance wrong number format or number belongs to different operator.
ERR_611 Invalid or non-compliant message  
ERR_612 User is blacklisted or blocked End-user is blacklisted by either Fortumo or operator.
ERR_613 Insufficient credit for user (Not enough funds) End-user does not have enough funds on balance.
ERR_615 PIN code was not delivered PIN code was not sent to end-user.
ERR_616 User charge limit exceeded or purchase limit reached Spending limit for the specific MSISDN is reached. The limit is set on either Fortumo or operator side.
ERR_617 PIN generation request limit exceeded, the last PIN is still valid Poland specific error. Limits how many PIN codes can be generated per MSISDN.
ERR_618 PIN generation request limit exceeded, previous PIN codes are no longer valid Poland specific error. Limits how many PIN codes can be generated per MSISDN.
ERR_620 Invalid PIN code, retry attempts available End-user has entered invalid PIN code. Can be attempted again for 3 times.
ERR_621 User account is not enabled End-user's SIM card is not enabled by the operator.
ERR_622 User account is disabled End-user's SIM card is disabled by the operator.
ERR_623 User not permitted to purchase this content type Some operators block specific content that Merchant might provide.
ERR_624 User not permitted to purchase this content type by provider  
ERR_625 Invalid or expired PIN code, retry attempts not available If end-user has entered invalid PIN code for more than three times final ERR_625 is displayed. No new retry attempts can be made.
ERR_630 Authentication session not found The provided charging token is not found.
ERR_635 Authentication session has expired Every authorisation session expires in 30 min. Happens when end-user does not enter a received PIN code within 30 minutes.
ERR_636 Authentication session has been cancelled The provided charging token is not found or is cancelled. The reason may be that the msisdn is blacklisted or deactivated.
ERR_637 Authorisation cannot be performed, multiple active charging consents not allowed by provider. Payments API specific error. May happen when multiple unfinished authorisation requests are being made for one specific end-user.
ERR_638 Charging amount not supported Price amount is invalid. May be in a wrong format or exceeds the maximum price range that is set by the operator.
ERR_640 Country is not supported Fortumo is yet to configure country routes to your service.
ERR_641 Operator is not supported Fortumo is yet to configure the specified carrier (the channel code you have specified in your JWT) to your service.
ERR_650 Operation refused by user Charging is not confirmed by user.
ERR_651 Invalid Terms of Service  

Pending authorisation sessions

Before any authorisation session ends up in final verified or failed status, every authorisation session is pending for an update. In case you detect a high number of authorisation sessions that remain pending, there can be several different reasons for that.

In case of PIN authorisation flow, typical issue for session to remain pending is that consumer is still waiting for their PIN code to arrive on their device and hence has not entered the code into the payment interface. While Fortumo sends out PIN codes to consumers instantly after the authorisation session has been started, it can be that due to network traffic, issues with consumer's mobile device or consumer's location PIN code is delivered with a slight delay.

With Header Enrichment authorisation flow such situation typically occurs when there is a problem with calling the carrier hosted consumer identification URL directly from consumer's device. Most common reason for such situation is that certain types of requests are blocked by consumer's browser. That can happen in case the consumer has decided to switch on extreme data savings mode for their mobile browser.

Help us improve our Merchants Portal. Was this article helpful?