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, whether the payment is for carrier billing or digital wallets, 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 or ewallet. Example: EE |
| channel_code | String | Optional | Channel code. Attribute that specifies the channel (carrier or ewallet that your consumer is using for completing a payment.) Example: sandbox-ee, wallet-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 |
| failure_redirect_delay | Integer | Optional | Defines the number of seconds after which users are automatically redirected from the error screen. 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 without URL forwarding. Example: https://www.example.com/auth |
| payment_callback | String | Optional | Callback URL to be used for receiving payment callbacks. Only HTTPS allowed without URL forwarding. Example: https://www.example.com/payment |
| subscription_callback | String | Optional | Callback URL to be used for receiving subscription callbacks. Only HTTPS allowed without URL forwarding. 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 with lower value. |
| 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 hours and days 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 Unified SDK 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 validation failed | JWT is invalid |
| 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 |
| Could not locate theme, falling back to default | Theme specified does not exist |