Payment initialization

Every JWT that you will be including in the payment initialization URL has a following structure: header.payload.signature

JWT headers include information about the type of the token and the hashing algorithm that is used for signing the request. In Fortumo we are asking you to sign your tokens using RSA public-private key pair.

Parameter Type Required Description
alg String Mandatory Algorithm. Specified the algorithm that is used for signing the token. Fortumo supports RS256 algorithm. Example: RS256
typ String Mandatory Type. Used to declare the media type of the complete JWT. Example: JWT
Payload

The payload of the JWT includes a number of claims that provide the contextual information about the message you are transmitting. The attributes of this object determine what is being displayed to your consumer when they are directed to the payment flow, how much are they charged, whether the service is sold on one time or recurring basis etc. Payload also includes information about which type of information you expect to receive back to your server.

Parameter Type Required Description
iss String Mandatory Issuer. Identifies the principal that issued the JWT. Value must equal to your merchant ID as provided by Fortumo. Example: 93d9523134eee0f22716e49093af881a
exp Long, Unix epoch Mandatory Expiration time. Identifies the expiration time after which the JWT must not be accepted for processing. Example: 1988326400
sub String Mandatory Subject. Identifies the principal that is the subject of the JWT. Should be set as hdcb.
aud String Mandatory Audience. Identifies the recipients that the JWT is intended for. Should be set at Fortumo.
nbf Long, Unix epoch Mandatory Not before. Identifies the time before which the JWT must not be accepted for processing. Example: 1485256642
iat Long, Unix epoch Mandatory Issued at. Identifies the time at which the JWT was issued. Example: 1485256645
jti String Mandatory JWT ID. Provides a unique identifier for the JWT. Example: 00001
country_code Mandatory String, ISO 3166-1 alpha-2 Country code. Attribute that specifies the country of your consumer's carrier. Example: EE
channel_code String Optional Channel code. Attribute that specifies the channel (carrier that your consumer is using for completing a payment. Example: sandbox-ee
cuid String Optional Specific user record internal to your system. Helps you match every payment to a specific user of your service. Example: user123
item_description String Mandatory Item name. Attribute that specifies what is the service you are selling. Max length is 32 characters but should be kept as short as possible. Example: Premium access
operation_reference String Optional 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
language_code String, ISO 639-1 Optional Language code. Attribute that allows you to open the payment flow in a language that is different from the default country language, but still supported in specific country. Example: en
theme String Optional Theme ID. Attribute that allows you to specify a custom theme to be used for styling the UI. Example: my_theme_name
price Object Mandatory (top level object for one time payments, included in subscription object for subscription payments Contains attributes for specifying the price you want to charge for the service.
custom_prices Object Optional (included in price object for one-time payments Contains attributes for specifying operator and the price you want to charge for the service.
urls Object Mandatory Contains attributes for specifying URLs for integration purposes.
subscription Object Mandatory for subscription payments Contains attributes specifying details for charging users at recurring basis. Contains objects to define grace period and promotion.
grace_period Object Optional Provides you an option to override the default 48 hour grace period for the subscription. Defined in subscription object
promotion Object Optional Includes attributes defining the price and duration of a promotion period. Defined in subscription object
msisdn Integer Optional Allows you to prefill consumer MSISDN in case you have it available in your database and would like to prevent consumer from making a payment with an alternative phone number. Example: 37256565656
msisdn_edit_disabled Boolean Optional Used together with msisdn parameter disables phone number editing. When used together with msisdn and channel code then both phone number and operator selection are disabled. Example: true
return_to_merchant_text String Optional In case of successful payment, replaces the default Return to merchant text with your custom text. Max lenght is 22 characters. Example: Start listening
redirect_delay Integer Optional Defines the number of seconds after which users are automatically directed to redirect url. 0 ise used for instant redirect. Example: 30
URLs      
authorisation_callback String Optional Callback URL to be used for receiving payment authorisation callbacks. Only HTTPS allowed. Example: https://www.example.com/auth
payment_callback String Optional Callback URL to be used for receiving payment callbacks. Only HTTPS allowed. Example: https://www.example.com/payment
subscription_callback String Optional Callback URL to be used for receiving subscription callbacks. Only HTTPS allowed. Example: https://www.example.com/subs
redirect String Optional Redirect URL, specifies the URL to which endusers should be directed to after they have completed a payment. Example: https://www.example.com/payment_successful
failure_redirect String Optional Redirect URL, specifies the URL to which endusers should be directed to after payment has failed. Example: https://www.example.com/payment_failed
unsubscription_redirect String Optional Redirect URL, specifies the URL to which endusers should be directed to after they successfully unsubscribed. Example: https://www.example.com/unsub_redirect
postmessage_target String Optional Specifies the URL in which the iframe can be opened to verify sender's identity Example: https://www.example.com/
Subscription      
duration Int Mandatory Defines the number of time units in one billing cycle. Example: 30
unit String Mandatory Defines the time unit in which subscription cycle is measured. Example: Currently days and months are supported on live channels. For testing purposes you can use hours with sandbox channels only and together with cycles parameter.
cycles Int Optional Defines the number of billing cycles subscription should run. Example: 12
price Object Mandatory Contains attributes for specifying the price you want to charge for the service.
grace_period Object Optional Provides you an option to override the default 48 hour grace period for the subscription.
promotion Object Optional Includes attributes defining the price and duration of a promotion period.
Promotion      
price Object Mandatory Defines the price that is charged during promotional period.
duration Int Mandatory Defines the number of time units in one promotional period billing cycle. Example: 7
unit String Mandatory Defines the time unit in which promotional period billing cycle is measured. Example: Currently days and months are supported.
cycles Int Mandatory Defines the number of billing cycles during which a promotional price should be charged. Example: 1
free_trial_limit Int Optional Defines the limit of free promotions (promotions with price 0) that users can have. Example: 2
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

All price amounts must be specified as gross amount.

Grace period      
duration Int Mandatory Defines the number of time units for the grace period user will have access to your service after initial renewal has failed. Example: 2
unit String Mandatory Defines the time unit in which grace period duration is measured. Example: Currently days and months are supported.
Auth only flow      
activity String Optional The activity flow that the user will be passing through: one-off-payment, auth-only or subscription. Example: auth-only
item_info String Optional Describes a block with extra information about the authorisation. Example: Completing the authorisation flow allows you to get access to the service
Initialization errors

When there are invalid parameters in the JWT then HDCB will throw an error. Most errors are displayed on the payment screen and the payment flow can not continue unless the errors are fixed. Some smaller errors however are thrown in the browser console and allow the payment flow to continue but should be taken a look at never the less. Possible error messages and their description are listed below.

Error message Description
Channel not supported Channel_code is not enabled for this merchant
Could not read public key Public key configured is incorrect
Country not specified Country_code missing from JWT
Country not supported Country_code specified is not available for this merchant
Error parsing merchant secret Merchant secret is incorrect
Internal error on mapping token parameters. Incorrect token parameters
Invalid request: no callbacks specified Callback urls are missing from JWT
Invalid request: postmessage_target url does not meet the requirements postmessage_target url is misconfigured
Invalid request: signature mismatch or invalid JWT Private key does not match configured public key or JWT is invalid
Invalid request: token missing Token is missing from payment url
Invalid subscription integration parameters Subscription paramaters are incorrect
Item description length must not exceed 32 characters. Item_description exceeds max length of 32 character
Item description not specified Item_description parameter missing
Item info length must not exceed 400 characters. Item_info exceeds max length of 400 character
JWT expired exp parameter is in the past
JWT is used before valid time nbf parameter is set in the future
JWT signature verification failed Merchant private key and configured public key do not match
MSISDN not specified for msisdn_edit_disabled User phone number not specified while editing phone number is disabled
Malformed JWT JWT is in incorrect format
Merchant UUID is invalid Iss paramater contains invalid merchant ID
Merchant not specified Iss parameter is missing
Merchant secret can not be empty Missing private key
Merchant secret configuration missing for specified merchant Public key has not been configured
Unsupported JWT format/configuration JWT is invalid
Could not locate theme, falling back to default Theme specified does not exist
Help us improve our Merchants Portal. Was this article helpful?